diff --git a/.github/RELEASE_NOTICE.md b/.github/RELEASE_NOTICE.md
index 9a848b629..0a27def77 100644
--- a/.github/RELEASE_NOTICE.md
+++ b/.github/RELEASE_NOTICE.md
@@ -54,3 +54,44 @@ The server edition now enforces a **25-token quota per signed-in user** on top o
 - Server edition: a user at 25 tokens gets a `409 Conflict` from `POST /user/tokens` that names *their* quota — permanently deleting one of their unused tokens frees a slot — so one user can no longer take the whole pool. The 100-record deployment cap remains and every stored token still counts toward it, so a deployment whose stored records add up to 100 refuses the next token for everyone until an administrator frees records; a caller who is still under their own quota then gets the `409` that says the limit is shared and points at an administrator (the quota is checked first, so a user already at 25 sees their own-quota message instead). A user who already holds more than 25 tokens keeps them; they cannot create another until they are back under the quota.
 - Personal edition: every token is ownerless, so the quota does not apply and the 100-token limit is unchanged.
 - No configuration change is needed. Details: [agent tokens](https://docs.mcpproxy.app/features/agent-tokens/).
+
+## Server edition: `/mcp` always requires a credential
+
+When `server_edition.enabled` is true, `/mcp` now behaves as if `require_mcp_auth` were `true` whatever the file says (spec 107, FR-029). Before this release a server-edition deployment with `require_mcp_auth` off (the default) handed every unauthenticated `/mcp` caller an **anonymous administrator** context.
+
+- No credential → `401`. A session cookie or a user JWT on `/mcp` → `401` (they were never valid there; they are no longer silently promoted). Agent tokens (`mcp_agt_…`), the global API key and the Unix socket work exactly as before.
+- An explicit `"require_mcp_auth": false` is **not** a validation error, so no deployment fails to boot on upgrade. It logs one notice — `require_mcp_auth: false is overridden to true because server_edition.enabled is true` — and `mcpproxy doctor` reports the same line. Remove the key, or set it to `true`, to silence both.
+- Personal edition: unchanged; `require_mcp_auth` keeps its configured value.
+- If an AI client reached `/mcp` on a server-edition deployment without any credential, it now needs an agent token: each user mints one from the Web UI or `POST /api/v1/user/tokens` and sends it as `Authorization: Bearer mcp_agt_…`.
+
+## `trusted_proxies` now gates every forwarded header — behind an ingress, set it or `public_url`
+
+`X-Forwarded-For`, `X-Real-IP`, `X-Forwarded-Proto` and `X-Forwarded-Host` used to be believed from **any** peer: a direct client could choose its own session IP, force the OAuth callback to `https`, or move it to another host. They are now honoured only when the request's `RemoteAddr` is inside the new top-level `trusted_proxies` list (CIDRs or addresses; env `MCPPROXY_TRUSTED_PROXIES`, comma-separated; hot-reloadable; both editions), taking the right-most hop that is not itself a trusted proxy as the client IP. The default is empty — **trust nobody** (FR-027).
+
+**What changes behind a reverse proxy or ingress if you do nothing**
+
+- The OAuth `redirect_uri` sent to your IdP is built from the listener's own scheme and `Host` — typically `http://…` — instead of the ingress's `X-Forwarded-Proto: https`. Your IdP's exact-match registration then refuses the callback and every SSO login fails.
+- The session's recorded IP, the audit `client.ip`, the connect-flow base URL and the swagger server URL all show the ingress's address, not the user's.
+
+**Fix (either one)**
+
+- Set `server_edition.public_url` to the origin users reach (`https://mcp.example.com`; env `MCPPROXY_PUBLIC_URL`). It becomes the sole source of the callback URL (`<public_url>/api/v1/auth/callback`), the connect-flow base URL and the cookie `Secure` decision; `Host` and `X-Forwarded-*` are ignored for those (FR-025). When it is unset and the listener is not loopback — the published image listens on `0.0.0.0:8080` — boot logs a warning and `mcpproxy doctor` reports it; it is not a validation error.
+- Or list your ingress in `trusted_proxies` (`["10.0.0.0/8"]`, `["fd00::/8"]`, a single address). Do both if you also want the real client IP in sessions and audit lines.
+- An invalid entry (`trusted_proxies[0] "…" is not a valid CIDR or IP address`) is a validation error at load and on `PATCH /api/v1/config`. No forwarded header ever feeds the local/remote or administrator classification. Details: [reverse proxy](https://docs.mcpproxy.app/operations/reverse-proxy/), [config file](https://docs.mcpproxy.app/configuration/config-file/), [environment variables](https://docs.mcpproxy.app/configuration/environment-variables/).
+
+**Session cookie** — `server_edition.session_cookie_secure` is new: `auto` (default) sets `Secure` when the effective scheme is https (`public_url`, in-process TLS, or `X-Forwarded-Proto: https` from a *trusted* proxy), `true` forces it, `false` disables it. Earlier releases never set `Secure`. Validation refuses `false` together with an `https://` `public_url` or in-process TLS; an explicit `false` elsewhere is honoured with one boot warning and a `mcpproxy doctor` finding. `HttpOnly` and `SameSite=Lax` are unchanged (FR-026).
+
+**Post-login redirect** — `redirect_uri` on `GET /api/v1/auth/login` is accepted only as a same-origin path (a single leading `/`, no scheme, host, `//`, `/\`, backslash or control character); anything else lands on `/ui/` and the login's `auth_event` line carries `redirect_rejected`. The Web UI is unaffected (FR-028).
+
+## Server edition: generic `oidc` identity provider
+
+`server_edition.oauth.provider` accepts `oidc` next to `google`, `github` and `microsoft`, so Okta, Entra ID, Keycloak, Authentik, Auth0 and any other OpenID Connect provider work without provider-specific code (FR-020). The three existing providers behave exactly as before.
+
+- **Configuration**: `issuer_url` (required; `https`, or `http` only for a loopback host **and** `allow_insecure_issuer: true`), `scopes` (default `["openid","profile","email"]`; `openid` is added if missing), `groups_claim` (default `"groups"`), `email_verified_policy` (default `refuse_false`), `display_name` (login-button label; falls back to the provider name). `client_id`/`client_secret` stay `${env:}`-referenced; there is no environment variable for nested keys. `authorization_endpoint`, `token_endpoint`, `jwks_uri` and `userinfo_endpoint` come from `<issuer_url>/.well-known/openid-configuration`, fetched lazily on the first login and cached, so boot and readiness never wait on the IdP.
+- **Every ID token is verified before any claim is read**: signature against the issuer's JWKS (RS/PS/ES families only — never `none`, never HS*), exact `iss`, `aud`/`azp`, `exp`/`nbf`/`iat` with 60 s skew, and a per-login `nonce`. Discovered endpoints must be absolute `https` (same loopback exception), and the back-channel client never follows a redirect: the client secret and code are still sent to your configured token endpoint (and a bearer token to your configured userinfo endpoint) as normal, but a 3xx answer from any of the token, JWKS or userinfo endpoints refuses the login instead of being followed — so a compromised or misconfigured endpoint cannot redirect that credential to another host (FR-021).
+- **`email_verified_policy`** — `refuse_false` (default) refuses a login whose ID token says `email_verified: false` and admits one where the claim is absent; `require_true` also refuses an absent claim; `ignore` admits both. Pick `require_true` when your IdP always sets the claim; `refuse_false` exists so providers that omit it still work out of the box. `email` itself is required (`email_missing` otherwise).
+- **Groups are captured**: on every successful `oidc` login the user record stores the groups claim from the verified ID token (or from `userinfo` when the token lacks it — accepted only when the userinfo `sub` equals the token's `sub`), replacing the previous list wholesale with a `groups_updated_at` timestamp; a missing or malformed claim stores `[]` and logs `groups_claim_missing`. `google`/`github`/`microsoft` logins store `[]`. `GET /api/v1/auth/me` returns your groups; `GET /api/v1/admin/users` shows every user's groups and `groups_updated_at`. Storing groups has no authorisation effect on its own; they are the input to the server-edition `access` grant (FR-008).
+- **Subject binding**: a user record now remembers `(provider, provider_subject_id)` and refreshes both on every login. Same provider, same email, **different** subject is refused (`subject_mismatch`), so an IdP email collision cannot take over an existing account; an administrator re-arms the binding for a genuinely re-created IdP account by disabling and re-enabling the user — the next successful login rebinds (FR-023).
+- **Refusals are uniform**: every denied login renders one generic `403` page ("Sign-in was not permitted") with a reference id; the reason (`email_unverified`, `subject_mismatch`, `state_invalid`, …) reaches only the server log and the `auth_event` line under that id. IdP-side failures (`discovery_failed`, `provider_error`) and proxy-side failures after verification (`internal_error`) render a `503` "Sign-in is temporarily unavailable" instead, so an outage is never shown as "not permitted" (FR-024).
+- **Login page label and edition probe**: public `GET /api/v1/auth/provider` returns only `{"display_name": "…"}` — never the issuer, client id, tenant, scopes or domains — so the Web UI labels the sign-in button and detects the edition before login; the personal build answers `404` (FR-030).
+- Guide: [multi-user authentication](https://docs.mcpproxy.app/development/server-edition-multiuser-auth/).
diff --git a/ROADMAP.md b/ROADMAP.md
index f12b3013b..c857ba989 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -423,16 +423,18 @@ graph LR
   sso_pr_b_oidc_front_door --> sso_pr_c_group_allowlist
   sso_pr_c_group_allowlist --> sso_pr_d_audit_line
 
+  classDef done fill:#1f7a1f,stroke:#0d3d0d,color:#ffffff;
   classDef in_progress fill:#1f6feb,stroke:#0b3d91,color:#ffffff;
   classDef todo fill:#6e7781,stroke:#3d4248,color:#ffffff;
-  class sso_pr_a_freeze_cut in_progress;
-  class sso_pr_b_oidc_front_door,sso_pr_c_group_allowlist,sso_pr_d_audit_line todo;
+  class sso_pr_a_freeze_cut done;
+  class sso_pr_b_oidc_front_door in_progress;
+  class sso_pr_c_group_allowlist,sso_pr_d_audit_line todo;
 ```
 
 | Task | Status | Refs |
 | --- | --- | --- |
-| PR-A freeze/cut latent code + config normaliser + per-owner token cap (US5, US6) | 🔵 In progress | #1287 |
-| PR-B generic OIDC provider + front door behind ingress + telemetry v13 (US2, US7) | ⚪ Todo | — |
+| PR-A freeze/cut latent code + config normaliser + per-owner token cap (US5, US6) | 🟢 Done | #1287 |
+| PR-B generic OIDC provider + front door behind ingress + telemetry v13 (US2, US7) | 🔵 In progress | #1292 |
 | PR-C one entitlement predicate, group grants, tenant Web UI session principal (US1, US4) | ⚪ Todo | — |
 | PR-D attributable JSONL audit line + auth_event + config/doctor/metrics (US3) | ⚪ Todo | — |
 
@@ -894,7 +896,7 @@ graph LR
 | Telemetry v7: honest funnel + churn instrumentation | In progress | P1 | — | [080-telemetry-v7-churn](./specs/080-telemetry-v7-churn/) |  |
 | MCP protocol upgrade to 2026-07-28 revision | In progress | P1 | 19/81 (23%) | [058-mcp-2026-upgrade](./specs/058-mcp-2026-upgrade/) |  |
 | Planning/docs truth automation | In progress | P2 | — |  |  |
-| Spec 107 server edition SSO front door hardened for real IdPs | In progress | P2 | 32/126 (25%) | [107-server-edition-sso-hardening](./specs/107-server-edition-sso-hardening/) |  |
+| Spec 107 server edition SSO front door hardened for real IdPs | In progress | P2 | 69/126 (55%) | [107-server-edition-sso-hardening](./specs/107-server-edition-sso-hardening/) |  |
 | Discovery-quality eval harness (Spec 065 second half) | In progress | P3 | — | [065-evaluation-foundation](./specs/065-evaluation-foundation/) |  |
 | tpa-db: versioned TPA signature database for the offline scanner | Todo | P1 | — | [101-tpa-db](./specs/101-tpa-db/) |  |
 | Auto routing mode: budget-fitted tool surface per session (spec 104) | Todo | P1 | — | [104-auto-routing-mode](./specs/104-auto-routing-mode/) |  |
@@ -1036,4 +1038,4 @@ Legend: `shipped` ≥95% checked · `in-flight` 1–94% · `drafted` 0% · `—`
 | [104-auto-routing-mode](./specs/104-auto-routing-mode/) | — | — |
 | [105-agent-scope-hardening](./specs/105-agent-scope-hardening/) | `drafted` | 0/109 (0%) |
 | [106-security-residual-fixes](./specs/106-security-residual-fixes/) | `shipped` | 18/19 (95%) |
-| [107-server-edition-sso-hardening](./specs/107-server-edition-sso-hardening/) | `in-flight` | 32/126 (25%) |
+| [107-server-edition-sso-hardening](./specs/107-server-edition-sso-hardening/) | `in-flight` | 69/126 (55%) |
diff --git a/cmd/mcpproxy/listen_flag_test.go b/cmd/mcpproxy/listen_flag_test.go
index e38f14c66..03e1c791e 100644
--- a/cmd/mcpproxy/listen_flag_test.go
+++ b/cmd/mcpproxy/listen_flag_test.go
@@ -55,7 +55,7 @@ func TestLoadConfig_ListenFlag(t *testing.T) {
 				t.Fatal(err)
 			}
 
-			cfg, err := loadConfig(cmd)
+			cfg, _, err := loadConfig(cmd)
 			if err != nil {
 				t.Fatalf("loadConfig: %v", err)
 			}
diff --git a/docs/configuration.md b/docs/configuration.md
index d9df0f076..95f4acfba 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -654,6 +654,7 @@ See [OAuth Documentation](mcp-go-oauth.md) for complete details.
 {
   "api_key": "your-secret-api-key",
   "trusted_hosts": ["mcp.example.com"],
+  "trusted_proxies": ["127.0.0.1"],
   "read_only_mode": false,
   "disable_management": false,
   "allow_server_add": true,
@@ -665,6 +666,7 @@ See [OAuth Documentation](mcp-go-oauth.md) for complete details.
 |-------|------|---------|-------------|
 | `api_key` | string | Auto-generated | API key for REST API authentication. Required; if empty, one is auto-generated and enforced (logged on startup) |
 | `trusted_hosts` | string[] | `[]` | Non-loopback `Host` header values accepted on loopback listeners (reverse-proxy deployments). See below |
+| `trusted_proxies` | string[] | `[]` (trust nobody) | CIDRs or IP addresses whose `X-Forwarded-For` / `X-Real-IP` / `X-Forwarded-Proto` / `X-Forwarded-Host` headers are honoured; any other peer's forwarded headers are ignored and `RemoteAddr` is used. Env `MCPPROXY_TRUSTED_PROXIES`. Hot-reloadable. Invalid entry: `trusted_proxies[N] "value" is not a valid CIDR or IP address` (boot, PATCH and apply). See [Reverse Proxy Deployment](operations/reverse-proxy.md#trusted_proxies-forwarded-headers) |
 | `read_only_mode` | boolean | `false` | Prevent all configuration modifications |
 | `disable_management` | boolean | `false` | Disable server management operations (restart, enable, disable) |
 | `allow_server_add` | boolean | `true` | Allow adding new servers via API/tools |
@@ -1627,6 +1629,8 @@ Many configuration options can be overridden via environment variables:
 |----------------------|--------------|-------------|
 | `MCPPROXY_LISTEN` / `MCPP_LISTEN` | `listen` | Network binding address |
 | `MCPPROXY_API_KEY` | `api_key` | API key for authentication (empty values trigger auto-generation; auth remains enabled) |
+| `MCPPROXY_TRUSTED_HOSTS` | `trusted_hosts` | Comma-separated `Host` allowlist for loopback listeners behind a reverse proxy |
+| `MCPPROXY_TRUSTED_PROXIES` | `trusted_proxies` | Comma-separated CIDRs/IPs whose `X-Forwarded-*` headers are honoured |
 | `MCPPROXY_TLS_ENABLED` | `tls.enabled` | Enable HTTPS/TLS |
 | `MCPPROXY_TLS_REQUIRE_CLIENT_CERT` | `tls.require_client_cert` | Enable mTLS |
 | `MCPPROXY_CERTS_DIR` | `tls.certs_dir` | Custom certificates directory |
diff --git a/docs/configuration/config-file.md b/docs/configuration/config-file.md
index a26297413..5a04dc879 100644
--- a/docs/configuration/config-file.md
+++ b/docs/configuration/config-file.md
@@ -59,8 +59,9 @@ MCPProxy uses a JSON configuration file located at `~/.mcpproxy/mcp_config.json`
 | `listen` | string | `127.0.0.1:8080` | Address and port to listen on |
 | `data_dir` | string | `~/.mcpproxy` | Directory for data storage |
 | `api_key` | string | auto-generated | API key for REST API authentication |
-| `trusted_hosts` | string[] | `[]` | Non-loopback `Host` header values accepted on a loopback listener. Needed when running behind a reverse proxy — see [Reverse Proxy Deployment](/operations/reverse-proxy) |
-| `require_mcp_auth` | boolean | `false` | Require an API key on the `/mcp` endpoint (off by default for client compatibility). Enable when exposing MCPProxy beyond localhost |
+| `trusted_hosts` | string[] | `[]` | Non-loopback `Host` header values accepted on a loopback listener. Needed when running behind a reverse proxy — see [Reverse Proxy Deployment](/operations/reverse-proxy). This is DNS-rebinding protection only; it is **not** the control for forwarded headers (see `trusted_proxies`) |
+| `trusted_proxies` | string[] | `[]` (trust nobody) | CIDRs or IP addresses whose `X-Forwarded-For`, `X-Real-IP`, `X-Forwarded-Proto` and `X-Forwarded-Host` headers are believed. Headers from any other peer are ignored and the direct `RemoteAddr` is used. Env `MCPPROXY_TRUSTED_PROXIES` (comma list). Live (hot-reload, no restart). Validation: `trusted_proxies[N] "value" is not a valid CIDR or IP address` — refused identically at boot, `PATCH /api/v1/config` and `/config/apply`. See [Reverse Proxy Deployment](/operations/reverse-proxy#trusted_proxies-forwarded-headers) |
+| `require_mcp_auth` | boolean | `false` | Require an API key on the `/mcp` endpoint (off by default for client compatibility). Enable when exposing MCPProxy beyond localhost. **Server edition:** forced to `true` whenever `server_edition.enabled` is `true` — an explicit `false` is not an error, but boot logs `require_mcp_auth: false is overridden to true because server_edition.enabled is true` and `mcpproxy doctor` reports the same finding |
 | `enable_socket` | boolean | `true` | Enable Unix socket/named pipe for local communication |
 
 ### HTTP Server Timeouts
@@ -244,6 +245,125 @@ Full reference — validation rules, metrics, and which origins are limited —
 lives in [`docs/configuration.md`](https://github.com/smart-mcp-proxy/mcpproxy-go/blob/main/docs/configuration.md#concurrency-limits--request-queueing)
 in the repository.
 
+### Server Edition (`server_edition`) {#server-edition}
+
+The `server_edition` block configures multi-user SSO in the **Server edition**
+(`mcpproxy-server`, distributed as the Docker image only — no `.deb`/tar.gz).
+The Personal edition carries the
+block as opaque JSON: it is preserved key-for-key and value-for-value through load, save and
+`PATCH /api/v1/config`, never validated and never acted on. The block is not
+part of the OpenAPI schema; this section is its reference. Development notes
+and the REST endpoints live in
+[Server Multi-User Authentication](/development/server-edition-multiuser-auth).
+
+```json
+{
+  "listen": "0.0.0.0:8080",
+  "trusted_proxies": ["10.42.0.0/16"],
+  "server_edition": {
+    "enabled": true,
+    "admin_emails": ["admin@example.com"],
+    "public_url": "https://mcp.example.com",
+    "session_cookie_secure": "auto",
+    "session_ttl": "24h",
+    "bearer_token_ttl": "24h",
+    "credential_encryption_key": "${env:MCPPROXY_CRED_KEY}",
+    "oauth": {
+      "provider": "oidc",
+      "issuer_url": "https://login.example.com/realms/team",
+      "client_id": "mcpproxy",
+      "client_secret": "${env:OIDC_CLIENT_SECRET}",
+      "scopes": ["openid", "profile", "email", "groups"],
+      "groups_claim": "groups",
+      "email_verified_policy": "refuse_false",
+      "display_name": "Example SSO",
+      "allowed_domains": ["example.com"]
+    }
+  }
+}
+```
+
+**Reload column.** *Restart* keys are bound when the login handler and session
+store are built: an edit is reported by the hot-reloader as
+`server_edition` with `RequiresRestart=true` (`server_edition settings are
+bound at startup`) and takes effect on the next start. *Live* keys apply on the
+next request after the file reload lands. Validation messages are the exact
+strings emitted at boot, by `PATCH /api/v1/config` and by `/config/apply`
+(all three refuse the same input the same way).
+
+| Key | Type | Default | Reload | Validation / notes |
+|-----|------|---------|--------|--------------------|
+| `enabled` | boolean | `false` | Restart | Turns the block on. When `true`: `admin_emails` and `oauth` become required, `/mcp` requires a credential regardless of `require_mcp_auth` (agent tokens, the API key and the socket are unchanged; a session cookie or user JWT is **never** an MCP credential) |
+| `admin_emails` | string[] | — (required when enabled) | **Live** | `server_edition.admin_emails must contain at least one admin email`. Case-insensitive match; the single source of the admin role, re-derived on every request (a removed admin is demoted on their next request without re-login) |
+| `public_url` | string | `""` | Restart | Absolute origin only — `server_edition.public_url must be an absolute origin (scheme://host[:port]) with no path`. Env alias `MCPPROXY_PUBLIC_URL` (the only nested `server_edition.*` key with one; the Personal edition ignores it). When set it is the **sole** source of the IdP `redirect_uri` (`<public_url>/api/v1/auth/callback`), of the connect-flow base URL and of the scheme behind the `Secure` cookie decision — `Host` and `X-Forwarded-*` are ignored for those. Unset on a non-loopback listener (the Docker image listens on `0.0.0.0:8080`) is a boot warning + `mcpproxy doctor` finding, never an error |
+| `session_cookie_secure` | `auto` \| `true` \| `false` | `auto` | Restart | `auto` = `Secure` when the effective scheme is https (an https `public_url`, in-process TLS, or `X-Forwarded-Proto: https` from a peer in `trusted_proxies`). `false` with an https `public_url` or `tls.enabled` is refused: `server_edition.session_cookie_secure=false cannot be combined with an https public_url or tls.enabled`. An explicit `false` elsewhere is honoured with one boot warning + `doctor` finding (loopback/test deployments only). Any other value: `server_edition.session_cookie_secure must be one of: auto, true, false`. `HttpOnly` and `SameSite=Lax` are always set |
+| `session_ttl` | duration | `24h` | Restart | `server_edition.session_ttl must be positive` |
+| `bearer_token_ttl` | duration | `24h` | Restart | `server_edition.bearer_token_ttl must be positive`. Lifetime of user JWTs minted by `POST /api/v1/auth/token` (REST/CLI only) |
+| `credential_encryption_key` | string | env `MCPPROXY_CRED_KEY` | Restart | Encrypts per-user upstream credentials at rest (`oauth_connect` broker). An explicit value wins over the environment. Secret — keep it as `${env:...}` or set only the variable; it never appears in the Settings UI |
+| `store_idp_tokens` | boolean | `false` | — | **Deprecated no-op.** Accepted so older files load; `true` logs `server_edition.store_idp_tokens is deprecated and no longer stores IdP tokens; remove it` once at load. See [IdP Token Storage](/features/idp-token-storage) |
+| ~~`max_user_servers`~~, ~~`workspace_idle_timeout`~~ | — | — | never reported | **Removed.** A file that still carries them loads: each is dropped with one startup diagnostic, `server_edition.max_user_servers is no longer supported and was ignored` (likewise `workspace_idle_timeout`), and the next write-back omits them. `PATCH /api/v1/config` and `/config/apply` refuse them with the same text |
+| `oauth` | object | — (required when enabled) | Restart | `server_edition.oauth configuration is required when server_edition is enabled`. Every `oauth.*` edit is restart-pinned (`server_edition.oauth.* is bound at login handler construction`) |
+| `oauth.provider` | `google` \| `github` \| `microsoft` \| `oidc` | — | Restart | `server_edition.oauth.provider must be one of: google, github, microsoft, oidc (got: X)`. The three legacy providers keep their provider-specific exchange exactly as before (no nonce, no JWKS step, `client_secret_post`, groups always `[]`); `oidc` is the generic OpenID Connect Discovery provider with a verified ID token. The front-door keys (`public_url`, `session_cookie_secure`, `trusted_proxies`, forced MCP auth, subject binding, relative post-login redirect) apply to all four |
+| `oauth.client_id` | string | — | Restart | `server_edition.oauth.client_id is required` |
+| `oauth.client_secret` | string (`${env:...}`) | — | Restart | `server_edition.oauth.client_secret is required`. Masked in every API response and log; never a Settings row — reference a variable |
+| `oauth.tenant_id` | string | `common` | Restart | `microsoft` only (multi-tenant `common` when unset); ignored by the other providers |
+| `oauth.allowed_domains` | string[] | `[]` = allow all | Restart | Email-domain allowlist, matched case-insensitively after login. Applies to every provider |
+| `oauth.issuer_url` | string | — | Restart | **`oidc` only, required**: `server_edition.oauth.issuer_url is required when provider is oidc`. Must be absolute `https`; `http` is admitted only for a loopback host together with `allow_insecure_issuer: true` — `server_edition.oauth.issuer_url must use https (http is allowed only for a loopback host with allow_insecure_issuer: true)`. Discovery reads `<issuer_url>/.well-known/openid-configuration` lazily on the first login (never at boot — readiness does not depend on the IdP), and the document's `issuer` must equal the configured value **byte for byte** (a trailing slash or path difference refuses the login as `discovery_failed`; the log line names both values) |
+| `oauth.allow_insecure_issuer` | boolean | `false` | Restart | Development toggle for an in-process or loopback fake IdP: admits a plain-`http` issuer and plain-`http` discovered endpoints **only** when their host is loopback. Non-loopback `http` is refused regardless. Raw-JSON only — deliberately has no Settings row |
+| `oauth.scopes` | string[] | `["openid","profile","email"]` | Restart | `oidc` only. `openid` is appended when missing. Add whatever your IdP needs for the groups claim (Okta: `groups`; see the table below) |
+| `oauth.groups_claim` | string | `"groups"` | Restart | `oidc` only. Name of the ID-token (then userinfo) claim carrying group memberships. Accepted shapes: a flat JSON array of strings or a single string; anything else is treated as absent. Compared as exact strings by the group → server map |
+| `oauth.email_verified_policy` | `refuse_false` \| `require_true` \| `ignore` | `refuse_false` | Restart | `server_edition.oauth.email_verified_policy must be one of: refuse_false, require_true, ignore`. See the cost note below |
+| `oauth.display_name` | string | provider family name | Restart | Login-button label; at most 64 characters (`server_edition.oauth.display_name must be at most 64 characters`). It is the **only** field returned by the public `GET /api/v1/auth/provider` probe (never the issuer, client id, tenant, scopes or domains) |
+
+#### `email_verified_policy` — what each value costs
+
+| Value | `email_verified: false` | claim absent | Use when |
+|-------|------------------------|--------------|----------|
+| `refuse_false` (default) | refused (`email_unverified`) | login proceeds | Most IdPs. Refuses only what the IdP explicitly marks unverified |
+| `require_true` | refused | refused | The IdP always emits the claim and every account must be verified — unverified or self-registered accounts can never pass `allowed_domains` |
+| `ignore` | ignored | ignored | The IdP never emits the claim. **Cost:** a self-asserted email is trusted, so an attacker who can register `anything@example.com` at the IdP passes an `allowed_domains: ["example.com"]` check. Compensate at the IdP (verified-only registration) or with the group map |
+
+#### Groups claim by identity provider
+
+The proxy compares group strings exactly and case-sensitively. What the claim
+carries is decided by the IdP:
+
+| IdP | `groups_claim` | Values | Notes |
+|-----|----------------|--------|-------|
+| Keycloak | `groups` | `/path/names` (e.g. `/engineering/backend`) | Needs a **Group Membership** mapper on the client scope; untick *Full group path* to get bare names |
+| Okta | `groups` | group names | Add the `groups` scope to `scopes` and a groups claim filter to the authorization server |
+| Auth0 | `https://example.com/groups` | whatever your Action emits | Custom claims must be namespaced (a URL-shaped name); set it verbatim |
+| Authentik | `groups` | group names | Shipped in the default `profile` scope, no extra mapping |
+| Microsoft Entra ID | `groups` | group **object ids** (GUIDs) | Use the GUIDs in the map, or app roles. Above ~200 groups Entra omits the claim and sends an overage marker (`_claim_names`); the proxy treats that as **no groups** (`[]`) and logs a warning |
+
+Groups are read from the verified ID token first; only when the token lacks
+the claim is `userinfo_endpoint` consulted once, and only if its `sub` equals
+the token's `sub`. A claim absent from both means `[]` (fail closed: the user
+still logs in and receives only the default grant) with one warning naming the
+user id and the claim looked for — never the token.
+
+#### `public_url` and `trusted_proxies` in a container
+
+```text
+browser ──https──▶ ingress / TLS terminator (10.42.0.7) ──http──▶ mcpproxy-server 0.0.0.0:8080
+                    sets X-Forwarded-Proto: https
+                         X-Forwarded-For: <client ip>
+                         Host: 127.0.0.1:8080 (or the public host)
+```
+
+| Setting | What it decides | If you leave it out |
+|---------|-----------------|---------------------|
+| `server_edition.public_url: "https://mcp.example.com"` | The exact `redirect_uri` registered at the IdP, the connect-flow base URL and the `Secure` cookie decision — from configuration, not from `Host`/`X-Forwarded-*` | The callback URL is derived from the request: the IdP's exact-match `redirect_uri` registration is then the only guard against a rewritten `Host`, and you get a boot warning + `doctor` finding on a non-loopback listener |
+| `trusted_proxies: ["10.42.0.0/16"]` (the ingress's source range) | Which peers may set the forwarded scheme, host and client IP — for the session IP, the per-request client IP tagged for attribution and, without `public_url`, the callback scheme | Every forwarded header is ignored: the session IP is the ingress's address, and without `public_url` the callback is `http://…` (`redirect_uri_mismatch` at the IdP) |
+| `session_cookie_secure: "auto"` (default) | `Secure` when the effective scheme is https | — |
+
+Set both keys in the container. `trusted_hosts` is unrelated to this door: it
+is DNS-rebinding protection for **loopback** listeners and never runs on
+`0.0.0.0:8080`. When `public_url` is https but the callback reaches the proxy
+over plain http, the login proceeds and one warning is logged
+(`public_url is https but the OAuth callback arrived over http … check the
+ingress forwards X-Forwarded-Proto from an address in trusted_proxies`).
+
 ### MCP Servers
 
 See [Upstream Servers](/configuration/upstream-servers) for detailed server configuration.
@@ -252,7 +372,7 @@ See [Upstream Servers](/configuration/upstream-servers) for detailed server conf
 
 MCPProxy watches the configuration file for changes and automatically reloads when modifications are detected. No restart is required for most configuration changes.
 
-Exceptions that require a restart include `listen`, `data_dir`, `api_key`, the TLS block, and the three `http_*_timeout` options.
+Exceptions that require a restart include `listen`, `data_dir`, `api_key`, the TLS block, the three `http_*_timeout` options, and — in the Server edition — every `server_edition` key except `admin_emails` (see [Server Edition](#server-edition)). `trusted_proxies` is live.
 
 ## Environment Variable Overrides
 
diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md
index c50af6da6..bbad1e7a5 100644
--- a/docs/configuration/environment-variables.md
+++ b/docs/configuration/environment-variables.md
@@ -38,6 +38,7 @@ Environment variables are useful for CI/CD environments or temporary overrides d
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `MCPPROXY_TRUSTED_HOSTS` | Comma-separated `Host` header allowlist for loopback listeners behind a reverse proxy (see [Reverse Proxy Deployment](/operations/reverse-proxy)) | - |
+| `MCPPROXY_TRUSTED_PROXIES` | Comma-separated CIDRs or IP addresses whose `X-Forwarded-For` / `X-Real-IP` / `X-Forwarded-Proto` / `X-Forwarded-Host` headers are honoured (overrides `trusted_proxies`). Any other peer's forwarded headers are ignored. An entry that is neither a CIDR nor an IP is refused at boot with `trusted_proxies[N] "value" is not a valid CIDR or IP address`, exactly like a file value. See [trusted_proxies](/operations/reverse-proxy#trusted_proxies-forwarded-headers) | - (trust nobody) |
 | `MCPPROXY_TLS_ENABLED` | Enable TLS/HTTPS | `false` |
 | `MCPPROXY_TLS_CERT` | Path to TLS certificate | - |
 | `MCPPROXY_TLS_KEY` | Path to TLS private key | - |
@@ -52,6 +53,18 @@ Environment variables are useful for CI/CD environments or temporary overrides d
 |----------|-------------|---------|
 | `MCPPROXY_DISABLE_OAUTH` | Disable OAuth for testing | `false` |
 
+### Server Edition (SSO)
+
+These are read only by the Server edition binary (`mcpproxy-server`, the Docker
+image); the Personal edition ignores them. Every other `server_edition.*` key is
+file-only — reference secrets with `${env:NAME}` inside the config file instead
+(see [Server Edition](./config-file.md#server-edition)).
+
+| Variable | Config key | Description | Default |
+|----------|------------|-------------|---------|
+| `MCPPROXY_PUBLIC_URL` | `server_edition.public_url` | Absolute origin users reach the deployment at (`https://mcp.example.com`, no path). Sole source of the IdP `redirect_uri`, the connect-flow base URL and the `Secure` cookie decision when set. Overrides the file value; validated with the same message (`server_edition.public_url must be an absolute origin (scheme://host[:port]) with no path`) | - |
+| `MCPPROXY_CRED_KEY` | `server_edition.credential_encryption_key` | Key for encrypting per-user upstream credentials at rest (the `oauth_connect` broker — see [Auth Broker](/features/auth-broker)). Used only when the config key is empty; an explicit config value wins | - |
+
 ### Browser Detection
 
 These variables control browser behavior for OAuth flows:
diff --git a/docs/development/server-edition-multiuser-auth.md b/docs/development/server-edition-multiuser-auth.md
index 87bdd51a2..bde34e50f 100644
--- a/docs/development/server-edition-multiuser-auth.md
+++ b/docs/development/server-edition-multiuser-auth.md
@@ -1,25 +1,41 @@
 ---
 title: "Server Multi-User Authentication"
 sidebar_label: "Server Multi-User Auth"
-description: "OAuth-based multi-user authentication for the server edition with Google, GitHub, or Microsoft identity providers."
+description: "SSO multi-user authentication for the server edition: generic OIDC (Keycloak, Okta, Auth0, Authentik, Entra) with JWKS-verified ID tokens, plus the Google, GitHub and Microsoft legacy providers, behind a TLS-terminating ingress."
 ---
 
-# Server Multi-User Authentication (Spec 024)
+# Server Multi-User Authentication (Spec 024, hardened by Spec 107)
 
-Server edition supports OAuth-based multi-user authentication with Google, GitHub, or Microsoft identity providers. All server code is behind `//go:build server`; the personal edition is unaffected.
+Server edition supports SSO multi-user authentication with four identity
+providers: the generic **`oidc`** provider (any OpenID Connect Discovery issuer —
+Keycloak, Okta, Auth0, Authentik, Microsoft Entra ID — with a JWKS-verified ID
+token and a groups claim) and the three legacy providers **`google`**,
+**`github`** and **`microsoft`**. All server code is behind `//go:build server`;
+the personal edition is unaffected. The complete key table with defaults,
+validation text and reload behaviour is
+[Server Edition](../configuration/config-file.md#server-edition); this page is
+the developer view.
 
 ## Server Configuration
 
 ```json
 {
+  "listen": "0.0.0.0:8080",
+  "trusted_proxies": ["10.42.0.0/16"],
   "server_edition": {
     "enabled": true,
     "admin_emails": ["admin@company.com"],
+    "public_url": "https://mcp.company.com",
+    "session_cookie_secure": "auto",
     "oauth": {
-      "provider": "google",
-      "client_id": "xxx.apps.googleusercontent.com",
-      "client_secret": "GOCSPX-xxx",
-      "tenant_id": "",
+      "provider": "oidc",
+      "issuer_url": "https://login.company.com/realms/team",
+      "client_id": "mcpproxy",
+      "client_secret": "${env:OIDC_CLIENT_SECRET}",
+      "scopes": ["openid", "profile", "email", "groups"],
+      "groups_claim": "groups",
+      "email_verified_policy": "refuse_false",
+      "display_name": "Company SSO",
       "allowed_domains": ["company.com"]
     },
     "session_ttl": "24h",
@@ -28,6 +44,122 @@ Server edition supports OAuth-based multi-user authentication with Google, GitHu
 }
 ```
 
+A legacy provider needs only `provider`, `client_id`, `client_secret` (and
+`tenant_id` for `microsoft`, default `common`); the six `oidc` keys are ignored
+for it. `oauth.provider` is validated in one place
+(`internal/config/server_edition_config.go`, `Validate`); the Web UI select in
+`frontend/src/views/settings/fields.ts` and `users.User.Validate` must change
+in lockstep with it.
+
+### The `oidc` provider (`internal/serveredition/auth/oidc_provider.go`)
+
+- **Discovery is lazy.** Nothing is fetched at boot or for readiness: the first
+  `GET /api/v1/auth/login` reads `<issuer_url>/.well-known/openid-configuration`,
+  checks the document's `issuer` equals the configured value **byte for byte**
+  (a trailing slash is a mismatch → `discovery_failed`, both values logged),
+  and caches it with a bounded TTL (cache headers respected, clamped to
+  5 min – 24 h). Every discovered endpoint (`authorization_endpoint`,
+  `token_endpoint`, `jwks_uri` required; `userinfo_endpoint` optional) must be
+  absolute `https`; plain `http` is admitted only for a loopback host together
+  with `allow_insecure_issuer: true` (`config.IsAllowedOIDCEndpoint` — the same
+  rule gates the configured issuer). A violating document is rejected before
+  any redirect or any request carrying the client secret.
+- **The back channel never follows redirects** and has a 10 s timeout. A 3xx
+  from discovery, JWKS, the token endpoint or userinfo is `provider_error`, so
+  a misconfigured or compromised IdP cannot downgrade the code or the client
+  secret to another origin.
+- **Client authentication is chosen once, before the single exchange**, from
+  `token_endpoint_auth_methods_supported`: `client_secret_basic` when
+  advertised (also the default when the key is absent), else
+  `client_secret_post`, else `discovery_failed`. An authorization code is
+  single-use, so there is no retry with a second method. PKCE S256 and a
+  per-login `nonce` are always sent; `openid` is appended to `scopes` if missing.
+- **The ID token is verified before any claim is read**
+  (`oidc_jwks.go` parses RSA/EC JWKs with the standard library and
+  `golang-jwt/jwt/v5` verifies): signature by `kid` against the cached JWKS
+  (an unknown `kid` triggers exactly one JWKS refetch per login), algorithm
+  restricted to RS256/RS384/RS512/PS256/PS384/PS512/ES256/ES384/ES512 (never
+  `none`, never HS*), `exp`/`nbf`/`iat` with 60 s skew, exact `iss`, `aud`
+  containing the client id (with `azp` required and checked when there are
+  several audiences), and the nonce stored beside the pending state and
+  consumed once. The unverified `parseIDToken` survives only for the three
+  legacy providers and is unreachable for `oidc`.
+- **Claims.** `sub` and `email` are required (`email_missing`);
+  `email_verified` is applied per `email_verified_policy`; groups are read from
+  the ID token's `groups_claim` (a flat string array or a single string), then
+  from `userinfo` once — and no userinfo claim is used before its `sub` is
+  compared with the verified token's `sub` (`userinfo_subject_mismatch`). A
+  failed userinfo fetch is `provider_error` (503, store untouched, stored
+  groups **not** reset); a claim absent from both, or an Entra overage marker
+  (`_claim_names`), stores `[]` and logs a warning naming the user id and the
+  claim looked for — never the token.
+- **Pending login state** is in-process, 10-minute TTL, capped at 10,000
+  entries with the oldest evicted on insert. A second replica is unsupported.
+- **Never log tokens or the client secret.** Log lines name the issuer, the
+  failed check and the error class only.
+
+### Subject binding and login refusals (every provider)
+
+- A user record stores `(provider, provider_subject_id)` and refreshes both on
+  every successful login. Same provider + same normalised email + different
+  `sub` is refused (`subject_mismatch`); a configured-provider change re-binds
+  on the first login and flags the attempt `provider_rebound`. Email stays the
+  lookup key (no store migration). An administrator re-arms the binding for a
+  genuinely re-created IdP account through `disable` → `enable`: the enable
+  transition sets `subject_rebind_armed_at`, the next successful login consumes
+  it (single-use, persisted across restarts, cleared atomically in the same
+  store write); a failed attempt does not consume it.
+- Every denial renders **one generic page** — `Sign-in was not permitted (ref
+  <request id>)` with the same status for every reason. The closed
+  `LoginRefusal` enum (`oauth_handler.go`: `authorization_denied`,
+  `state_invalid`, `id_token_invalid`, `issuer_mismatch`, `audience_mismatch`,
+  `token_expired`, `nonce_mismatch`, `email_missing`, `email_unverified`,
+  `domain_not_allowed`, `subject_mismatch`, `userinfo_subject_mismatch`,
+  `user_disabled`) reaches only the server log,
+  keyed by that request id. The one distinct class is unavailability —
+  `discovery_failed`, `provider_error` and the post-verification
+  `internal_error` — rendered as `503 Sign-in is temporarily unavailable (ref
+  <id>)`; the proxy stays up, readiness is unaffected and the next login
+  retries. A failure that is not the user's fault is never rendered as "not
+  permitted".
+- `redirect_uri` on `GET /api/v1/auth/login` is accepted only as a same-origin
+  path (single leading `/`, no `//`, `/\`, scheme, host, backslash or control
+  character); anything else becomes `/ui/` silently and flags the attempt
+  `redirect_rejected`. The Web UI passes `window.location.pathname`.
+
+### Front door behind an ingress
+
+The published image listens on `0.0.0.0:8080` behind a TLS-terminating ingress.
+Three keys make the SSO door safe there; `trusted_hosts` is **not** one of them
+(it is DNS-rebinding protection for loopback listeners and never runs on a
+non-loopback one).
+
+| Key | Role | Code |
+|-----|------|------|
+| `server_edition.public_url` (env `MCPPROXY_PUBLIC_URL`) | When set, the sole source of the IdP `redirect_uri` (`<public_url>/api/v1/auth/callback`), of the connect-flow base URL and of the scheme behind the `Secure` cookie decision; `Host` and `X-Forwarded-*` are ignored for those. Unset on a non-loopback listener → boot warning + `doctor` finding (never an error: every existing container deployment must keep booting). When set to https but the callback arrives over http, one warning with the request id is logged and login proceeds | `buildCallbackURL` (`oauth_handler.go`), `connector_provider.go`, `internal/config/env_serveredition.go` |
+| `trusted_proxies` (top-level, edition-neutral, env `MCPPROXY_TRUSTED_PROXIES`, **live**) | The only gate on `X-Forwarded-For` / `X-Real-IP` / `X-Forwarded-Proto` / `X-Forwarded-Host`: honoured only when `RemoteAddr` is inside the list, client IP = right-most untrusted hop. Default empty = trust nobody. Every reader evaluates a `func() []string` provider per request — never a slice captured at construction | `config.ForwardedHeaders` (`internal/config/trusted_proxies.go`) — the one reader; consumers: session store, callback, connector base URL, swagger, `httpapi.tagRequestMeta` |
+| `server_edition.session_cookie_secure` | `auto` (default: `Secure` when the effective scheme is https — `public_url`, in-process TLS, or a **trusted** `X-Forwarded-Proto: https`), `true`, `false`. `false` × (https `public_url` or `tls.enabled`) is refused at boot, PATCH and apply (`validateServerEditionConfig`, the `*Config`-level bridge that can see `tls`); an explicit `false` elsewhere is honoured with a warning + `doctor` finding | `NewSessionManager(..., securePolicy)`, `setup.go` |
+
+Forced MCP auth: when `server_edition.enabled` is `true`,
+`config.EffectiveRequireMCPAuth` makes `mcpAuthMiddleware` behave as if
+`require_mcp_auth` were `true` — no credential → 401, a session cookie or user
+JWT → 401; agent tokens, the API key and the socket are unchanged. An explicit
+`false` is not a validation error: boot logs `require_mcp_auth: false is
+overridden to true because server_edition.enabled is true` and `mcpproxy
+doctor` names the override. The accessors live in
+`internal/config/serveredition_accessors.go` (+ `_stub.go` for the personal
+build) so `internal/server` stays edition-neutral.
+
+`mcpproxy doctor` renders these findings from `config.DoctorFindings(cfg)`
+(`internal/config/doctor_findings*.go`), registered as a runtime-warning source
+on the management service; there is no producer in `cmd/mcpproxy`.
+
+Reload semantics: `enabled`, `oauth.*`, `public_url`, `session_cookie_secure`,
+`session_ttl`, `bearer_token_ttl` and `credential_encryption_key` are bound at
+setup and reported as `server_edition` with `RequiresRestart=true`
+(`server_edition settings are bound at startup`); `admin_emails` is live
+(`server_edition.admin_emails`); `trusted_proxies` is live.
+
 The former knobs `workspace_idle_timeout` and `max_user_servers` never
 controlled anything and were removed (Spec 107). A config file that still
 carries them loads: the server edition drops each with one startup warning
@@ -43,8 +175,9 @@ ignored (one deprecation warning when `true`); see
 
 | Endpoint | Auth | Description |
 |----------|------|-------------|
-| `GET /api/v1/auth/login` | Public | Initiate OAuth login flow |
-| `GET /api/v1/auth/callback` | Public | OAuth callback (creates session) |
+| `GET /api/v1/auth/provider` | Public | Edition + label probe: returns only `{"display_name": "..."}` (`oauth.display_name`, falling back to the provider family name), no side effects. Never the issuer, client id, tenant, scopes or domains. Registered only when the block is enabled; the personal build answers 404 — the Web UI uses that to detect the edition before any authenticated call |
+| `GET /api/v1/auth/login` | Public | Initiate OAuth login flow (PKCE S256, `state`, `nonce`; `?redirect_uri=` must be a same-origin path) |
+| `GET /api/v1/auth/callback` | Public | OAuth callback (verifies the ID token for `oidc`, creates session; one generic refusal page) |
 | `GET /api/v1/auth/me` | Session/JWT | Get current user profile |
 | `POST /api/v1/auth/token` | Session | Mint a user JWT for the REST API and CLI (`/api/v1/user/*`); a JWT is **never** an MCP credential — `/mcp` accepts only agent tokens, the API key and the socket |
 | `POST /api/v1/auth/logout` | Session | Invalidate session |
@@ -59,7 +192,7 @@ ignored (one deprecation warning when `true`); see
 
 ## Server Architecture
 
-- **Auth flow**: OAuth 2.0 + PKCE → Session cookie (Web UI) + JWT bearer (REST API / CLI only). Neither is accepted on `/mcp`; a user reaches tools only through an agent token they own.
+- **Auth flow**: OAuth 2.0 + PKCE (+ nonce and a JWKS-verified ID token for `oidc`) → Session cookie (`HttpOnly; SameSite=Lax`; `Secure` per `session_cookie_secure`) for the Web UI + JWT bearer (REST API / CLI only). Neither is accepted on `/mcp`; a user reaches tools only through an agent token they own.
 - **Server types**: Shared (config file) + Personal (DB rows a user adds through `POST /api/v1/user/servers`). Every upstream connection is the process's single shared connection — there is no per-user connection, per-user workspace or per-user credential on the tool-call path.
 - **Isolation**: REST listing scope (users see only shared + own personal servers), agent-token `allowed_servers` scope narrowed on every authentication, and user-scoped activity logs.
 - **Admin**: Identified by `admin_emails` config. Sees all activity, manages users.
@@ -251,7 +384,9 @@ bucket whose `allowed_servers` contains `"*"` and whose `user_id` is non-empty
 | `cmd/mcpproxy/edition.go` | Default edition = "personal" |
 | `cmd/mcpproxy/edition_teams.go` | Build-tagged override for server edition |
 | `cmd/mcpproxy/serveredition_register.go` | Server feature registration entry point |
-| `internal/serveredition/auth/` | OAuth, sessions, JWT tokens, middleware |
+| `internal/serveredition/auth/` | OAuth (legacy providers), `oidc_provider.go` + `oidc_jwks.go` (discovery, JWKS, verified ID token), sessions, JWT tokens, middleware, `login_pages.go` (generic refusal / unavailability pages) |
+| `internal/config/{server_edition_config,trusted_proxies,serveredition_accessors,env_serveredition,doctor_findings*}.go` | Block schema + validation, `ForwardedHeaders`, edition accessors (`EffectiveRequireMCPAuth`), `MCPPROXY_PUBLIC_URL`, doctor findings |
+| `tests/oauthserver/` (`-oidc`) | In-process fake OpenID Provider with discovery, JWKS, userinfo, per-user claims and a tamper matrix (bad signature, wrong `iss`/`aud`, expired, wrong nonce, `alg: none`, HS256, `email_verified: false`, `http` endpoints, redirecting token endpoint) |
 | `internal/serveredition/users/` | User/session models, BBolt store |
 | `internal/serveredition/multiuser/` | Activity isolation (user-scoped activity queries). The per-user router, tool filter and workspace packages that once lived here had no production caller and were deleted in Spec 107. |
 | `internal/serveredition/broker/` | Per-user `oauth_connect` credential store (stored, not injected — see [Auth Broker](../features/auth-broker.md)) |
@@ -261,8 +396,46 @@ bucket whose `allowed_servers` contains `"*"` and whose `user_id` is non-empty
 
 ```bash
 go test -tags server ./internal/serveredition/... -v -race  # All server unit + integration tests
-go build -tags server ./cmd/mcpproxy                        # Build server edition
+go build -tags server -o mcpproxy-server ./cmd/mcpproxy     # Build server edition (always -o: a bare build overwrites ./mcpproxy)
 go build ./cmd/mcpproxy                                     # Verify personal edition unaffected
 ```
 
+### Local rig: `scripts/dev-server-edition.sh`
+
+The Spec 107 verification rig runs the whole SSO path against a fake OpenID
+Provider, loopback-only, in a scratch directory — it never touches
+`~/.mcpproxy`, the tray's core or a real IdP. It is the executable form of
+`specs/107-server-edition-sso-hardening/quickstart.md`; the script is the
+source of truth and that page is its narrative.
+
+```bash
+scripts/dev-server-edition.sh                        # phase b: build, fake IdP, boot, headless login, /auth/me
+scripts/dev-server-edition.sh --phase c              # + tenant principal on core REST (PR-C)
+scripts/dev-server-edition.sh --phase d --keep       # + token mint, /mcp gate, audit tail (PR-D); keep the scratch dir
+scripts/dev-server-edition.sh --idp-args "-token-error bad-signature"   # one US2 tamper case: expects a 403, no session
+```
+
+What it does, in order: builds `mcpproxy-server` (`-tags server -o`, never
+bare) and the fake IdP (`tests/oauthserver/cmd/server -oidc`) into the scratch
+dir; runs `npm ci --prefix tests/echo-rugpull-server` once for the stdio
+fixture (`node tests/echo-rugpull-server/index.js`, a deterministic `echo`
+tool while `DESC_FILE` is unset); writes `mcp_config.json` with
+`server_edition.oauth.provider: "oidc"` pointing at the IdP through
+`${env:OIDC_CLIENT_ID}` / `${env:OIDC_CLIENT_SECRET}`; boots the server
+edition with **both** `--config` and `--data-dir` on a free `18xxx` port and
+waits for `/readyz` + `/api/v1/status` (`edition: server`); performs the
+headless login as `alice@example.com` (302 to the IdP with `S256` + `nonce`,
+POST the login form without following redirects, then GET the callback) and
+prints `/api/v1/auth/me`; repeats the login with
+`redirect_uri=https://evil.example/` and asserts the 302 lands on `/ui/`.
+
+Rules it encodes: every wait loop is bounded and every `curl` carries
+`--max-time`, so a missing piece (an older branch without the `oidc` provider
+answers exit 4 at config load) is reported with the reason, never hung on;
+teardown kills only the PIDs it started (never `pkill` by name) and removes
+the scratch dir only when it created it via `mktemp` (`--scratch DIR` and
+`MCPPROXY_RIG_SCRATCH` are always kept, as is any failed run). Gates for the
+script itself: `bash -n scripts/dev-server-edition.sh` and `shellcheck
+scripts/dev-server-edition.sh`.
+
 > Note: server-edition `//go:build server` routes are invisible to `swag` / `verify-oas-coverage.sh` (which don't pass `--build-tags server`), so document endpoints here. CI lints twice — bare and with `--build-tags server` — and race-tests `internal/server`, `internal/httpapi` and `internal/storage` under the tag (Spec 107 FR-047); run both lint passes locally before pushing (see the Lint block in `CLAUDE.md`).
diff --git a/docs/features/telemetry.md b/docs/features/telemetry.md
index 0e60a30fd..6de1b86ef 100644
--- a/docs/features/telemetry.md
+++ b/docs/features/telemetry.md
@@ -10,7 +10,7 @@ MCPProxy collects anonymous usage statistics to help improve the product. This p
 
 ## What is collected
 
-MCPProxy sends a **daily heartbeat** containing only aggregate, non-identifying information. The current schema is **version 12** (`schema_version: 12` in the JSON payload); the schema is forward-compatible so older consumers simply ignore fields they don't recognize.
+MCPProxy sends a **daily heartbeat** containing only aggregate, non-identifying information. The current schema is **version 13** (`schema_version: 13` in the JSON payload); the schema is forward-compatible so older consumers simply ignore fields they don't recognize.
 
 | Field | Example | Purpose |
 |-------|---------|---------|
@@ -43,6 +43,10 @@ MCPProxy sends a **daily heartbeat** containing only aggregate, non-identifying
 | `tpa_scanner` | `{"scans_completed":4,"scans_failed":0,"scans_with_findings":1,"findings":{"high":2},"tool_change_gate_scans":6,"prompt_scans":11}` | Security/TPA scanner activity (schema v8, extended in v9) — counts only, keyed by the fixed severity enum. Omitted entirely when no scan of any kind ran |
 | `trust_mode_distribution` | `{"auto":1,"scan":3,"manual":8}` | Configured servers per effective trust tier (schema v9) — fixed enum keys `auto`/`scan`/`manual`, counts only. Never server names |
 | `feature_flags.deep_scan_enabled` | `false` | Whether the opt-in deep-scan layer is turned on (schema v8) |
+| `feature_flags.server_edition_enabled` | `false` | Whether the `server_edition` block is present and enabled (schema v13, Spec 107). Always `false` on the personal edition, where the block is never interpreted |
+| `feature_flags.idp_provider` | `none` | The configured identity-provider **family** for server-edition SSO (schema v13) — fixed enum `google` / `github` / `microsoft` / `oidc` / `none`. The kind only: never the issuer URL, tenant, client id or display name. `none` when the block is disabled or unset |
+| `member_count_bucket` | `1-10` | Number of server-edition user accounts, bucketed (schema v13) — fixed enum `0` / `1-10` / `11-100` / `101-1000` / `1000+`. `0` on the personal edition (no counter is installed); omitted only when the counter fails. A count only, never an identity. (Named `member_…`, not `user_…`: the anonymity scanner blocks the home-dir basename as a substring of the whole payload, and `user` is the username of every `USER user` container image) |
+| `env_markers.is_container` | `true` | Unchanged in v13; read together with the fields above to see how server-edition installs are deployed |
 | `preflight` | `{"filter_diag_emitted_24h":3,"availability_block_24h":2,"availability_block_reasons_24h":{"server_quarantined":2},"discovery_omission_24h":5}` | Preflight baseline counters (issue #969) — counts only, reason map keyed by a fixed enum. Omitted entirely when nothing was counted. See below |
 
 The `server_protocol_counts` map uses a **fixed enum of keys** (`stdio`, `http`, `sse`, `streamable_http`, `auto`) — server names and URLs are never included. Unknown or misconfigured protocol values are bucketed into `auto`.
@@ -86,6 +90,7 @@ The following is **never** collected:
 - File paths or environment variables
 - IP addresses (stripped by our server before storage)
 - User identity, email, or account information
+- Server-edition IdP issuer URLs, tenant ids, client ids, or group names (only the provider family and a bucketed member count are sent — schema v13)
 - Tool call content, arguments, or responses
 - Any user-generated content
 - The **raw** OS machine id or any reversible hardware identifier (only the salted, non-reversible `machine_id` hash is sent — see below)
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index e5cf68d5d..e2e1698bb 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -399,6 +399,65 @@ docker run -d --name mcpproxy \
   container is awkward.
 - **Web UI**: `http://localhost:8080/ui/`.
 
+### Behind an ingress with SSO
+
+To put the container behind a TLS-terminating ingress and sign users in through your
+IdP, add the `server_edition` block to the config on the volume and pass the secrets as
+environment variables that the file references with `${env:...}` — nothing secret is
+written into `mcp_config.json`:
+
+```bash
+docker run -d --name mcpproxy \
+  -p 8080:8080 \
+  -e MCPPROXY_API_KEY \
+  -e OIDC_CLIENT_SECRET \
+  -e MCPPROXY_CRED_KEY \
+  -e MCPPROXY_PUBLIC_URL="https://mcp.example.com" \
+  -e MCPPROXY_TRUSTED_PROXIES="10.42.0.0/16" \
+  -v mcpproxy-data:/root/.mcpproxy \
+  ghcr.io/smart-mcp-proxy/mcpproxy-server:latest
+```
+
+```json
+{
+  "listen": "0.0.0.0:8080",
+  "trusted_proxies": ["10.42.0.0/16"],
+  "server_edition": {
+    "enabled": true,
+    "admin_emails": ["admin@example.com"],
+    "public_url": "https://mcp.example.com",
+    "credential_encryption_key": "${env:MCPPROXY_CRED_KEY}",
+    "oauth": {
+      "provider": "oidc",
+      "issuer_url": "https://login.example.com/realms/team",
+      "client_id": "mcpproxy",
+      "client_secret": "${env:OIDC_CLIENT_SECRET}"
+    }
+  }
+}
+```
+
+- **`public_url`** is the origin users reach — the IdP `redirect_uri` becomes
+  `https://mcp.example.com/api/v1/auth/callback` and the session cookie is `Secure`,
+  independent of what the ingress puts in `Host` or `X-Forwarded-*`. The image listens on
+  `0.0.0.0:8080`, so leaving it unset is a boot warning and a `mcpproxy doctor` finding.
+  `MCPPROXY_PUBLIC_URL` overrides the file value; it is the only nested `server_edition`
+  key with an environment alias.
+- **`trusted_proxies`** is the ingress's source range as the container sees it. Forwarded
+  headers from anywhere else are ignored, so a direct client cannot spoof its address or
+  scheme. `MCPPROXY_TRUSTED_PROXIES` (comma list) overrides the file value. `trusted_hosts`
+  is unrelated here — it never runs on a non-loopback listener.
+- **Secrets** stay in the environment: `client_secret`, `credential_encryption_key` (or
+  just `MCPPROXY_CRED_KEY`, its fallback) and the API key. `${env:NAME}` is expanded when
+  the file is loaded and the secret is masked in every API response.
+- **`/mcp` requires a credential** as soon as `server_edition.enabled` is `true`, whatever
+  `require_mcp_auth` says — agent tokens, the API key or the socket; a browser session is
+  never an MCP credential.
+
+The full key table — `session_cookie_secure`, `scopes`, `groups_claim`,
+`email_verified_policy`, `display_name`, the per-IdP groups-claim notes — is in
+[Server Edition](/configuration/config-file#server-edition).
+
 Note that this image ships the Server edition binary (`mcpproxy version` reports `(server)`); it is
 the headless core only, with no system tray.
 
diff --git a/docs/operations/reverse-proxy.md b/docs/operations/reverse-proxy.md
index d5271f94b..4e254d0e5 100644
--- a/docs/operations/reverse-proxy.md
+++ b/docs/operations/reverse-proxy.md
@@ -2,16 +2,17 @@
 id: reverse-proxy
 title: Reverse Proxy Deployment
 sidebar_label: Reverse Proxy
-description: 'Run MCPProxy behind nginx or Caddy — fix "403 Forbidden: invalid Host header" with trusted_hosts, and secure the exposed endpoint.'
-keywords: [reverse proxy, nginx, caddy, trusted_hosts, invalid Host header, DNS rebinding, 403 Forbidden, Host header]
+description: 'Run MCPProxy behind nginx or Caddy — fix "403 Forbidden: invalid Host header" with trusted_hosts, honour X-Forwarded-* only from trusted_proxies, and secure the exposed endpoint.'
+keywords: [reverse proxy, nginx, caddy, trusted_hosts, trusted_proxies, X-Forwarded-For, X-Forwarded-Proto, invalid Host header, DNS rebinding, 403 Forbidden, Host header]
 ---
 
 # Reverse Proxy Deployment
 
 MCPProxy listens on a loopback address by default (`127.0.0.1:8080`) and is designed
 to run locally. You can still put it behind a reverse proxy (nginx, Caddy, Traefik,
-CloudPanel) to add HTTPS, a public hostname, or shared access — but two things need
-attention: **Host-header validation** and **authentication**.
+CloudPanel) to add HTTPS, a public hostname, or shared access — but three things need
+attention: **Host-header validation**, **forwarded headers** (`trusted_proxies`) and
+**authentication**.
 
 ## The `403 Forbidden: invalid Host header` error
 
@@ -54,6 +55,11 @@ The fix is to add your public domain(s) to the `trusted_hosts` allowlist.
   `MCPPROXY_TRUSTED_HOSTS="mcp.example.com,mcp.internal:8443"`.
 - **Hot-reloadable:** editing the config file applies without a restart.
 
+`trusted_hosts` decides only which `Host` values a **loopback** listener accepts. It
+never runs on a non-loopback listener (the Docker image's `0.0.0.0:8080`), and it says
+nothing about whether the proxy believes `X-Forwarded-*` — that is `trusted_proxies`,
+below. In particular it is **not** the control that secures the Server-edition SSO door.
+
 ### Origin validation (browser requests)
 
 Per the MCP specification's security best practices, MCPProxy also validates the
@@ -68,6 +74,55 @@ client served **from your public domain** works as soon as that domain is in
 frontend hosted on a **different** origin must have its own host added to
 `trusted_hosts` too, or its requests are rejected.
 
+## `trusted_proxies` — forwarded headers {#trusted_proxies-forwarded-headers}
+
+A reverse proxy rewrites the connection MCPProxy sees: the peer address becomes the
+proxy's, the scheme becomes plain `http`, and the real client, scheme and host arrive
+only as `X-Forwarded-For`, `X-Real-IP`, `X-Forwarded-Proto` and `X-Forwarded-Host`.
+Anyone who can reach the listener directly can send those headers too, so by default
+MCPProxy **believes none of them**. `trusted_proxies` lists the peers it does believe:
+
+```json
+{
+  "listen": "127.0.0.1:8080",
+  "trusted_hosts": ["mcp.example.com"],
+  "trusted_proxies": ["127.0.0.1", "10.42.0.0/16"]
+}
+```
+
+| Behaviour | Detail |
+|-----------|--------|
+| Entries | CIDRs (`10.42.0.0/16`, `fd00::/8`) or single IP addresses (`127.0.0.1`, `::1`). Hostnames are not accepted |
+| Default | Empty (`[]`) — **trust nobody**: every forwarded header is ignored and the direct `RemoteAddr` and listener scheme are used |
+| Trusted peer | When `RemoteAddr` is inside the list, `X-Forwarded-Proto` (`http`/`https`) and `X-Forwarded-Host` are honoured, and the client IP is the **right-most `X-Forwarded-For` hop that is not itself a trusted proxy** (then `X-Real-IP`) |
+| Untrusted peer | Headers ignored, no error. A direct client cannot spoof its IP, the request scheme or the host |
+| What it feeds | The session client IP (and the per-request client IP tagged for attribution), the `Secure` decision of the Server-edition session cookie, the OAuth callback scheme/host when `server_edition.public_url` is unset, and the Swagger UI base URL |
+| What it never feeds | Local/remote or administrator classification — no forwarded header can promote a caller |
+| Validation | `trusted_proxies[0] "nginx" is not a valid CIDR or IP address` — the same message at boot, on `PATCH /api/v1/config` and on `/config/apply` |
+| Environment override | `MCPPROXY_TRUSTED_PROXIES="127.0.0.1,10.42.0.0/16"` |
+| Hot reload | Live — every reader evaluates the current list per request, no restart |
+
+List the proxy's **source** address as MCPProxy sees it: `127.0.0.1` for nginx or Caddy on
+the same host, the ingress pod or node range in Kubernetes, the Docker bridge network for a
+proxy container in front of `mcpproxy-server`. Do not list `0.0.0.0/0` — that re-opens the
+spoof.
+
+nginx sends the standard headers with:
+
+```nginx
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Forwarded-Proto $scheme;
+proxy_set_header X-Forwarded-Host $host;
+```
+
+Caddy's `reverse_proxy` sets `X-Forwarded-For` and `X-Forwarded-Proto` by default.
+
+**Server edition (SSO):** behind a TLS-terminating ingress set **both**
+`server_edition.public_url` (the exact origin registered at the IdP — the callback URL and
+the `Secure` cookie then no longer depend on any header) and `trusted_proxies` (the ingress
+range, so the session IP and the attributed client IP are the real client). See
+[Server Edition](/configuration/config-file#server-edition) for the container topology.
+
 ## nginx
 
 With `trusted_hosts` configured, a standard nginx block works without rewriting the
@@ -82,6 +137,11 @@ server {
         proxy_pass http://127.0.0.1:8080;
         proxy_set_header Host $host;
 
+        # Honoured only if 127.0.0.1 is in trusted_proxies (see above).
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $host;
+
         # MCPProxy streams responses (SSE at /events, streamable HTTP at /mcp).
         # Disable proxy buffering so events are delivered as they are produced.
         proxy_buffering off;
@@ -129,11 +189,16 @@ authenticate differently:
 
   MCP clients then authenticate with the same API key (`X-API-Key` header).
 
+  In the **Server edition** `require_mcp_auth` is forced to `true` whenever
+  `server_edition.enabled` is `true`; an explicit `false` is overridden with one boot
+  notice and a `mcpproxy doctor` finding. A browser session cookie or user JWT is never
+  an MCP credential — `/mcp` accepts agent tokens, the API key and the socket only.
+
 Prefer the `X-API-Key` header over `?apikey=` where the client supports it — query
 strings are more likely to be logged by intermediate proxies.
 
 ## Related
 
 - [Configuration File](/configuration/config-file) — full option reference
-- [Environment Variables](/configuration/environment-variables) — `MCPPROXY_TRUSTED_HOSTS`
+- [Environment Variables](/configuration/environment-variables) — `MCPPROXY_TRUSTED_HOSTS`, `MCPPROXY_TRUSTED_PROXIES`
 - [REST API](/api/rest-api) — authentication details
diff --git a/frontend/src/services/auth-api.ts b/frontend/src/services/auth-api.ts
index 58bef32df..d017b8d3a 100644
--- a/frontend/src/services/auth-api.ts
+++ b/frontend/src/services/auth-api.ts
@@ -16,7 +16,34 @@ export interface BearerTokenResponse {
   expires_at: string
 }
 
+// Spec 107 FR-030: the whole body of the public edition probe — an
+// operator-chosen label and nothing else (never issuer, client id, tenant,
+// scopes, domains or provider family).
+export interface ProviderInfo {
+  display_name: string
+}
+
 export const authApi = {
+  // Public edition probe (Spec 107 FR-030 / FR-041). No authentication, no
+  // side effects. 200 {display_name} = server edition; 404 = personal build
+  // or server_edition.enabled=false. Any other failure is reported as null so
+  // the UI degrades to the personal surface rather than hanging on a spinner.
+  // This is called BEFORE any authenticated call: a tenant holds no API key,
+  // so learning the edition from a keyed endpoint would 401 for exactly the
+  // people the server edition exists for.
+  async getProvider(): Promise<ProviderInfo | null> {
+    try {
+      const response = await fetch(`${API_BASE}/auth/provider`)
+      if (response.status === 404) return null
+      if (!response.ok) return null
+      const body = await response.json()
+      if (!body || typeof body.display_name !== 'string') return null
+      return { display_name: body.display_name }
+    } catch {
+      return null
+    }
+  },
+
   // Get current user profile (returns null if not authenticated)
   async getMe(): Promise<UserProfile | null> {
     try {
diff --git a/frontend/src/stores/auth.ts b/frontend/src/stores/auth.ts
index 085a801c2..5289d72ab 100644
--- a/frontend/src/stores/auth.ts
+++ b/frontend/src/stores/auth.ts
@@ -1,12 +1,14 @@
 import { defineStore } from 'pinia'
 import { ref, computed } from 'vue'
-import { authApi, type UserProfile } from '@/services/auth-api'
-import api from '@/services/api'
+import { authApi, type ProviderInfo, type UserProfile } from '@/services/auth-api'
 
 export const useAuthStore = defineStore('auth', () => {
   const user = ref<UserProfile | null>(null)
   const loading = ref(true)
   const isTeamsEdition = ref(false)
+  // Spec 107 FR-030: the operator-chosen login label from the public probe;
+  // null on the personal edition. Login.vue renders it.
+  const provider = ref<ProviderInfo | null>(null)
 
   const isAuthenticated = computed(() => !!user.value)
   const isAdmin = computed(() => user.value?.role === 'admin')
@@ -25,13 +27,15 @@ export const useAuthStore = defineStore('auth', () => {
 
   async function probe() {
     try {
-      // Check if this is server edition using the API service (includes API key)
-      const statusRes = await api.getStatus()
-      isTeamsEdition.value = statusRes.data?.edition === 'server'
+      // Spec 107 FR-030 / FR-041: learn the edition from the PUBLIC probe
+      // before any authenticated call. The previous detection went through
+      // GET /api/v1/status with the API key, which a tenant never holds — so
+      // every tenant read as "personal edition" and was bounced off /login.
+      const probe = await authApi.getProvider()
+      provider.value = probe
+      isTeamsEdition.value = probe != null
 
-      if (isTeamsEdition.value) {
-        user.value = await authApi.getMe()
-      }
+      user.value = isTeamsEdition.value ? await authApi.getMe() : null
     } catch {
       // Not authenticated or not server edition
       user.value = null
@@ -68,6 +72,7 @@ export const useAuthStore = defineStore('auth', () => {
     user,
     loading,
     isTeamsEdition,
+    provider,
     isAuthenticated,
     isAdmin,
     displayName,
diff --git a/frontend/src/views/settings/fields.ts b/frontend/src/views/settings/fields.ts
index 4c87c40c4..3176ecd7c 100644
--- a/frontend/src/views/settings/fields.ts
+++ b/frontend/src/views/settings/fields.ts
@@ -34,6 +34,12 @@ export interface DangerSpec {
 // which are validated from the control type). Centralised in validateField.
 export type ValueKind = 'hostport' | 'bytesize' | 'cpu' | 'hostname' | 'url' | 'secretkey'
 
+// A `[]string` config key edited through a textarea. The form shows a joined
+// string ('comma' = "a, b", 'lines' = one entry per line) and the PATCH
+// partial carries the split, trimmed array — see listToText / textToList.
+// Without this the textarea would PATCH a plain string into a []string key.
+export type ListKind = 'comma' | 'lines'
+
 export interface SettingField {
   key: string // dot-path, e.g. "docker_isolation.enabled"
   label: string
@@ -54,6 +60,8 @@ export interface SettingField {
   // for `omitempty` fields whose zero value is meaningful (the serialization
   // modes: "" means "full"). See normalizeFieldDefaults below for why.
   defaultValue?: string
+  // Set for a textarea that edits a []string key (see ListKind).
+  listKind?: ListKind
 }
 
 export interface SettingsAccordion {
@@ -235,6 +243,18 @@ export const SECURITY_FIELDS: SettingField[] = [
         'Binding to a non-loopback address (e.g. 0.0.0.0) exposes mcpproxy to your network. Make sure “Require API key for MCP clients” is enabled. Continue?',
     },
   },
+  {
+    // Spec 107 FR-027 (edition-neutral, hot-reloaded): X-Forwarded-For /
+    // X-Forwarded-Proto / X-Forwarded-Host / X-Real-IP are honoured only when
+    // the direct peer is in this list. Empty = trust nobody.
+    key: 'trusted_proxies',
+    label: 'Trusted reverse proxies',
+    help: 'One CIDR or IP address per line (e.g. 10.0.0.0/8). Forwarded headers (X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, X-Real-IP) are honoured only from these peers; leave empty when mcpproxy is not behind a proxy. Applies without a restart.',
+    control: 'textarea',
+    listKind: 'lines',
+    optional: true,
+    placeholder: '10.0.0.0/8',
+  },
 ]
 
 // ---- Section 2: General ----
@@ -321,9 +341,102 @@ export const GENERAL_FIELDS: SettingField[] = [
 // so old configs hydrate the form while edits always save under `server_edition`.
 export const SERVER_EDITION_TAB_LABEL = 'Server Edition'
 export const SERVER_EDITION_SECTION_TITLE = '👥 Server Edition'
+//
+// Spec 107 PR-B (T054): this row set is asserted EXACTLY by
+// `tests/unit/settings-server-edition-wording.spec.ts`. The `Settings`
+// disposition paragraph of `specs/107-server-edition-sso-hardening/contracts/
+// config-keys.md` is the authority. Every row is restart-pinned (bound at
+// login-handler construction). Deliberately absent, Raw-JSON-only:
+// `access.*` (no map control), `oauth.allow_insecure_issuer` (a loopback-only
+// development toggle that must not look like a normal setting), and the
+// retained keys with no row today (`admin_emails`, `session_ttl`,
+// `bearer_token_ttl`, `oauth.client_id`, `oauth.tenant_id`,
+// `oauth.allowed_domains` — SC-007, no UI widening). NEVER a row:
+// `oauth.client_secret` and `credential_encryption_key` (secrets; `${env:}` /
+// `MCPPROXY_CRED_KEY`) and `store_idp_tokens` (deprecated no-op).
 export const SERVER_EDITION_FIELDS: SettingField[] = [
   { key: 'server_edition.enabled', label: 'Enable multi-user mode', control: 'toggle', restart: true },
-  { key: 'server_edition.oauth.provider', label: 'OAuth provider', control: 'select', options: ['', 'google', 'github', 'microsoft'].map((v) => ({ value: v, label: v || '(none)' })) },
+  {
+    key: 'server_edition.oauth.provider',
+    label: 'OAuth provider',
+    help: 'Identity provider family. Choose "oidc" for any OpenID Connect provider (Keycloak, Okta, Entra, Authentik, …) and set the issuer URL below. Client id and secret are set in the config file (use ${env:…} for the secret).',
+    control: 'select',
+    options: ['', 'google', 'github', 'microsoft', 'oidc'].map((v) => ({ value: v, label: v || '(none)' })),
+    restart: true,
+  },
+  {
+    key: 'server_edition.oauth.display_name',
+    label: 'Login button label',
+    help: 'Shown on the sign-in page as "Sign in with …". Defaults to the provider family name. Up to 64 characters.',
+    control: 'text',
+    optional: true,
+    placeholder: 'Acme SSO',
+    restart: true,
+  },
+  {
+    key: 'server_edition.oauth.issuer_url',
+    label: 'OIDC issuer URL',
+    help: 'Required when the provider is "oidc". Must be https (plain http is accepted only for a loopback host with allow_insecure_issuer set in the config file). Discovery runs at <issuer>/.well-known/openid-configuration and the discovered issuer must match byte-for-byte.',
+    control: 'text',
+    valueKind: 'url',
+    optional: true,
+    placeholder: 'https://login.example.com/realms/acme',
+    restart: true,
+  },
+  {
+    key: 'server_edition.oauth.scopes',
+    label: 'OIDC scopes',
+    help: 'Comma-separated scopes requested at login. "openid" is always added. Default: openid, profile, email.',
+    control: 'textarea',
+    listKind: 'comma',
+    optional: true,
+    placeholder: 'openid, profile, email',
+    restart: true,
+  },
+  {
+    key: 'server_edition.oauth.groups_claim',
+    label: 'Groups claim',
+    help: 'Name of the ID-token / userinfo claim that carries the user’s groups (used by the access map). Default: groups.',
+    control: 'text',
+    optional: true,
+    placeholder: 'groups',
+    restart: true,
+  },
+  {
+    key: 'server_edition.oauth.email_verified_policy',
+    label: 'Email verification policy',
+    help: 'refuse_false = reject a login whose ID token says email_verified: false (default); require_true = also reject when the claim is missing; ignore = never check.',
+    control: 'select',
+    options: [
+      { value: 'refuse_false', label: 'refuse_false — reject unverified (default)' },
+      { value: 'require_true', label: 'require_true — require the claim to be true' },
+      { value: 'ignore', label: 'ignore — never check' },
+    ],
+    restart: true,
+  },
+  {
+    key: 'server_edition.public_url',
+    label: 'Public URL',
+    help: 'The absolute origin users reach mcpproxy at behind a reverse proxy (scheme://host[:port], no path). Used to build the OAuth callback and to decide whether the session cookie is Secure. MCPPROXY_PUBLIC_URL overrides it.',
+    control: 'text',
+    valueKind: 'url',
+    optional: true,
+    placeholder: 'https://mcp.example.com',
+    restart: true,
+  },
+  {
+    key: 'server_edition.session_cookie_secure',
+    label: 'Session cookie Secure attribute',
+    help: 'auto = Secure when the public URL is https or TLS is on (default). "false" cannot be combined with an https public URL or TLS.',
+    control: 'select',
+    defaultValue: 'auto',
+    options: [
+      { value: 'auto', label: 'auto — follow the public URL / TLS (default)' },
+      { value: 'true', label: 'true — always Secure' },
+      { value: 'false', label: 'false — never Secure (plain-http development only)' },
+    ],
+    restart: true,
+  },
 ]
 
 // isBlankInstructions returns true when a saved instructions value is empty /
@@ -544,8 +657,8 @@ export function aliasServerEdition(cfg: any): any {
 export function hydrateConfigState(cfg: any): { working: any; original: any; raw: any } {
   const clone = (v: any) => (v == null ? v : JSON.parse(JSON.stringify(v)))
   return {
-    working: normalizeFieldDefaults(aliasServerEdition(clone(cfg))),
-    original: normalizeFieldDefaults(aliasServerEdition(clone(cfg))),
+    working: normalizeListFields(normalizeFieldDefaults(aliasServerEdition(clone(cfg)))),
+    original: normalizeListFields(normalizeFieldDefaults(aliasServerEdition(clone(cfg)))),
     raw: clone(cfg),
   }
 }
@@ -560,6 +673,47 @@ export function normalizeFieldDefaults(cfg: any): any {
   return cfg
 }
 
+/**
+ * Render a []string value as the textarea text of a list-kind field. Anything
+ * that is not an array (already text, null) is returned unchanged.
+ */
+export function listToText(kind: ListKind, value: unknown): unknown {
+  if (!Array.isArray(value)) return value
+  const items = value.map((v) => String(v))
+  return kind === 'lines' ? items.join('\n') : items.join(', ')
+}
+
+/**
+ * Parse the textarea text of a list-kind field back into a trimmed []string.
+ * Commas and newlines both separate entries for either kind (an operator who
+ * pastes "a,b" into a one-per-line box still gets two entries); blank entries
+ * are dropped, so a cleared textarea is an empty list, never a string. An
+ * array is returned as-is.
+ */
+export function textToList(_kind: ListKind, value: unknown): string[] {
+  if (Array.isArray(value)) return value.map((v) => String(v))
+  if (value == null) return []
+  return String(value)
+    .split(/[\n,]/)
+    .map((v) => v.trim())
+    .filter((v) => v !== '')
+}
+
+/**
+ * Turn every list-kind field's array into its textarea text. Applied to BOTH
+ * the working copy and the last-saved snapshot (see hydrateConfigState) so the
+ * dirty comparison stays string-vs-string. Mutates and returns cfg.
+ */
+export function normalizeListFields(cfg: any): any {
+  if (cfg == null || typeof cfg !== 'object') return cfg
+  for (const f of allCatalogFields()) {
+    if (!f.listKind) continue
+    const cur = getPath(cfg, f.key)
+    if (Array.isArray(cur)) setPath(cfg, f.key, listToText(f.listKind, cur))
+  }
+  return cfg
+}
+
 export function getPath(obj: any, path: string): any {
   return path.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj)
 }
@@ -583,10 +737,15 @@ export function setPath(obj: any, path: string, value: any): void {
 
 // buildPartial assembles a nested object containing ONLY the given dot-path
 // keys, read from `source`. This is the partial payload sent to PATCH /config.
+// A list-kind field (see ListKind) is converted from its textarea text back
+// into the []string the Go side expects.
 export function buildPartial(source: any, dirtyKeys: string[]): Record<string, any> {
   const out: Record<string, any> = {}
+  const fields = allCatalogFields()
   for (const key of dirtyKeys) {
-    setPath(out, key, getPath(source, key))
+    const f = fields.find((x) => x.key === key)
+    const val = getPath(source, key)
+    setPath(out, key, f?.listKind ? textToList(f.listKind, val) : val)
   }
   return out
 }
diff --git a/frontend/src/views/teams/Login.vue b/frontend/src/views/teams/Login.vue
index e7ad1de31..4c1cd3a28 100644
--- a/frontend/src/views/teams/Login.vue
+++ b/frontend/src/views/teams/Login.vue
@@ -20,12 +20,16 @@
 </template>
 
 <script setup lang="ts">
+import { computed } from 'vue'
 import { useAuthStore } from '@/stores/auth'
 
 const authStore = useAuthStore()
 
-// Provider name will come from status API in future; for now show generic
-const providerName = 'your organization'
+// Spec 107 FR-030: the label comes from the public probe
+// (GET /api/v1/auth/provider → {display_name}: oauth.display_name, falling
+// back to the provider family name on the server). The generic fallback only
+// shows while the probe is still in flight.
+const providerName = computed(() => authStore.provider?.display_name || 'your organization')
 
 function handleLogin() {
   authStore.login()
diff --git a/frontend/tests/unit/auth-guard-hard-reload.spec.ts b/frontend/tests/unit/auth-guard-hard-reload.spec.ts
index e0fede205..ee4945a7f 100644
--- a/frontend/tests/unit/auth-guard-hard-reload.spec.ts
+++ b/frontend/tests/unit/auth-guard-hard-reload.spec.ts
@@ -6,7 +6,12 @@ import { createRouter, createMemoryHistory, type Router } from 'vue-router'
 // callers race for the auth probe: App.vue's onMounted checkAuth() and the
 // router guard's own checkAuth() for the initial navigation. The guard must
 // decide `isTeamsEdition` / `isAuthenticated` from ONE settled probe (never a
-// half-run one) and the pair must not double-issue /status + /auth/me.
+// half-run one) and the pair must not double-issue /auth/provider + /auth/me.
+//
+// Spec 107 FR-030/FR-041 moved edition detection off the keyed GET
+// /api/v1/status (a tenant holds no API key) onto the public GET
+// /api/v1/auth/provider probe, so `providerSpy` stands in for that call here
+// — same race, same single-in-flight-probe guarantee, different endpoint.
 
 const deferred = <T,>() => {
   let resolve!: (v: T) => void
@@ -14,18 +19,12 @@ const deferred = <T,>() => {
   return { promise, resolve }
 }
 
-const statusSpy = vi.hoisted(() => vi.fn())
+const providerSpy = vi.hoisted(() => vi.fn())
 const meSpy = vi.hoisted(() => vi.fn())
 
-vi.mock('@/services/api', () => ({
-  default: {
-    getStatus: statusSpy,
-    hasAPIKey: vi.fn(() => false),
-  },
-}))
-
 vi.mock('@/services/auth-api', () => ({
   authApi: {
+    getProvider: providerSpy,
     getMe: meSpy,
     getLoginUrl: vi.fn(() => '/api/v1/auth/login'),
     logout: vi.fn(),
@@ -57,13 +56,13 @@ function makeRouter(): Router {
 }
 
 function serverEdition(user: typeof tenant | null) {
-  const status = deferred<{ data: { edition: string } }>()
+  const provider = deferred<{ display_name: string }>()
   const me = deferred<typeof tenant | null>()
-  statusSpy.mockReturnValue(status.promise)
+  providerSpy.mockReturnValue(provider.promise)
   meSpy.mockReturnValue(me.promise)
   return {
     settle: () => {
-      status.resolve({ data: { edition: 'server' } })
+      provider.resolve({ display_name: 'Server SSO' })
       me.resolve(user)
     },
   }
@@ -72,11 +71,11 @@ function serverEdition(user: typeof tenant | null) {
 describe('auth store: concurrent checkAuth shares one in-flight probe', () => {
   beforeEach(() => {
     setActivePinia(createPinia())
-    statusSpy.mockReset()
+    providerSpy.mockReset()
     meSpy.mockReset()
   })
 
-  it('issues /status and /auth/me once for two concurrent callers, both see the settled edition', async () => {
+  it('issues /auth/provider and /auth/me once for two concurrent callers, both see the settled edition', async () => {
     const rig = serverEdition(tenant)
     const store = useAuthStore()
 
@@ -85,7 +84,7 @@ describe('auth store: concurrent checkAuth shares one in-flight probe', () => {
     rig.settle()
     await Promise.all([mount, guard])
 
-    expect(statusSpy).toHaveBeenCalledTimes(1)
+    expect(providerSpy).toHaveBeenCalledTimes(1)
     expect(meSpy).toHaveBeenCalledTimes(1)
     expect(store.isTeamsEdition).toBe(true)
     expect(store.isAuthenticated).toBe(true)
@@ -95,28 +94,28 @@ describe('auth store: concurrent checkAuth shares one in-flight probe', () => {
   it('fresh: true queues a new probe behind the in-flight one instead of joining it', async () => {
     // Probe 1 was issued before the key was repaired (/auth/me says signed
     // out); probe 2 is the recovery read and must see the tenant.
-    const status = [deferred<{ data: { edition: string } }>(), deferred<{ data: { edition: string } }>()]
+    const provider = [deferred<{ display_name: string }>(), deferred<{ display_name: string }>()]
     const me = [deferred<typeof tenant | null>(), deferred<typeof tenant | null>()]
-    statusSpy.mockImplementation(() => status[statusSpy.mock.calls.length - 1].promise)
+    providerSpy.mockImplementation(() => provider[providerSpy.mock.calls.length - 1].promise)
     meSpy.mockImplementation(() => me[meSpy.mock.calls.length - 1].promise)
     const store = useAuthStore()
 
     const first = store.checkAuth()
-    await Promise.resolve() // let probe 1 issue its /status call
-    expect(statusSpy).toHaveBeenCalledTimes(1)
+    await Promise.resolve() // let probe 1 issue its /auth/provider call
+    expect(providerSpy).toHaveBeenCalledTimes(1)
 
     const recovery = store.checkAuth({ fresh: true }) // reloadAfterAuth
-    expect(statusSpy).toHaveBeenCalledTimes(1) // queued, not joined and not issued yet
+    expect(providerSpy).toHaveBeenCalledTimes(1) // queued, not joined and not issued yet
 
-    status[0].resolve({ data: { edition: 'server' } })
+    provider[0].resolve({ display_name: 'Server SSO' })
     me[0].resolve(null)
     await first
     // The stale run settled, but the store is not "settled" until the fresh
     // probe behind it has too.
     expect(store.loading).toBe(true)
-    expect(statusSpy).toHaveBeenCalledTimes(2)
+    expect(providerSpy).toHaveBeenCalledTimes(2)
 
-    status[1].resolve({ data: { edition: 'server' } })
+    provider[1].resolve({ display_name: 'Server SSO' })
     me[1].resolve(tenant)
     await recovery
 
@@ -137,7 +136,7 @@ describe('auth store: concurrent checkAuth shares one in-flight probe', () => {
     second.settle()
     await q
 
-    expect(statusSpy).toHaveBeenCalledTimes(2)
+    expect(providerSpy).toHaveBeenCalledTimes(2)
     expect(store.isAdmin).toBe(true)
   })
 })
@@ -145,7 +144,7 @@ describe('auth store: concurrent checkAuth shares one in-flight probe', () => {
 describe('router guard: hard-reload deep link under the server edition', () => {
   beforeEach(() => {
     setActivePinia(createPinia())
-    statusSpy.mockReset()
+    providerSpy.mockReset()
     meSpy.mockReset()
   })
 
@@ -170,7 +169,7 @@ describe('router guard: hard-reload deep link under the server edition', () => {
 
       expect(router.currentRoute.value.name).toBe(name)
       expect(document.title).toBe(`${router.currentRoute.value.meta.title} - MCPProxy Control Panel`)
-      expect(statusSpy).toHaveBeenCalledTimes(1)
+      expect(providerSpy).toHaveBeenCalledTimes(1)
     })
 
     it(`admin: mount-time checkAuth racing the initial navigation to ${path} lands on ${name}`, async () => {
@@ -184,7 +183,7 @@ describe('router guard: hard-reload deep link under the server edition', () => {
       await Promise.all([mount, nav])
 
       expect(router.currentRoute.value.name).toBe(name)
-      expect(statusSpy).toHaveBeenCalledTimes(1)
+      expect(providerSpy).toHaveBeenCalledTimes(1)
     })
   }
 
@@ -218,9 +217,9 @@ describe('router guard: hard-reload deep link under the server edition', () => {
     // Probe 1 (stale key) says signed out; reloadAfterAuth queues probe 2
     // (repaired key) while the guard is still awaiting probe 1. The guard
     // must route on probe 2, not bounce the deep link to /login.
-    const status = [deferred<{ data: { edition: string } }>(), deferred<{ data: { edition: string } }>()]
+    const provider = [deferred<{ display_name: string }>(), deferred<{ display_name: string }>()]
     const me = [deferred<typeof tenant | null>(), deferred<typeof tenant | null>()]
-    statusSpy.mockImplementation(() => status[statusSpy.mock.calls.length - 1].promise)
+    providerSpy.mockImplementation(() => provider[providerSpy.mock.calls.length - 1].promise)
     meSpy.mockImplementation(() => me[meSpy.mock.calls.length - 1].promise)
     const store = useAuthStore()
     const router = makeRouter()
@@ -231,20 +230,20 @@ describe('router guard: hard-reload deep link under the server edition', () => {
     // few ticks, and it must have joined probe 1 BEFORE the fresh probe is
     // queued for this to exercise the drain (otherwise it joins probe 2).
     await new Promise((r) => setTimeout(r, 0))
-    expect(statusSpy).toHaveBeenCalledTimes(1)
+    expect(providerSpy).toHaveBeenCalledTimes(1)
     const recovery = store.checkAuth({ fresh: true })
 
-    status[0].resolve({ data: { edition: 'server' } })
+    provider[0].resolve({ display_name: 'Server SSO' })
     me[0].resolve(null)
     await mount
     expect(router.currentRoute.value.name).toBeUndefined() // still deciding
 
-    status[1].resolve({ data: { edition: 'server' } })
+    provider[1].resolve({ display_name: 'Server SSO' })
     me[1].resolve(tenant)
     await Promise.all([recovery, nav])
 
     expect(router.currentRoute.value.name).toBe('user-tokens')
-    expect(statusSpy).toHaveBeenCalledTimes(2)
+    expect(providerSpy).toHaveBeenCalledTimes(2)
   })
 
   it('guard alone (no mount call yet) still waits for the probe before deciding', async () => {
@@ -257,6 +256,6 @@ describe('router guard: hard-reload deep link under the server edition', () => {
     await nav
 
     expect(router.currentRoute.value.name).toBe('user-tokens')
-    expect(statusSpy).toHaveBeenCalledTimes(1)
+    expect(providerSpy).toHaveBeenCalledTimes(1)
   })
 })
diff --git a/frontend/tests/unit/auth-provider-probe.spec.ts b/frontend/tests/unit/auth-provider-probe.spec.ts
new file mode 100644
index 000000000..ec424704f
--- /dev/null
+++ b/frontend/tests/unit/auth-provider-probe.spec.ts
@@ -0,0 +1,168 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { mount } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { authApi } from '@/services/auth-api'
+import { useAuthStore } from '@/stores/auth'
+import Login from '@/views/teams/Login.vue'
+
+// The auth store must never need the operator's API key to learn the edition.
+// Stub the keyed API service so any authenticated call through it is visible
+// (and counted) rather than a real network request.
+const getStatus = vi.fn()
+vi.mock('@/services/api', () => ({
+  default: {
+    getStatus: (...args: unknown[]) => getStatus(...args),
+    hasAPIKey: vi.fn(() => false),
+  },
+}))
+
+type FetchLog = { url: string; init?: RequestInit }
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(status === 204 ? null : JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
+// Route each fetch by path so a test can script the probe and /auth/me
+// independently and then read back the call ORDER.
+function installFetch(routes: Record<string, () => Response>): FetchLog[] {
+  const log: FetchLog[] = []
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url
+      log.push({ url, init })
+      const path = url.replace(/\?.*$/, '')
+      const handler = routes[path]
+      if (!handler) return jsonResponse(404, { error: `unrouted ${path}` })
+      return handler()
+    }),
+  )
+  return log
+}
+
+/**
+ * Spec 107 FR-030 / FR-041 (PR-B, T054): `GET /api/v1/auth/provider` is the
+ * public, side-effect-free edition probe. A tenant holds no API key, so the
+ * old edition detection (`GET /api/v1/status` with the key, critic G1) 401'd
+ * for exactly the people the server edition exists for. The store must learn
+ * the edition from the probe BEFORE any authenticated call, and the login page
+ * must label its button with the operator-chosen `display_name`.
+ */
+describe('auth-api provider probe (Spec 107 FR-030)', () => {
+  afterEach(() => vi.unstubAllGlobals())
+
+  it('GETs /api/v1/auth/provider and returns only the display_name', async () => {
+    const log = installFetch({
+      '/api/v1/auth/provider': () => jsonResponse(200, { display_name: 'Acme Okta' }),
+    })
+    const res = await authApi.getProvider()
+    expect(res).toEqual({ display_name: 'Acme Okta' })
+    expect(log).toHaveLength(1)
+    expect(log[0].url).toBe('/api/v1/auth/provider')
+    expect(log[0].init?.method ?? 'GET').toBe('GET')
+    // Public probe: it carries no API key header.
+    const headers = new Headers(log[0].init?.headers)
+    expect(headers.get('X-API-Key')).toBeNull()
+  })
+
+  it('answers null on 404 — the personal build, or server_edition.enabled=false', async () => {
+    installFetch({ '/api/v1/auth/provider': () => jsonResponse(404, { error: 'not found' }) })
+    expect(await authApi.getProvider()).toBeNull()
+  })
+
+  it('answers null when the probe cannot be reached at all', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => { throw new TypeError('network down') }))
+    expect(await authApi.getProvider()).toBeNull()
+  })
+})
+
+describe('auth store edition detection (Spec 107 FR-041)', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    getStatus.mockReset()
+    getStatus.mockResolvedValue({ success: true, data: { edition: 'server' } })
+  })
+  afterEach(() => vi.unstubAllGlobals())
+
+  it('learns the server edition from the probe before /auth/me, never from a keyed call', async () => {
+    const log = installFetch({
+      '/api/v1/auth/provider': () => jsonResponse(200, { display_name: 'Acme Okta' }),
+      '/api/v1/auth/me': () =>
+        jsonResponse(200, { id: 'u1', email: 'a@acme.test', display_name: 'A', role: 'user', provider: 'oidc' }),
+    })
+    const store = useAuthStore()
+    await store.checkAuth()
+
+    expect(store.isTeamsEdition).toBe(true)
+    expect(store.provider?.display_name).toBe('Acme Okta')
+    expect(store.isAuthenticated).toBe(true)
+    expect(store.loading).toBe(false)
+
+    const paths = log.map((l) => l.url.replace(/\?.*$/, ''))
+    expect(paths.indexOf('/api/v1/auth/provider')).toBe(0)
+    expect(paths.indexOf('/api/v1/auth/me')).toBeGreaterThan(paths.indexOf('/api/v1/auth/provider'))
+    // The keyed status call is not how the edition is learned any more.
+    expect(getStatus).not.toHaveBeenCalled()
+    expect(paths).not.toContain('/api/v1/status')
+  })
+
+  it('treats a 404 from the probe as the personal edition and makes no authenticated call', async () => {
+    const log = installFetch({
+      '/api/v1/auth/provider': () => jsonResponse(404, { error: 'not found' }),
+    })
+    const store = useAuthStore()
+    await store.checkAuth()
+
+    expect(store.isTeamsEdition).toBe(false)
+    expect(store.provider).toBeNull()
+    expect(store.user).toBeNull()
+    expect(store.loading).toBe(false)
+    const paths = log.map((l) => l.url.replace(/\?.*$/, ''))
+    expect(paths).toEqual(['/api/v1/auth/provider'])
+    expect(getStatus).not.toHaveBeenCalled()
+  })
+
+  it('keeps the edition and label when the session is missing (the /login case)', async () => {
+    installFetch({
+      '/api/v1/auth/provider': () => jsonResponse(200, { display_name: 'Acme Okta' }),
+      '/api/v1/auth/me': () => jsonResponse(401, { error: 'unauthorized' }),
+    })
+    const store = useAuthStore()
+    await store.checkAuth()
+    expect(store.isTeamsEdition).toBe(true)
+    expect(store.provider?.display_name).toBe('Acme Okta')
+    expect(store.isAuthenticated).toBe(false)
+  })
+})
+
+describe('Login.vue provider label (Spec 107 FR-030)', () => {
+  beforeEach(() => setActivePinia(createPinia()))
+  afterEach(() => vi.unstubAllGlobals())
+
+  it('labels the button with the probe display_name instead of a hardcoded organization', async () => {
+    const store = useAuthStore()
+    store.provider = { display_name: 'Acme Okta' }
+    const wrapper = mount(Login)
+    const btn = wrapper.find('button')
+    expect(btn.text()).toBe('Sign in with Acme Okta')
+    expect(wrapper.text()).not.toContain('your organization')
+  })
+
+  it('reacts when the probe result lands after mount', async () => {
+    const store = useAuthStore()
+    const wrapper = mount(Login)
+    store.provider = { display_name: 'Contoso Entra' }
+    await wrapper.vm.$nextTick()
+    expect(wrapper.find('button').text()).toBe('Sign in with Contoso Entra')
+  })
+
+  it('never leaks anything but the label (no issuer / client id in the DOM)', async () => {
+    const store = useAuthStore()
+    store.provider = { display_name: 'Acme Okta' }
+    const wrapper = mount(Login)
+    expect(wrapper.html()).not.toMatch(/issuer|client_id|tenant/i)
+  })
+})
diff --git a/frontend/tests/unit/settings-server-edition-wording.spec.ts b/frontend/tests/unit/settings-server-edition-wording.spec.ts
index 49acbaa9c..2c4263301 100644
--- a/frontend/tests/unit/settings-server-edition-wording.spec.ts
+++ b/frontend/tests/unit/settings-server-edition-wording.spec.ts
@@ -3,6 +3,10 @@ import {
   SERVER_EDITION_TAB_LABEL,
   SERVER_EDITION_SECTION_TITLE,
   SERVER_EDITION_FIELDS,
+  SECURITY_FIELDS,
+  hydrateConfigState,
+  buildPartial,
+  getPath,
 } from '../../src/views/settings/fields'
 
 // MCP-1087: the Settings server-edition surface must read "Server Edition",
@@ -35,3 +39,141 @@ describe('Settings server-edition wording (MCP-1087)', () => {
     expect(keys).not.toContain('server_edition.max_user_servers')
   })
 })
+
+// Spec 107 PR-B (T054, US2): the server-edition row set is asserted EXACTLY so
+// an undecided key can never appear by accident. The `Settings` disposition
+// paragraph of `specs/107-server-edition-sso-hardening/contracts/config-keys.md`
+// is the authority: rows for the OIDC + front-door keys; Raw-JSON-only for
+// `access.*`, `oauth.allow_insecure_issuer` (a loopback-only development
+// toggle that must not look like a normal setting) and the retained keys with
+// no row today; NEVER a row for the secrets (`oauth.client_secret`,
+// `credential_encryption_key`) or the deprecated no-op `store_idp_tokens`.
+describe('Settings server-edition row set (Spec 107 T054)', () => {
+  const keys = () => SERVER_EDITION_FIELDS.map((f) => f.key)
+  const byKey = (k: string) => SERVER_EDITION_FIELDS.find((f) => f.key === k)
+
+  it('exposes exactly the contract row set, in catalogue order', () => {
+    expect(keys()).toEqual([
+      'server_edition.enabled',
+      'server_edition.oauth.provider',
+      'server_edition.oauth.display_name',
+      'server_edition.oauth.issuer_url',
+      'server_edition.oauth.scopes',
+      'server_edition.oauth.groups_claim',
+      'server_edition.oauth.email_verified_policy',
+      'server_edition.public_url',
+      'server_edition.session_cookie_secure',
+    ])
+  })
+
+  it('never offers a row for a secret, the deprecated no-op, or a Raw-JSON-only key', () => {
+    for (const k of [
+      'server_edition.oauth.client_secret',
+      'server_edition.credential_encryption_key',
+      'server_edition.store_idp_tokens',
+      'server_edition.oauth.allow_insecure_issuer',
+      'server_edition.admin_emails',
+      'server_edition.session_ttl',
+      'server_edition.bearer_token_ttl',
+      'server_edition.oauth.client_id',
+      'server_edition.oauth.tenant_id',
+      'server_edition.oauth.allowed_domains',
+      'server_edition.access',
+      'server_edition.access.group_servers',
+      'server_edition.access.default_servers',
+      'server_edition.max_user_servers',
+      'server_edition.workspace_idle_timeout',
+    ]) {
+      expect(keys(), k).not.toContain(k)
+    }
+    // Belt and braces: no row's key mentions a secret by any spelling.
+    for (const k of keys()) expect(k).not.toMatch(/secret|encryption_key/)
+  })
+
+  it('adds `oidc` to the provider family select', () => {
+    const provider = byKey('server_edition.oauth.provider')
+    expect(provider?.control).toBe('select')
+    expect(provider?.options?.map((o) => o.value)).toEqual(['', 'google', 'github', 'microsoft', 'oidc'])
+  })
+
+  it('marks every server_edition row restart-pinned (all bound at login handler construction)', () => {
+    for (const f of SERVER_EDITION_FIELDS) expect(f.restart, f.key).toBe(true)
+  })
+
+  it('types the OIDC rows per the contract', () => {
+    const issuer = byKey('server_edition.oauth.issuer_url')
+    expect(issuer?.control).toBe('text')
+    expect(issuer?.valueKind).toBe('url')
+    expect(issuer?.optional).toBe(true) // only required for provider=oidc — the backend refuses, not the form
+
+    const scopes = byKey('server_edition.oauth.scopes')
+    expect(scopes?.control).toBe('textarea')
+    expect(scopes?.listKind).toBe('comma')
+
+    expect(byKey('server_edition.oauth.groups_claim')?.control).toBe('text')
+    expect(byKey('server_edition.oauth.display_name')?.control).toBe('text')
+
+    const policy = byKey('server_edition.oauth.email_verified_policy')
+    expect(policy?.control).toBe('select')
+    expect(policy?.options?.map((o) => o.value)).toEqual(['refuse_false', 'require_true', 'ignore'])
+  })
+
+  it('types the front-door rows per the contract', () => {
+    const pub = byKey('server_edition.public_url')
+    expect(pub?.control).toBe('text')
+    expect(pub?.valueKind).toBe('url')
+    expect(pub?.optional).toBe(true)
+
+    const cookie = byKey('server_edition.session_cookie_secure')
+    expect(cookie?.control).toBe('select')
+    expect(cookie?.options?.map((o) => o.value)).toEqual(['auto', 'true', 'false'])
+  })
+})
+
+// `trusted_proxies` is edition-neutral (top-level, FR-027) and LIVE, so it is a
+// Security & Access row — one CIDR or IP per line — not a server-edition row.
+describe('Settings trusted_proxies row (Spec 107 T054)', () => {
+  it('lives in the Security section as a live one-per-line textarea', () => {
+    const f = SECURITY_FIELDS.find((x) => x.key === 'trusted_proxies')
+    expect(f).toBeDefined()
+    expect(f?.control).toBe('textarea')
+    expect(f?.listKind).toBe('lines')
+    expect(f?.restart).toBeFalsy()
+    expect(SERVER_EDITION_FIELDS.map((x) => x.key)).not.toContain('trusted_proxies')
+  })
+})
+
+// A `[]string` config key edited through a textarea must round-trip as a real
+// JSON array: the form shows a joined string, the PATCH carries the split list.
+// Without this the textarea would PATCH `"openid, profile"` (a string) into a
+// `[]string` key and the server-edition decoder would refuse it.
+describe('list-kind textarea round trip (Spec 107 T054)', () => {
+  it('hydrates arrays as joined text on both working and original, leaving raw untouched', () => {
+    const cfg = {
+      trusted_proxies: ['10.0.0.0/8', '192.168.1.1'],
+      server_edition: { oauth: { scopes: ['openid', 'email'] } },
+    }
+    const { working, original, raw } = hydrateConfigState(cfg)
+    expect(getPath(working, 'trusted_proxies')).toBe('10.0.0.0/8\n192.168.1.1')
+    expect(getPath(original, 'trusted_proxies')).toBe('10.0.0.0/8\n192.168.1.1')
+    expect(getPath(working, 'server_edition.oauth.scopes')).toBe('openid, email')
+    expect(getPath(original, 'server_edition.oauth.scopes')).toBe('openid, email')
+    expect(raw.trusted_proxies).toEqual(['10.0.0.0/8', '192.168.1.1'])
+    expect(raw.server_edition.oauth.scopes).toEqual(['openid', 'email'])
+  })
+
+  it('splits joined text back into a trimmed array in the PATCH partial', () => {
+    const working = {
+      trusted_proxies: ' 10.0.0.0/8 \n\n192.168.1.1\n',
+      server_edition: { oauth: { scopes: 'openid, profile,email' } },
+    }
+    const partial = buildPartial(working, ['trusted_proxies', 'server_edition.oauth.scopes'])
+    expect(partial.trusted_proxies).toEqual(['10.0.0.0/8', '192.168.1.1'])
+    expect(partial.server_edition.oauth.scopes).toEqual(['openid', 'profile', 'email'])
+  })
+
+  it('sends an empty list, not a string, when the textarea is cleared', () => {
+    const partial = buildPartial({ trusted_proxies: '' }, ['trusted_proxies'])
+    expect(partial.trusted_proxies).toEqual([])
+  })
+})
diff --git a/internal/config/config.go b/internal/config/config.go
index 2cbdf074c..b53619333 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -377,7 +377,13 @@ type Config struct {
 	// Origin header when present (MCP spec DNS-rebinding defense). Empty
 	// (default) keeps full protection. Env override: MCPPROXY_TRUSTED_HOSTS
 	// (comma-separated).
-	TrustedHosts      []string `json:"trusted_hosts,omitempty" mapstructure:"trusted-hosts"`
+	TrustedHosts []string `json:"trusted_hosts,omitempty" mapstructure:"trusted-hosts"`
+	// TrustedProxies lists the CIDRs or IP addresses whose X-Forwarded-For /
+	// X-Real-IP / X-Forwarded-Proto / X-Forwarded-Host headers are believed
+	// (Spec 107 FR-027). Empty (default) trusts nobody. Edition-neutral, live
+	// (hot-reloadable). Env override: MCPPROXY_TRUSTED_PROXIES (comma-separated).
+	// The one reader is ForwardedHeaders; validation is validateTrustedProxies.
+	TrustedProxies    []string `json:"trusted_proxies,omitempty" mapstructure:"trusted-proxies"`
 	ReadOnlyMode      bool     `json:"read_only_mode" mapstructure:"read-only-mode"`
 	DisableManagement bool     `json:"disable_management" mapstructure:"disable-management"`
 	AllowServerAdd    bool     `json:"allow_server_add" mapstructure:"allow-server-add"`
@@ -2623,6 +2629,10 @@ func (c *Config) validateDetailedCore() []ValidationError {
 		}
 	}
 
+	// Spec 107 FR-027/FR-039: every trusted_proxies entry must parse as a
+	// CIDR or IP on every door (boot, PATCH, /config/apply).
+	errors = append(errors, validateTrustedProxies(c)...)
+
 	// Spec 107 FR-039: the server_edition block is validated (never mutated)
 	// on every door — boot, PATCH and /config/apply. No-op in the personal
 	// edition (stub); enforced in the server edition.
diff --git a/internal/config/config_validate_serveredition.go b/internal/config/config_validate_serveredition.go
index fe37ed24c..eaaf17eb1 100644
--- a/internal/config/config_validate_serveredition.go
+++ b/internal/config/config_validate_serveredition.go
@@ -14,5 +14,12 @@ func validateServerEditionConfig(cfg *Config) []ValidationError {
 	if err := cfg.ServerEdition.Validate(); err != nil {
 		return []ValidationError{{Field: "server_edition", Message: err.Error()}}
 	}
+	// The tls.enabled half of the session_cookie_secure=false refusal (Spec
+	// 107 FR-026) needs the top-level TLS block the nested Validate cannot
+	// see; the https-public_url half lives in ServerEditionConfig.Validate.
+	if cfg.ServerEdition.Enabled && cfg.ServerEdition.SessionCookieSecure == SessionCookieSecureFalse &&
+		cfg.TLS != nil && cfg.TLS.Enabled {
+		return []ValidationError{{Field: "server_edition.session_cookie_secure", Message: msgSessionCookieSecureFalse}}
+	}
 	return nil
 }
diff --git a/internal/config/doctor_findings.go b/internal/config/doctor_findings.go
new file mode 100644
index 000000000..8ab396e70
--- /dev/null
+++ b/internal/config/doctor_findings.go
@@ -0,0 +1,18 @@
+package config
+
+// MsgRequireMCPAuthOverridden is the boot notice and doctor finding text of
+// contracts/config-keys.md for an explicit require_mcp_auth: false under an
+// enabled server-edition block (Spec 107 FR-029).
+const MsgRequireMCPAuthOverridden = "require_mcp_auth: false is overridden to true because server_edition.enabled is true"
+
+// DoctorFindings returns the configuration findings `mcpproxy doctor` renders
+// as runtime_warnings (Spec 107 T052). It reads the config it is handed — the
+// caller passes the LIVE snapshot — and never mutates it. Edition-neutral
+// findings live here; the server-only ones come from the build-tagged
+// serverEditionDoctorFindings (a no-op on the personal build).
+func DoctorFindings(cfg *Config) []string {
+	if cfg == nil {
+		return nil
+	}
+	return serverEditionDoctorFindings(cfg)
+}
diff --git a/internal/config/doctor_findings_serveredition.go b/internal/config/doctor_findings_serveredition.go
new file mode 100644
index 000000000..359ddb922
--- /dev/null
+++ b/internal/config/doctor_findings_serveredition.go
@@ -0,0 +1,48 @@
+//go:build server
+
+package config
+
+import (
+	"fmt"
+	"net"
+)
+
+// serverEditionDoctorFindings are the server-only doctor findings of Spec 107:
+// an overridden require_mcp_auth (FR-029), an unset public_url on a
+// non-loopback listener (FR-025) and an explicit session_cookie_secure: false
+// (FR-026). T074 adds the unknown access-map names.
+func serverEditionDoctorFindings(cfg *Config) []string {
+	if !ServerEditionEnabled(cfg) {
+		return nil
+	}
+	var out []string
+	if RequireMCPAuthOverridden(cfg) {
+		out = append(out, MsgRequireMCPAuthOverridden)
+	}
+	if cfg.ServerEdition.PublicURL == "" && !ListenIsLoopback(cfg.Listen) {
+		out = append(out, fmt.Sprintf("server_edition.public_url is unset while listening on %s: set it (or MCPPROXY_PUBLIC_URL) to the origin users reach so the OAuth callback URL and Secure cookie decision do not depend on Host or X-Forwarded-* headers", cfg.Listen))
+	}
+	if cfg.ServerEdition.SessionCookieSecure == SessionCookieSecureFalse {
+		out = append(out, "server_edition.session_cookie_secure is explicitly false: the session cookie is sent over plain http; only a loopback or test deployment should run this way")
+	}
+	return out
+}
+
+// ListenIsLoopback reports whether a listen address binds a loopback
+// interface only. An empty or port-only address (":8080") and the unspecified
+// addresses (0.0.0.0, [::]) are non-loopback; an unparsable host is treated
+// as non-loopback so the warning errs on the side of being shown.
+func ListenIsLoopback(listen string) bool {
+	host, _, err := net.SplitHostPort(listen)
+	if err != nil {
+		host = listen
+	}
+	if host == "" {
+		return false
+	}
+	if host == "localhost" {
+		return true
+	}
+	ip := net.ParseIP(host)
+	return ip != nil && ip.IsLoopback()
+}
diff --git a/internal/config/doctor_findings_stub.go b/internal/config/doctor_findings_stub.go
new file mode 100644
index 000000000..9040a3bad
--- /dev/null
+++ b/internal/config/doctor_findings_stub.go
@@ -0,0 +1,7 @@
+//go:build !server
+
+package config
+
+// serverEditionDoctorFindings has nothing to report on the personal build:
+// the server_edition block is an opaque carrier there (Spec 107 FR-040).
+func serverEditionDoctorFindings(_ *Config) []string { return nil }
diff --git a/internal/config/env_public_url_personal_test.go b/internal/config/env_public_url_personal_test.go
new file mode 100644
index 000000000..dea76ceaf
--- /dev/null
+++ b/internal/config/env_public_url_personal_test.go
@@ -0,0 +1,56 @@
+//go:build !server
+
+package config_test
+
+// Spec 107 T048 (FR-025, FR-040): MCPPROXY_PUBLIC_URL is the one nested
+// `server_edition.*` key with an env alias, applied by the build-tagged
+// applyServerEditionEnvOverrides (T051). The personal build's stub is a
+// no-op: the block is an opaque carrier there, so the variable must leave
+// the document's bytes untouched in meaning — the file's public_url survives
+// and the env value never appears. This is the personal twin of
+// TestFrontDoor_PublicURLEnvOverride (internal/serveredition/front_door_test.go);
+// it is green on the PR-B base by construction and pins that T051's stub stays
+// a no-op.
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+)
+
+func TestPersonalBuild_PublicURLEnvIsIgnored(t *testing.T) {
+	dir := t.TempDir()
+	doc := map[string]any{
+		"listen":   "127.0.0.1:8080",
+		"data_dir": dir,
+		"server_edition": map[string]any{
+			"enabled":      true,
+			"admin_emails": []string{"admin@example.com"},
+			"oauth":        map[string]any{"provider": "google", "client_id": "cid", "client_secret": "csec"},
+			"public_url":   "https://file.example",
+		},
+	}
+	data, err := json.Marshal(doc)
+	require.NoError(t, err)
+	path := filepath.Join(dir, "mcp_config.json")
+	require.NoError(t, os.WriteFile(path, data, 0600))
+
+	t.Setenv("MCPPROXY_PUBLIC_URL", "https://env.example")
+
+	cfg, err := config.LoadFromFile(path)
+	require.NoError(t, err)
+	require.NotNil(t, cfg.ServerEdition, "the carrier must survive the load")
+
+	carrier, err := json.Marshal(cfg.ServerEdition)
+	require.NoError(t, err)
+	var block map[string]any
+	require.NoError(t, json.Unmarshal(carrier, &block))
+	assert.Equal(t, "https://file.example", block["public_url"], "the personal build never interprets the variable")
+	assert.NotContains(t, string(carrier), "env.example")
+}
diff --git a/internal/config/env_serveredition.go b/internal/config/env_serveredition.go
new file mode 100644
index 000000000..7acf2b901
--- /dev/null
+++ b/internal/config/env_serveredition.go
@@ -0,0 +1,33 @@
+//go:build server
+
+package config
+
+import (
+	"os"
+	"strings"
+)
+
+// EnvPublicURL is the environment alias of server_edition.public_url — the
+// one nested `server_edition.*` key with an env alias (Spec 107 FR-025).
+const EnvPublicURL = "MCPPROXY_PUBLIC_URL"
+
+// applyServerEditionEnvOverrides applies MCPPROXY_PUBLIC_URL over the file
+// value. An unset or blank variable leaves the file value alone. The override
+// runs before Validate in LoadFromFile, so an invalid value is refused with the
+// same message as a file value. A document without a server_edition block
+// gains one only to carry the override (disabled, so no rule applies).
+func applyServerEditionEnvOverrides(cfg *Config) {
+	// Trimmed before the blank check (cross-review round 1, chunk 3 P3): a
+	// whitespace-only value (e.g. an env file with a stray space) used to
+	// pass the `!= ""` gate, overwrite a valid file value with a non-empty
+	// but unparsable string, and fail startup validation — contradicting
+	// this function's own "blank leaves the file value alone" contract.
+	value := strings.TrimSpace(os.Getenv(EnvPublicURL))
+	if value == "" || cfg == nil {
+		return
+	}
+	if cfg.ServerEdition == nil {
+		cfg.ServerEdition = &ServerEditionConfig{}
+	}
+	cfg.ServerEdition.PublicURL = value
+}
diff --git a/internal/config/env_serveredition_stub.go b/internal/config/env_serveredition_stub.go
new file mode 100644
index 000000000..ffb64e82a
--- /dev/null
+++ b/internal/config/env_serveredition_stub.go
@@ -0,0 +1,8 @@
+//go:build !server
+
+package config
+
+// applyServerEditionEnvOverrides is a no-op in the personal edition: the
+// server_edition block is an opaque carrier there (Spec 107 FR-040) and
+// MCPPROXY_PUBLIC_URL is never interpreted.
+func applyServerEditionEnvOverrides(_ *Config) {}
diff --git a/internal/config/loader.go b/internal/config/loader.go
index f75ff6a35..e750231fb 100644
--- a/internal/config/loader.go
+++ b/internal/config/loader.go
@@ -61,6 +61,17 @@ func LoadFromFile(configPath string) (*Config, error) {
 
 	// Expand secret/env refs in DataDir before creating it
 	expandDataDir(cfg)
+	// server_edition.oauth.client_id/client_secret are deliberately NOT
+	// expanded here (cross-review round 6, chunk 3 P2, superseding round 1's
+	// in-place expansion): this cfg is what becomes r.cfg/r.desiredCfg and is
+	// round-tripped back to disk by SaveConfig on every later PATCH
+	// /api/v1/config or /config/apply, so resolving the secret into it here
+	// would persist the plaintext value instead of the operator's
+	// `${env:...}` reference. ServerEditionConfig.Validate() (reached just
+	// below) resolves it itself, read-only, to enforce the "required" check
+	// against the actual value; auth.NewOAuthHandler resolves it again on its
+	// own private, never-persisted config clone to get the live secret for
+	// the token endpoint.
 
 	// Create data directory if it doesn't exist.
 	// Skip if the path still contains unresolved ${...} refs (e.g., missing env var) —
@@ -186,6 +197,9 @@ func LoadWithPath() (*Config, string, error) {
 
 	// Expand secret/env refs in DataDir before creating it
 	expandDataDir(cfg)
+	// server_edition.oauth.client_id/client_secret are deliberately NOT
+	// expanded here — see the matching comment in LoadFromFile (cross-review
+	// round 6, chunk 3 P2).
 
 	// Create data directory if it doesn't exist.
 	// Skip if the path still contains unresolved ${...} refs (e.g., missing env var) —
@@ -724,6 +738,18 @@ func applyTLSEnvOverrides(cfg *Config) {
 		cfg.TrustedHosts = hosts
 	}
 
+	// Override trusted proxies (Spec 107 FR-027). Comma-separated CIDRs or
+	// IPs; an empty variable leaves the file value. Entries are validated by
+	// validateTrustedProxies exactly like file values (LoadFromFile validates
+	// after the overrides run).
+	if value := os.Getenv("MCPPROXY_TRUSTED_PROXIES"); strings.TrimSpace(value) != "" {
+		cfg.TrustedProxies = parseTrustedProxiesEnv(value)
+	}
+
+	// Spec 107 FR-025: MCPPROXY_PUBLIC_URL, the one nested server_edition.*
+	// key with an env alias. Build-tagged: a no-op on the personal build.
+	applyServerEditionEnvOverrides(cfg)
+
 	// Override the offline TPA signature-bundle path from environment
 	// (spec 086 FR-019). Explicit MCPPROXY_* alias per the loader convention;
 	// the env value wins over the file value, and materializes the security
diff --git a/internal/config/server_edition_config.go b/internal/config/server_edition_config.go
index 86958245a..5f9ad4da7 100644
--- a/internal/config/server_edition_config.go
+++ b/internal/config/server_edition_config.go
@@ -3,10 +3,15 @@
 package config
 
 import (
+	"context"
 	"fmt"
+	"net"
+	"net/url"
 	"os"
 	"strings"
 	"time"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/secret"
 )
 
 // ServerEditionConfig holds configuration for the server edition multi-user features.
@@ -30,17 +35,151 @@ type ServerEditionConfig struct {
 	// loading (Spec 107 FR-033). IdP tokens are no longer persisted at login;
 	// `true` records one deprecation LoadDiagnostic at load time.
 	StoreIDPTokens bool `json:"store_idp_tokens" mapstructure:"store-idp-tokens"`
+
+	// PublicURL is the absolute origin (scheme://host[:port], no path) the
+	// deployment is reached at (Spec 107 FR-025). When set it is the sole
+	// source of the OAuth callback URL and the connect-flow base URL; Host and
+	// X-Forwarded-* are then ignored. Env alias: MCPPROXY_PUBLIC_URL.
+	PublicURL string `json:"public_url,omitempty" mapstructure:"public-url"`
+	// SessionCookieSecure is the Secure-attribute policy of the session cookie
+	// (Spec 107 FR-026): "auto" (default — https public_url, in-process TLS or
+	// a trusted X-Forwarded-Proto: https), "true" or "false".
+	SessionCookieSecure string `json:"session_cookie_secure,omitempty" mapstructure:"session-cookie-secure"`
+}
+
+// Session cookie Secure policies (Spec 107 FR-026).
+const (
+	SessionCookieSecureAuto  = "auto"
+	SessionCookieSecureTrue  = "true"
+	SessionCookieSecureFalse = "false"
+)
+
+// Validation messages fixed by contracts/config-keys.md (FR-039: boot, PATCH
+// and /config/apply say the same thing).
+const (
+	msgPublicURLShape            = "server_edition.public_url must be an absolute origin (scheme://host[:port]) with no path"
+	msgSessionCookieSecureFalse  = "server_edition.session_cookie_secure=false cannot be combined with an https public_url or tls.enabled"
+	msgSessionCookieSecurePolicy = "server_edition.session_cookie_secure must be one of: auto, true, false"
+)
+
+// ValidatePublicURL checks the public_url shape: absolute http(s) origin,
+// host present, no userinfo, path, query or fragment. Empty is valid (unset).
+func ValidatePublicURL(raw string) error {
+	if raw == "" {
+		return nil
+	}
+	u, err := url.Parse(raw)
+	if err != nil {
+		return fmt.Errorf("%s (got: %q)", msgPublicURLShape, raw)
+	}
+	// u.Host == "" alone does not catch "https://:443": Go's url.Parse leaves
+	// a non-empty Host (":443") with an EMPTY Hostname() when only a port is
+	// given, and that value went on to build a malformed OAuth callback /
+	// connect-flow URL (cross-review round 1, chunk 3 P2).
+	if (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" || u.Hostname() == "" || u.User != nil ||
+		u.Path != "" || u.RawPath != "" || u.RawQuery != "" || u.Fragment != "" || u.Opaque != "" ||
+		strings.Contains(raw, "?") || strings.Contains(raw, "#") {
+		return fmt.Errorf("%s (got: %q)", msgPublicURLShape, raw)
+	}
+	return nil
+}
+
+// resolveOAuthSecretRef resolves a `${env:...}` / `${keyring:...}` reference
+// (or returns a literal value unchanged) WITHOUT mutating the caller's
+// config — deliberately, unlike an earlier design (cross-review round 6,
+// chunk 3 P2): resolving `server_edition.oauth.client_id`/`client_secret` in
+// place at Load time meant the resolved plaintext secret lived in the same
+// Config object that GetDesiredConfig/ApplyConfig round-trip through
+// SaveConfig on every PATCH /api/v1/config or /config/apply — even one
+// editing an unrelated field — permanently overwriting the operator's
+// `${env:...}` reference in mcp_config.json with the resolved secret and
+// defeating docs/configuration/config-file.md's documented purpose of
+// keeping it out of the file. Every doc page for this block —
+// docs/configuration/config-file.md, docs/getting-started/installation.md,
+// docs/development/server-edition-multiuser-auth.md,
+// scripts/dev-server-edition.sh — tells the operator to write
+// `${env:OIDC_CLIENT_SECRET}`; ServerEditionConfig.Validate() calls this to
+// enforce the "required" check against the RESOLVED value (so a missing env
+// var is refused by "client_secret is required", never silently accepted as
+// the non-empty placeholder text — cross-review rounds 1 and 2), and
+// auth.NewOAuthHandler calls the identical `secret.Resolver` on its own
+// private, never-persisted config clone to get the actual value for the
+// token endpoint. An empty input resolves to "" with no error (client_id and
+// client_secret share the same "is required" check for the empty case).
+func resolveOAuthSecretRef(raw string) (string, error) {
+	if raw == "" {
+		return "", nil
+	}
+	return secret.NewResolver().ExpandSecretRefs(context.Background(), raw)
+}
+
+// PublicURLIsHTTPS reports whether the configured public_url uses https.
+func (c *ServerEditionConfig) PublicURLIsHTTPS() bool {
+	return c != nil && strings.HasPrefix(strings.ToLower(c.PublicURL), "https://")
+}
+
+// EffectiveSessionCookieSecure returns the policy with "" read as "auto".
+func (c *ServerEditionConfig) EffectiveSessionCookieSecure() string {
+	if c == nil || c.SessionCookieSecure == "" {
+		return SessionCookieSecureAuto
+	}
+	return c.SessionCookieSecure
 }
 
 // ServerEditionOAuthConfig holds OAuth identity provider configuration for the server edition.
+//
+// Spec 107 FR-020 adds the generic `oidc` provider (OpenID Connect Discovery +
+// a verified ID token) beside the three legacy providers. The six keys below
+// `AllowedDomains` are `oidc` concerns (contracts/config-keys.md); the legacy
+// providers ignore them.
 type ServerEditionOAuthConfig struct {
-	Provider       string   `json:"provider" mapstructure:"provider"` // "google", "github", "microsoft"
+	Provider       string   `json:"provider" mapstructure:"provider"` // "google", "github", "microsoft", "oidc"
 	ClientID       string   `json:"client_id" mapstructure:"client-id"`
 	ClientSecret   string   `json:"client_secret" mapstructure:"client-secret"`
 	TenantID       string   `json:"tenant_id,omitempty" mapstructure:"tenant-id"` // Microsoft only
 	AllowedDomains []string `json:"allowed_domains,omitempty" mapstructure:"allowed-domains"`
+
+	// IssuerURL is the OpenID Provider issuer (required for `oidc`). Discovery
+	// reads `<issuer_url>/.well-known/openid-configuration` lazily on the first
+	// login, and the ID token's `iss` must equal it byte for byte. It must be
+	// https, or http only for a loopback host with AllowInsecureIssuer.
+	IssuerURL string `json:"issuer_url,omitempty" mapstructure:"issuer-url"`
+	// AllowInsecureIssuer admits a plain-http issuer (and plain-http discovered
+	// endpoints) when — and only when — the host is loopback. A development
+	// toggle for the in-process fake IdP; non-loopback http is refused
+	// regardless.
+	AllowInsecureIssuer bool `json:"allow_insecure_issuer,omitempty" mapstructure:"allow-insecure-issuer"`
+	// Scopes requested on the authorization request (`oidc`). Default
+	// ["openid","profile","email"]; ApplyDefaults appends "openid" if missing.
+	Scopes []string `json:"scopes,omitempty" mapstructure:"scopes"`
+	// GroupsClaim names the ID-token / userinfo claim carrying the user's
+	// groups (`oidc`). Default "groups".
+	GroupsClaim string `json:"groups_claim,omitempty" mapstructure:"groups-claim"`
+	// EmailVerifiedPolicy decides what an `email_verified` claim of false or
+	// absent does to an `oidc` login: refuse_false (default: refuse only an
+	// explicit false), require_true (refuse false and absent) or ignore.
+	EmailVerifiedPolicy string `json:"email_verified_policy,omitempty" mapstructure:"email-verified-policy"`
+	// DisplayName is the login-button label (<= 64 chars); falls back to the
+	// provider family name when empty.
+	DisplayName string `json:"display_name,omitempty" mapstructure:"display-name"`
 }
 
+// Email-verified policies (server_edition.oauth.email_verified_policy).
+const (
+	EmailVerifiedPolicyRefuseFalse = "refuse_false"
+	EmailVerifiedPolicyRequireTrue = "require_true"
+	EmailVerifiedPolicyIgnore      = "ignore"
+)
+
+// OIDC defaults applied by ApplyDefaults for provider "oidc".
+const (
+	defaultOIDCGroupsClaim = "groups"
+	maxOAuthDisplayNameLen = 64
+)
+
+// defaultOIDCScopes is the scope set requested when `scopes` is unset.
+func defaultOIDCScopes() []string { return []string{"openid", "profile", "email"} }
+
 // defaultServerEditionTTL is the default for session_ttl and bearer_token_ttl.
 const defaultServerEditionTTL = Duration(24 * time.Hour)
 
@@ -81,12 +220,18 @@ func (c *ServerEditionConfig) ApplyDefaults() {
 	if c.OAuth != nil && c.OAuth.Provider == "microsoft" && c.OAuth.TenantID == "" {
 		c.OAuth.TenantID = "common"
 	}
+	if c.OAuth != nil && c.OAuth.Provider == "oidc" {
+		c.OAuth.applyOIDCDefaults()
+	}
 	if c.SessionTTL.Duration() <= 0 {
 		c.SessionTTL = defaultServerEditionTTL
 	}
 	if c.BearerTokenTTL.Duration() <= 0 {
 		c.BearerTokenTTL = defaultServerEditionTTL
 	}
+	if c.SessionCookieSecure == "" {
+		c.SessionCookieSecure = SessionCookieSecureAuto
+	}
 }
 
 // Validate checks that the ServerEditionConfig is valid for operation. It is
@@ -103,16 +248,44 @@ func (c *ServerEditionConfig) Validate() error {
 	if c.OAuth == nil {
 		return fmt.Errorf("server_edition.oauth configuration is required when server_edition is enabled")
 	}
-	validProviders := map[string]bool{"google": true, "github": true, "microsoft": true}
+	validProviders := map[string]bool{"google": true, "github": true, "microsoft": true, "oidc": true}
 	if !validProviders[c.OAuth.Provider] {
-		return fmt.Errorf("server_edition.oauth.provider must be one of: google, github, microsoft (got: %s)", c.OAuth.Provider)
+		return fmt.Errorf("server_edition.oauth.provider must be one of: google, github, microsoft, oidc (got: %s)", c.OAuth.Provider)
 	}
-	if c.OAuth.ClientID == "" {
+	// Resolved (never mutated — c.OAuth.ClientID/ClientSecret keep the
+	// operator's literal text, `${env:...}` reference included, for the
+	// "required" check below and for every other reader, including
+	// SaveConfig's persistence path (cross-review round 6, chunk 3 P2: an
+	// earlier design resolved the reference into ClientID/ClientSecret
+	// in place at Load time, so ANY later PATCH /api/v1/config or
+	// /config/apply — even one editing an unrelated field — round-tripped
+	// that already-resolved value back through SaveConfig and permanently
+	// overwrote the operator's `${env:...}` reference in mcp_config.json
+	// with the plaintext secret, defeating docs/configuration/config-file.md's
+	// documented purpose of keeping the secret out of the file). The actual
+	// runtime resolution now happens once, at the one place that needs the
+	// live secret for the token endpoint: auth.NewOAuthHandler, on its own
+	// private, never-persisted config clone.
+	if _, err := resolveOAuthSecretRef(c.OAuth.ClientID); err != nil || c.OAuth.ClientID == "" {
 		return fmt.Errorf("server_edition.oauth.client_id is required")
 	}
-	if c.OAuth.ClientSecret == "" {
+	if _, err := resolveOAuthSecretRef(c.OAuth.ClientSecret); err != nil || c.OAuth.ClientSecret == "" {
 		return fmt.Errorf("server_edition.oauth.client_secret is required")
 	}
+	if err := c.OAuth.validateOIDC(); err != nil {
+		return err
+	}
+	if err := ValidatePublicURL(c.PublicURL); err != nil {
+		return err
+	}
+	switch c.SessionCookieSecure {
+	case "", SessionCookieSecureAuto, SessionCookieSecureTrue, SessionCookieSecureFalse:
+	default:
+		return fmt.Errorf("%s (got: %q)", msgSessionCookieSecurePolicy, c.SessionCookieSecure)
+	}
+	if c.SessionCookieSecure == SessionCookieSecureFalse && c.PublicURLIsHTTPS() {
+		return fmt.Errorf("%s", msgSessionCookieSecureFalse)
+	}
 	if c.SessionTTL.Duration() < 0 {
 		return fmt.Errorf("server_edition.session_ttl must be positive")
 	}
@@ -136,7 +309,117 @@ func (c *ServerEditionConfig) Clone() *ServerEditionConfig {
 		if c.OAuth.AllowedDomains != nil {
 			oauth.AllowedDomains = append([]string(nil), c.OAuth.AllowedDomains...)
 		}
+		if c.OAuth.Scopes != nil {
+			oauth.Scopes = append([]string(nil), c.OAuth.Scopes...)
+		}
 		out.OAuth = &oauth
 	}
 	return &out
 }
+
+// applyOIDCDefaults fills the `oidc` defaults: scopes (with "openid" appended
+// when the operator's list lacks it), groups_claim and email_verified_policy.
+func (o *ServerEditionOAuthConfig) applyOIDCDefaults() {
+	if len(o.Scopes) == 0 {
+		o.Scopes = defaultOIDCScopes()
+	} else if !containsExact(o.Scopes, "openid") {
+		// Exact-case match only: OAuth/OIDC scope values are case-sensitive
+		// (RFC 6749 §3.3), so an operator-configured "OpenID"/"OPENID" is a
+		// different scope value to a compliant IdP and must not be treated
+		// as satisfying the FR-020 requirement — the literal "openid" scope
+		// is always appended, even if a differently-cased lookalike is
+		// already present (cross-review round 6, chunk 1 P2).
+		o.Scopes = append(append([]string(nil), o.Scopes...), "openid")
+	}
+	if o.GroupsClaim == "" {
+		o.GroupsClaim = defaultOIDCGroupsClaim
+	}
+	if o.EmailVerifiedPolicy == "" {
+		o.EmailVerifiedPolicy = EmailVerifiedPolicyRefuseFalse
+	}
+}
+
+// validateOIDC holds the `oidc`-specific and provider-neutral rules of the new
+// keys (FR-020). Non-mutating: unset defaulted keys are admitted (FR-039).
+//
+// display_name is provider-neutral (FR-020/FR-030: the login-button label for
+// ANY provider, falling back to the provider family name), so its length
+// check runs unconditionally. email_verified_policy is an `oidc`-only concern
+// — the struct doc above says so, and only oidcIdentity (oauth_handler.go)
+// ever reads it, legacyIdentity never does — so its check must run only for
+// `oidc`; checking it unconditionally rejected an otherwise-valid legacy
+// (google/github/microsoft) config that carried a leftover or mistyped value
+// in that field, instead of ignoring it as documented (cross-review round 1,
+// chunk 3 P2).
+func (o *ServerEditionOAuthConfig) validateOIDC() error {
+	if len(o.DisplayName) > maxOAuthDisplayNameLen {
+		return fmt.Errorf("server_edition.oauth.display_name must be at most %d characters", maxOAuthDisplayNameLen)
+	}
+	if o.Provider != "oidc" {
+		return nil
+	}
+	switch o.EmailVerifiedPolicy {
+	case "", EmailVerifiedPolicyRefuseFalse, EmailVerifiedPolicyRequireTrue, EmailVerifiedPolicyIgnore:
+	default:
+		return fmt.Errorf("server_edition.oauth.email_verified_policy must be one of: refuse_false, require_true, ignore")
+	}
+	if o.IssuerURL == "" {
+		return fmt.Errorf("server_edition.oauth.issuer_url is required when provider is oidc")
+	}
+	if !IsAllowedOIDCEndpoint(o.IssuerURL, o.AllowInsecureIssuer) {
+		return fmt.Errorf("server_edition.oauth.issuer_url must use https (http is allowed only for a loopback host with allow_insecure_issuer: true)")
+	}
+	// OpenID Connect Discovery 1.0 §2: the Issuer Identifier "MUST NOT
+	// contain query or fragment components". IsAllowedOIDCEndpoint admits
+	// them (it also gates the discovered endpoints, which the spec does not
+	// restrict this way), so an issuer_url carrying either passed validation
+	// and reached fetchDiscovery, which builds the discovery request by
+	// string-appending "/.well-known/openid-configuration" to issuer_url
+	// (oidc_provider.go) — for
+	// "https://idp.example/issuer?tenant=x" that produces
+	// ".../issuer?tenant=x/.well-known/openid-configuration", a request whose
+	// well-known suffix lands inside the query string instead of the path,
+	// so every login for that (accepted-at-boot) config failed discovery
+	// (cross-review round 6, chunk 3 P2).
+	if u, err := url.Parse(o.IssuerURL); err == nil && (u.RawQuery != "" || u.Fragment != "" || u.RawFragment != "") {
+		return fmt.Errorf("server_edition.oauth.issuer_url must not contain a query or fragment component (got: %q)", o.IssuerURL)
+	}
+	return nil
+}
+
+// IsAllowedOIDCEndpoint reports whether raw is an absolute https URL, or an
+// absolute http URL whose host is loopback while allowInsecure is set. The
+// same rule gates the configured issuer and every discovered endpoint
+// (FR-020): non-loopback http is never admitted, flag or no flag.
+func IsAllowedOIDCEndpoint(raw string, allowInsecure bool) bool {
+	u, err := url.Parse(raw)
+	if err != nil || u.Host == "" || u.Hostname() == "" {
+		return false
+	}
+	switch u.Scheme {
+	case "https":
+		return true
+	case "http":
+		return allowInsecure && isLoopbackHost(u.Hostname())
+	default:
+		return false
+	}
+}
+
+// isLoopbackHost reports whether host is "localhost" or a loopback IP literal.
+func isLoopbackHost(host string) bool {
+	if strings.EqualFold(host, "localhost") {
+		return true
+	}
+	ip := net.ParseIP(host)
+	return ip != nil && ip.IsLoopback()
+}
+
+func containsExact(list []string, want string) bool {
+	for _, s := range list {
+		if s == want {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/config/server_edition_oidc_config_test.go b/internal/config/server_edition_oidc_config_test.go
new file mode 100644
index 000000000..75a7dc4c3
--- /dev/null
+++ b/internal/config/server_edition_oidc_config_test.go
@@ -0,0 +1,327 @@
+//go:build server
+
+package config
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// Spec 107 US2 / FR-020 (T040, compile-red until T041): the generic `oidc`
+// provider lands in ServerEditionOAuthConfig with six new keys
+// (contracts/config-keys.md):
+//
+//	issuer_url             required for oidc; https, or http only for a loopback
+//	                       host with allow_insecure_issuer: true
+//	allow_insecure_issuer  loopback-only development toggle
+//	scopes                 default ["openid","profile","email"]; openid appended
+//	groups_claim           default "groups"
+//	email_verified_policy  refuse_false (default) | require_true | ignore
+//	display_name           login-button label, <= 64 chars
+//
+// Validate stays non-mutating (FR-039): every default belongs to ApplyDefaults
+// and an unset defaulted key is never refused, so PATCH /api/v1/config and
+// /config/apply admit the same document boot admits.
+
+const (
+	oidcProviderMsg    = "server_edition.oauth.provider must be one of: google, github, microsoft, oidc (got: bogus)"
+	oidcIssuerReqMsg   = "server_edition.oauth.issuer_url is required when provider is oidc"
+	oidcIssuerHTTPSMsg = "server_edition.oauth.issuer_url must use https (http is allowed only for a loopback host with allow_insecure_issuer: true)"
+	oidcEmailPolicyMsg = "server_edition.oauth.email_verified_policy must be one of: refuse_false, require_true, ignore"
+)
+
+// oidcBlock returns an enabled server_edition block with a minimal valid
+// `oidc` provider; callers mutate the OAuth sub-block per case.
+func oidcBlock() *ServerEditionConfig {
+	return &ServerEditionConfig{
+		Enabled:     true,
+		AdminEmails: []string{"admin@example.com"},
+		OAuth: &ServerEditionOAuthConfig{
+			Provider:     "oidc",
+			ClientID:     "cid",
+			ClientSecret: "csec",
+			IssuerURL:    "https://idp.example.com/realms/dev",
+		},
+	}
+}
+
+func TestServerEditionOIDC_ProviderAdmitted(t *testing.T) {
+	cfg := oidcBlock()
+	require.NoError(t, cfg.Validate(), "provider: oidc with an https issuer_url must validate")
+}
+
+func TestServerEditionOIDC_ProviderEnumMessageNamesOIDC(t *testing.T) {
+	cfg := oidcBlock()
+	cfg.OAuth.Provider = "bogus"
+	err := cfg.Validate()
+	require.Error(t, err)
+	assert.Equal(t, oidcProviderMsg, err.Error(), "the enum message must list oidc (FR-039: same string at boot and on the write doors)")
+}
+
+func TestServerEditionOIDC_IssuerURLRequired(t *testing.T) {
+	cfg := oidcBlock()
+	cfg.OAuth.IssuerURL = ""
+	err := cfg.Validate()
+	require.Error(t, err)
+	assert.Equal(t, oidcIssuerReqMsg, err.Error())
+}
+
+func TestServerEditionOIDC_IssuerURLNotRequiredForLegacyProviders(t *testing.T) {
+	for _, provider := range []string{"google", "github", "microsoft"} {
+		t.Run(provider, func(t *testing.T) {
+			cfg := oidcBlock()
+			cfg.OAuth.Provider = provider
+			cfg.OAuth.IssuerURL = ""
+			assert.NoError(t, cfg.Validate(), "issuer_url is an oidc-only requirement")
+		})
+	}
+}
+
+// The https rule and its single exception: http is admitted only when BOTH
+// hold — the host is loopback AND allow_insecure_issuer is true. Non-loopback
+// http is refused regardless of the flag (FR-020).
+func TestServerEditionOIDC_IssuerURLSchemeRule(t *testing.T) {
+	cases := []struct {
+		name          string
+		issuer        string
+		allowInsecure bool
+		wantErr       string // "" = admitted
+	}{
+		{name: "https public host", issuer: "https://idp.example.com", wantErr: ""},
+		{name: "https with path", issuer: "https://idp.example.com/realms/dev", wantErr: ""},
+		{name: "http public host, flag off", issuer: "http://idp.example.com", wantErr: oidcIssuerHTTPSMsg},
+		{name: "http public host, flag on (refused regardless)", issuer: "http://idp.example.com", allowInsecure: true, wantErr: oidcIssuerHTTPSMsg},
+		{name: "http 127.0.0.1, flag off", issuer: "http://127.0.0.1:9000", wantErr: oidcIssuerHTTPSMsg},
+		{name: "http 127.0.0.1, flag on", issuer: "http://127.0.0.1:9000", allowInsecure: true, wantErr: ""},
+		{name: "http localhost, flag on", issuer: "http://localhost:9000/oidc", allowInsecure: true, wantErr: ""},
+		{name: "http [::1], flag on", issuer: "http://[::1]:9000", allowInsecure: true, wantErr: ""},
+		{name: "http localhost, flag off", issuer: "http://localhost:9000", wantErr: oidcIssuerHTTPSMsg},
+		{name: "non-http scheme", issuer: "ftp://idp.example.com", wantErr: oidcIssuerHTTPSMsg},
+		{name: "scheme-less host", issuer: "idp.example.com", wantErr: oidcIssuerHTTPSMsg},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg := oidcBlock()
+			cfg.OAuth.IssuerURL = tc.issuer
+			cfg.OAuth.AllowInsecureIssuer = tc.allowInsecure
+			err := cfg.Validate()
+			if tc.wantErr == "" {
+				assert.NoError(t, err)
+				return
+			}
+			require.Error(t, err)
+			assert.Equal(t, tc.wantErr, err.Error())
+		})
+	}
+}
+
+// Spec 107 cross-review round 6, chunk 3 P2: OpenID Connect Discovery 1.0 §2
+// requires the Issuer Identifier to carry no query or fragment component.
+// IsAllowedOIDCEndpoint (shared with the discovered endpoints, which have no
+// such restriction) does not reject them, so an issuer_url carrying either
+// used to pass validation and only fail later, at login time, when
+// fetchDiscovery string-appended "/.well-known/openid-configuration" to it
+// and produced a malformed request URL (the suffix landing inside the query
+// string).
+func TestServerEditionOIDC_IssuerURLRejectsQueryAndFragment(t *testing.T) {
+	cases := []struct {
+		name   string
+		issuer string
+	}{
+		{name: "query", issuer: "https://idp.example.com/issuer?tenant=x"},
+		{name: "fragment", issuer: "https://idp.example.com/issuer#frag"},
+		{name: "query and fragment", issuer: "https://idp.example.com/issuer?tenant=x#frag"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg := oidcBlock()
+			cfg.OAuth.IssuerURL = tc.issuer
+			err := cfg.Validate()
+			require.Error(t, err, "a query or fragment component must be refused at Validate, not left to fail discovery at login time")
+			assert.Contains(t, err.Error(), "must not contain a query or fragment component")
+		})
+	}
+}
+
+func TestServerEditionOIDC_IssuerURLWithoutQueryOrFragmentStillAdmitted(t *testing.T) {
+	cfg := oidcBlock()
+	cfg.OAuth.IssuerURL = "https://idp.example.com/realms/dev"
+	assert.NoError(t, cfg.Validate())
+}
+
+func TestServerEditionOIDC_EmailVerifiedPolicyEnum(t *testing.T) {
+	for _, policy := range []string{"", "refuse_false", "require_true", "ignore"} {
+		t.Run("admits "+policy, func(t *testing.T) {
+			cfg := oidcBlock()
+			cfg.OAuth.EmailVerifiedPolicy = policy
+			assert.NoError(t, cfg.Validate(), "unset is defaulted by ApplyDefaults, never refused by Validate")
+		})
+	}
+	for _, policy := range []string{"bogus", "REFUSE_FALSE", "true"} {
+		t.Run("refuses "+policy, func(t *testing.T) {
+			cfg := oidcBlock()
+			cfg.OAuth.EmailVerifiedPolicy = policy
+			err := cfg.Validate()
+			require.Error(t, err)
+			assert.Equal(t, oidcEmailPolicyMsg, err.Error())
+		})
+	}
+}
+
+func TestServerEditionOIDC_GroupsClaimUnsetIsAdmitted(t *testing.T) {
+	// groups_claim is "non-empty for oidc" only after ApplyDefaults; Validate
+	// alone must not refuse the unset key (FR-039 non-mutating, write-door parity).
+	cfg := oidcBlock()
+	cfg.OAuth.GroupsClaim = ""
+	assert.NoError(t, cfg.Validate())
+
+	cfg.OAuth.GroupsClaim = "memberOf"
+	assert.NoError(t, cfg.Validate())
+}
+
+func TestServerEditionOIDC_DisplayNameLength(t *testing.T) {
+	for _, provider := range []string{"oidc", "google"} {
+		t.Run(provider, func(t *testing.T) {
+			cfg := oidcBlock()
+			cfg.OAuth.Provider = provider
+
+			cfg.OAuth.DisplayName = strings.Repeat("x", 64)
+			assert.NoError(t, cfg.Validate(), "64 chars is the inclusive maximum")
+
+			cfg.OAuth.DisplayName = strings.Repeat("x", 65)
+			err := cfg.Validate()
+			require.Error(t, err, "65 chars must be refused")
+			assert.Contains(t, err.Error(), "server_edition.oauth.display_name")
+		})
+	}
+}
+
+func TestServerEditionOIDC_ValidateIsNonMutating(t *testing.T) {
+	cfg := oidcBlock()
+	require.NoError(t, cfg.Validate())
+	assert.Nil(t, cfg.OAuth.Scopes, "Validate must not fill scopes")
+	assert.Equal(t, "", cfg.OAuth.GroupsClaim, "Validate must not fill groups_claim")
+	assert.Equal(t, "", cfg.OAuth.EmailVerifiedPolicy, "Validate must not fill email_verified_policy")
+}
+
+func TestServerEditionOIDC_ApplyDefaults_Scopes(t *testing.T) {
+	t.Run("unset gets the full default", func(t *testing.T) {
+		cfg := oidcBlock()
+		cfg.ApplyDefaults()
+		assert.Equal(t, []string{"openid", "profile", "email"}, cfg.OAuth.Scopes)
+	})
+	t.Run("openid appended when missing", func(t *testing.T) {
+		cfg := oidcBlock()
+		cfg.OAuth.Scopes = []string{"profile", "email", "groups"}
+		cfg.ApplyDefaults()
+		assert.Equal(t, []string{"profile", "email", "groups", "openid"}, cfg.OAuth.Scopes,
+			"operator scopes are kept in order and openid is appended")
+	})
+	t.Run("openid present is left alone", func(t *testing.T) {
+		cfg := oidcBlock()
+		cfg.OAuth.Scopes = []string{"openid", "email"}
+		cfg.ApplyDefaults()
+		assert.Equal(t, []string{"openid", "email"}, cfg.OAuth.Scopes)
+	})
+}
+
+func TestServerEditionOIDC_ApplyDefaults_GroupsClaimAndPolicy(t *testing.T) {
+	cfg := oidcBlock()
+	cfg.ApplyDefaults()
+	assert.Equal(t, "groups", cfg.OAuth.GroupsClaim)
+	assert.Equal(t, "refuse_false", cfg.OAuth.EmailVerifiedPolicy)
+
+	explicit := oidcBlock()
+	explicit.OAuth.GroupsClaim = "memberOf"
+	explicit.OAuth.EmailVerifiedPolicy = "ignore"
+	explicit.OAuth.DisplayName = "Acme SSO"
+	explicit.ApplyDefaults()
+	assert.Equal(t, "memberOf", explicit.OAuth.GroupsClaim, "explicit value wins")
+	assert.Equal(t, "ignore", explicit.OAuth.EmailVerifiedPolicy, "explicit value wins")
+	assert.Equal(t, "Acme SSO", explicit.OAuth.DisplayName, "explicit value wins")
+}
+
+func TestServerEditionOIDC_ApplyDefaultsThenValidate(t *testing.T) {
+	cfg := oidcBlock()
+	cfg.ApplyDefaults()
+	require.NoError(t, cfg.Validate(), "the boot order ApplyDefaults → Validate must admit the defaulted block")
+}
+
+// The six keys ride under the documented JSON names so the config file, the
+// PATCH merge and the Web UI settings rows all agree (contracts/config-keys.md).
+func TestServerEditionOIDC_JSONKeys(t *testing.T) {
+	doc := `{
+		"enabled": true,
+		"admin_emails": ["admin@example.com"],
+		"oauth": {
+			"provider": "oidc",
+			"client_id": "cid",
+			"client_secret": "csec",
+			"issuer_url": "http://127.0.0.1:9000",
+			"allow_insecure_issuer": true,
+			"scopes": ["openid", "email"],
+			"groups_claim": "memberOf",
+			"email_verified_policy": "require_true",
+			"display_name": "Acme SSO"
+		}
+	}`
+	var cfg ServerEditionConfig
+	require.NoError(t, json.Unmarshal([]byte(doc), &cfg))
+	require.NotNil(t, cfg.OAuth)
+	assert.Equal(t, "oidc", cfg.OAuth.Provider)
+	assert.Equal(t, "http://127.0.0.1:9000", cfg.OAuth.IssuerURL)
+	assert.True(t, cfg.OAuth.AllowInsecureIssuer)
+	assert.Equal(t, []string{"openid", "email"}, cfg.OAuth.Scopes)
+	assert.Equal(t, "memberOf", cfg.OAuth.GroupsClaim)
+	assert.Equal(t, "require_true", cfg.OAuth.EmailVerifiedPolicy)
+	assert.Equal(t, "Acme SSO", cfg.OAuth.DisplayName)
+	assert.NoError(t, cfg.Validate())
+
+	out, err := json.Marshal(cfg.OAuth)
+	require.NoError(t, err)
+	var keys map[string]json.RawMessage
+	require.NoError(t, json.Unmarshal(out, &keys))
+	for _, k := range []string{"issuer_url", "allow_insecure_issuer", "scopes", "groups_claim", "email_verified_policy", "display_name"} {
+		assert.Contains(t, keys, k, "marshalled oauth block must carry %q", k)
+	}
+}
+
+// Clone must deep-copy the new slice so a Clone-then-ApplyDefaults at setup
+// never leaks the derived scopes into the runtime's own (persisted) pointer.
+func TestServerEditionOIDC_CloneDeepCopiesScopes(t *testing.T) {
+	orig := oidcBlock()
+	orig.OAuth.Scopes = []string{"profile", "email"}
+
+	clone := orig.Clone()
+	clone.OAuth.Scopes[0] = "mutated"
+	clone.OAuth.Scopes = append(clone.OAuth.Scopes, "openid")
+
+	assert.Equal(t, []string{"profile", "email"}, orig.OAuth.Scopes, "original scopes must not observe the clone's mutation")
+}
+
+// Write-door parity (FR-039): the oidc rules are reached from Config.Validate
+// and ValidateDetailed with the same message boot emits.
+func TestConfigValidate_ReachesOIDCIssuerRule(t *testing.T) {
+	block := oidcBlock()
+	block.OAuth.IssuerURL = ""
+	cfg := minimalServerEditionConfig(block)
+
+	err := cfg.Validate()
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), oidcIssuerReqMsg)
+
+	errs := cfg.ValidateDetailed()
+	require.NotEmpty(t, errs)
+	found := false
+	for _, ve := range errs {
+		if strings.Contains(ve.Error(), oidcIssuerReqMsg) {
+			found = true
+			break
+		}
+	}
+	assert.True(t, found, "ValidateDetailed must report %q, got %v", oidcIssuerReqMsg, errs)
+}
diff --git a/internal/config/server_edition_secrets_expand_test.go b/internal/config/server_edition_secrets_expand_test.go
new file mode 100644
index 000000000..ddbf6f5dc
--- /dev/null
+++ b/internal/config/server_edition_secrets_expand_test.go
@@ -0,0 +1,103 @@
+//go:build server
+
+package config
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// Spec 107 cross-review round 2, chunk 3 P2: a missing ${env:...} referenced
+// by server_edition.oauth.client_secret/client_id must be refused by
+// Validate's "is required" message at boot, not silently kept as the literal
+// placeholder text (which is non-empty and so passed the required check,
+// sending "${env:MISSING}" itself to the IdP as the client secret).
+func TestExpandServerEditionSecrets_MissingEnvVarIsRefusedAtValidate(t *testing.T) {
+	os.Unsetenv("MCPPROXY_TEST_MISSING_OIDC_SECRET_XYZ")
+
+	dir := t.TempDir()
+	doc := map[string]any{
+		"listen":   "127.0.0.1:8080",
+		"data_dir": dir,
+		"server_edition": map[string]any{
+			"enabled":      true,
+			"admin_emails": []string{"admin@example.com"},
+			"oauth": map[string]any{
+				"provider":      "google",
+				"client_id":     "cid",
+				"client_secret": "${env:MCPPROXY_TEST_MISSING_OIDC_SECRET_XYZ}",
+			},
+		},
+	}
+	data, err := json.Marshal(doc)
+	require.NoError(t, err)
+	path := filepath.Join(dir, "mcp_config.json")
+	require.NoError(t, os.WriteFile(path, data, 0600))
+
+	_, err = LoadFromFile(path)
+	require.Error(t, err, "a missing env var must be refused at boot, not silently accepted as the literal placeholder")
+	assert.Contains(t, err.Error(), "server_edition.oauth.client_secret is required",
+		"the required-field message, not a downstream IdP-login failure with the placeholder text")
+}
+
+// Spec 107 cross-review round 6, chunk 3 P2: LoadFromFile must NOT resolve
+// server_edition.oauth.client_id/client_secret into the returned Config — that
+// object is r.cfg/r.desiredCfg, and GetDesiredConfig/ApplyConfig round-trip it
+// back to disk through SaveConfig on every later PATCH /api/v1/config or
+// /config/apply, even one editing an unrelated field. An earlier design
+// resolved the `${env:...}` reference in place at Load time, so that very
+// next unrelated save permanently overwrote the operator's reference in
+// mcp_config.json with the plaintext secret. The fix: the returned Config
+// keeps the operator's literal `${env:...}` text (Validate() resolves it
+// read-only, just to enforce "required"; auth.NewOAuthHandler resolves it
+// again on its own private, never-persisted clone for the actual token
+// exchange) — proved here two ways: the loaded value is still the reference,
+// and a save-after-load (SaveConfig on the returned cfg, exactly what
+// ApplyConfig does with the merged PATCH result) writes the reference back to
+// disk, never the secret.
+func TestLoadFromFile_DoesNotResolveOAuthSecretIntoTheReturnedConfig(t *testing.T) {
+	t.Setenv("MCPPROXY_TEST_OIDC_SECRET_ABC", "super-secret-plaintext-value")
+
+	dir := t.TempDir()
+	doc := map[string]any{
+		"listen":   "127.0.0.1:8080",
+		"data_dir": dir,
+		"server_edition": map[string]any{
+			"enabled":      true,
+			"admin_emails": []string{"admin@example.com"},
+			"oauth": map[string]any{
+				"provider":      "google",
+				"client_id":     "cid",
+				"client_secret": "${env:MCPPROXY_TEST_OIDC_SECRET_ABC}",
+			},
+		},
+	}
+	data, err := json.Marshal(doc)
+	require.NoError(t, err)
+	path := filepath.Join(dir, "mcp_config.json")
+	require.NoError(t, os.WriteFile(path, data, 0600))
+
+	cfg, err := LoadFromFile(path)
+	require.NoError(t, err)
+	require.NotNil(t, cfg.ServerEdition)
+	require.NotNil(t, cfg.ServerEdition.OAuth)
+	assert.Equal(t, "${env:MCPPROXY_TEST_OIDC_SECRET_ABC}", cfg.ServerEdition.OAuth.ClientSecret,
+		"the loaded Config must keep the operator's reference text, not the resolved secret — "+
+			"this is the object every later PATCH/apply merges onto and SaveConfig writes back to disk")
+
+	// Simulate the next unrelated save (SaveConfig on this exact object, as
+	// ApplyConfig does with its merged result): the file on disk must still
+	// carry the reference, never the plaintext secret.
+	require.NoError(t, SaveConfig(cfg, path))
+	saved, err := os.ReadFile(path)
+	require.NoError(t, err)
+	assert.Contains(t, string(saved), "${env:MCPPROXY_TEST_OIDC_SECRET_ABC}",
+		"a later save must persist the reference")
+	assert.NotContains(t, string(saved), "super-secret-plaintext-value",
+		"a later save must never persist the resolved secret")
+}
diff --git a/internal/config/serveredition_accessors.go b/internal/config/serveredition_accessors.go
new file mode 100644
index 000000000..8f1789bec
--- /dev/null
+++ b/internal/config/serveredition_accessors.go
@@ -0,0 +1,186 @@
+//go:build server
+
+package config
+
+import (
+	"bytes"
+	"encoding/json"
+)
+
+// Build-tagged accessors for the server-edition block (Spec 107 T052). The
+// edition-neutral packages (internal/server, internal/management) read the
+// block only through these, so the personal build — where the block is an
+// opaque carrier — never interprets it.
+
+// ServerEditionEnabled reports whether the server-edition block is present and
+// enabled.
+func ServerEditionEnabled(cfg *Config) bool {
+	return cfg != nil && cfg.ServerEdition != nil && cfg.ServerEdition.Enabled
+}
+
+// EffectiveRequireMCPAuth is the value the /mcp auth middleware enforces:
+// under an enabled server-edition block it is always true (FR-029), otherwise
+// the configured require_mcp_auth.
+func EffectiveRequireMCPAuth(cfg *Config) bool {
+	if cfg == nil {
+		return false
+	}
+	return cfg.RequireMCPAuth || ServerEditionEnabled(cfg)
+}
+
+// RequireMCPAuthOverridden reports the case the boot notice and the doctor
+// finding name: an explicit require_mcp_auth: false forced to true by an
+// enabled server-edition block.
+func RequireMCPAuthOverridden(cfg *Config) bool {
+	return cfg != nil && !cfg.RequireMCPAuth && ServerEditionEnabled(cfg)
+}
+
+// IdPProviderFamily returns the configured oauth.provider family ("google",
+// "github", "microsoft", "oidc") or "" when no block/oauth is configured.
+func IdPProviderFamily(cfg *Config) string {
+	if cfg == nil || cfg.ServerEdition == nil || cfg.ServerEdition.OAuth == nil {
+		return ""
+	}
+	return cfg.ServerEdition.OAuth.Provider
+}
+
+// PublicURL returns server_edition.public_url ("" when unset).
+func PublicURL(cfg *Config) string {
+	if cfg == nil || cfg.ServerEdition == nil {
+		return ""
+	}
+	return cfg.ServerEdition.PublicURL
+}
+
+// ServerEditionRestartProjection returns the restart-pinned subset of the
+// block for DetectConfigChanges (Spec 107 FR-039 part 2): every key setup.go
+// binds at construction — enabled, oauth.*, public_url, session_cookie_secure,
+// the TTLs and credential_encryption_key. admin_emails is deliberately absent
+// (live through ServerEditionConfigProvider) and so is the deprecated no-op
+// store_idp_tokens (contracts/config-keys.md: never reported). The value is
+// meant for jsonEqual: a nil block projects to the zero value, so an absent
+// block and `{}` compare equal, and omitempty collapses nil-vs-[] the way the
+// PATCH round-trip does.
+func ServerEditionRestartProjection(cfg *Config) any {
+	var p serverEditionRestartProjection
+	if cfg == nil || cfg.ServerEdition == nil {
+		return p
+	}
+	se := cfg.ServerEdition
+	p.Enabled = se.Enabled
+	p.OAuth = se.OAuth
+	p.SessionTTL = se.SessionTTL
+	p.BearerTokenTTL = se.BearerTokenTTL
+	p.CredentialEncryptionKey = se.CredentialEncryptionKey
+	p.PublicURL = se.PublicURL
+	p.SessionCookieSecure = se.SessionCookieSecure
+	return p
+}
+
+type serverEditionRestartProjection struct {
+	Enabled                 bool                      `json:"enabled"`
+	OAuth                   *ServerEditionOAuthConfig `json:"oauth,omitempty"`
+	SessionTTL              Duration                  `json:"session_ttl,omitempty"`
+	BearerTokenTTL          Duration                  `json:"bearer_token_ttl,omitempty"`
+	CredentialEncryptionKey string                    `json:"credential_encryption_key,omitempty"`
+	PublicURL               string                    `json:"public_url,omitempty"`
+	SessionCookieSecure     string                    `json:"session_cookie_secure,omitempty"`
+}
+
+// ServerEditionAdminEmails returns server_edition.admin_emails (nil when the
+// block is absent) — the one live key of the block, compared with
+// slices.Equal by DetectConfigChanges.
+func ServerEditionAdminEmails(cfg *Config) []string {
+	if cfg == nil || cfg.ServerEdition == nil {
+		return nil
+	}
+	return cfg.ServerEdition.AdminEmails
+}
+
+// ServerEditionRestartReason names the first restart-pinned key group that
+// differs between the two blocks, in the words of contracts/config-keys.md.
+// It carries key names only — never a value, so no secret can reach a log
+// line or an API result through it. "" when nothing restart-pinned differs.
+func ServerEditionRestartReason(oldCfg, newCfg *Config) string {
+	o, n := serverEditionOrZero(oldCfg), serverEditionOrZero(newCfg)
+	switch {
+	case o.Enabled != n.Enabled:
+		return "server_edition.enabled requires a restart"
+	case o.PublicURL != n.PublicURL:
+		return "server_edition.public_url is used at login handler construction"
+	case !oauthBlocksEqual(o.OAuth, n.OAuth):
+		return "server_edition.oauth.* is bound at login handler construction"
+	case o.SessionCookieSecure != n.SessionCookieSecure:
+		return "server_edition.session_cookie_secure is bound at session store construction"
+	case o.SessionTTL != n.SessionTTL:
+		return "server_edition.session_ttl is bound at session store construction"
+	case o.BearerTokenTTL != n.BearerTokenTTL:
+		return "server_edition.bearer_token_ttl is bound at session store construction"
+	case o.CredentialEncryptionKey != n.CredentialEncryptionKey:
+		return "server_edition.credential_encryption_key is bound at credential store construction"
+	}
+	return ""
+}
+
+// oauthBlocksEqual compares two oauth blocks by their JSON form so the PATCH
+// round-trip's nil-vs-[] on allowed_domains/scopes does not name oauth.* as
+// the reason for an unrelated TTL edit.
+func oauthBlocksEqual(a, b *ServerEditionOAuthConfig) bool {
+	if (a == nil) != (b == nil) {
+		return false
+	}
+	if a == nil {
+		return true
+	}
+	ab, errA := json.Marshal(a)
+	bb, errB := json.Marshal(b)
+	return errA == nil && errB == nil && bytes.Equal(ab, bb)
+}
+
+func serverEditionOrZero(cfg *Config) ServerEditionConfig {
+	if cfg == nil || cfg.ServerEdition == nil {
+		return ServerEditionConfig{}
+	}
+	return *cfg.ServerEdition
+}
+
+// MergeServerEditionRestartGated returns the ServerEdition block the running
+// process can actually adopt for one config apply (Spec 107 FR-039 part 2;
+// cross-review round 1, chunk 3 P1): the exact restart-pinned subset
+// ServerEditionRestartProjection/ServerEditionRestartReason name — enabled,
+// oauth.*, public_url, session_cookie_secure, session_ttl, bearer_token_ttl,
+// credential_encryption_key — pinned to `live`, so the process can never
+// silently adopt a change DetectConfigChanges reports as restart-required
+// (before this, internal/runtime's pinRestartGated did not pin ServerEdition
+// at all, so e.g. disabling server_edition.enabled took effect immediately —
+// restoring anonymous /mcp access — while the API still reported "requires
+// restart"). admin_emails (and the deprecated store_idp_tokens no-op) pass
+// through from `desired`, which is what makes admin_emails hot (#1169,
+// setup.go's ServerEditionConfigProvider).
+func MergeServerEditionRestartGated(live, desired *ServerEditionConfig) *ServerEditionConfig {
+	if live == nil && desired == nil {
+		return nil
+	}
+	out := &ServerEditionConfig{}
+	if desired != nil {
+		*out = *desired
+	}
+	if live != nil {
+		out.Enabled = live.Enabled
+		out.OAuth = live.OAuth
+		out.SessionTTL = live.SessionTTL
+		out.BearerTokenTTL = live.BearerTokenTTL
+		out.CredentialEncryptionKey = live.CredentialEncryptionKey
+		out.PublicURL = live.PublicURL
+		out.SessionCookieSecure = live.SessionCookieSecure
+	} else {
+		out.Enabled = false
+		out.OAuth = nil
+		out.SessionTTL = 0
+		out.BearerTokenTTL = 0
+		out.CredentialEncryptionKey = ""
+		out.PublicURL = ""
+		out.SessionCookieSecure = ""
+	}
+	return out
+}
diff --git a/internal/config/serveredition_accessors_stub.go b/internal/config/serveredition_accessors_stub.go
new file mode 100644
index 000000000..ae0e86ab5
--- /dev/null
+++ b/internal/config/serveredition_accessors_stub.go
@@ -0,0 +1,54 @@
+//go:build !server
+
+package config
+
+// Personal-build stubs of the server-edition accessors (Spec 107 T052): the
+// block is an opaque carrier here (FR-040), so nothing in it is interpreted.
+
+// ServerEditionEnabled is always false on the personal build.
+func ServerEditionEnabled(_ *Config) bool { return false }
+
+// EffectiveRequireMCPAuth is the configured value on the personal build.
+func EffectiveRequireMCPAuth(cfg *Config) bool {
+	return cfg != nil && cfg.RequireMCPAuth
+}
+
+// RequireMCPAuthOverridden is always false on the personal build.
+func RequireMCPAuthOverridden(_ *Config) bool { return false }
+
+// IdPProviderFamily is always "" on the personal build.
+func IdPProviderFamily(_ *Config) string { return "" }
+
+// PublicURL is always "" on the personal build.
+func PublicURL(_ *Config) string { return "" }
+
+// ServerEditionRestartProjection returns the opaque carrier itself on the
+// personal build (Spec 107 FR-040): the block is canonical JSON that is never
+// interpreted here, so DetectConfigChanges compares its bytes and reports ANY
+// difference as `server_edition`, restart-pinned. A nil block marshals to
+// `null`, so absent-vs-absent compares equal and absent-vs-present does not.
+func ServerEditionRestartProjection(cfg *Config) any {
+	if cfg == nil {
+		return (*ServerEditionConfig)(nil)
+	}
+	return cfg.ServerEdition
+}
+
+// ServerEditionAdminEmails is always nil on the personal build: the carrier
+// is not interpreted, so there is no live key to compare.
+func ServerEditionAdminEmails(_ *Config) []string { return nil }
+
+// ServerEditionRestartReason is the single reason the personal build can
+// give — it cannot tell which key inside the opaque block moved.
+func ServerEditionRestartReason(_, _ *Config) string {
+	return "server_edition changed - the block is opaque on the personal edition and is read at startup"
+}
+
+// MergeServerEditionRestartGated pins the WHOLE opaque carrier to `live` on
+// the personal build (cross-review round 1, chunk 3 P1): nothing inside it is
+// interpreted, so every key is restart-pinned by the same rule
+// ServerEditionRestartProjection uses — there is no hot admin_emails
+// exception here (that is server-build-only, #1169).
+func MergeServerEditionRestartGated(live, _ *ServerEditionConfig) *ServerEditionConfig {
+	return live
+}
diff --git a/internal/config/trusted_proxies.go b/internal/config/trusted_proxies.go
new file mode 100644
index 000000000..0c763a9db
--- /dev/null
+++ b/internal/config/trusted_proxies.go
@@ -0,0 +1,180 @@
+package config
+
+import (
+	"fmt"
+	"net"
+	"net/http"
+	"strings"
+)
+
+// Spec 107 FR-027: `trusted_proxies` is the edition-neutral, top-level,
+// hot-reloadable list of CIDRs or IP addresses whose X-Forwarded-For /
+// X-Real-IP / X-Forwarded-Proto / X-Forwarded-Host headers are believed. The
+// default (empty) trusts nobody, so a direct client can never spoof the
+// session IP, the callback scheme, the Secure cookie decision or the audit
+// IP. ForwardedHeaders is the ONE reader every consumer goes through.
+
+// ForwardedInfo is what ForwardedHeaders resolves for one request.
+type ForwardedInfo struct {
+	// Scheme is "http" or "https": X-Forwarded-Proto from a trusted peer,
+	// otherwise the listener's own TLS state.
+	Scheme string
+	// Host is X-Forwarded-Host from a trusted peer, otherwise r.Host.
+	Host string
+	// ClientIP is the right-most X-Forwarded-For hop that is not itself a
+	// trusted proxy (then X-Real-IP) from a trusted peer, otherwise the
+	// RemoteAddr host. An unparsable RemoteAddr (a socket peer) is returned
+	// raw, as before.
+	ClientIP string
+}
+
+// TrustedProxiesProvider yields the LIVE trusted_proxies list; consumers
+// evaluate it per request so a hot reload takes effect without a restart.
+type TrustedProxiesProvider func() []string
+
+// parseTrustedProxy parses one entry as a CIDR or a bare IP (a /32 or /128).
+// Whitespace around the entry is tolerated.
+func parseTrustedProxy(entry string) (*net.IPNet, bool) {
+	entry = strings.TrimSpace(entry)
+	if entry == "" {
+		return nil, false
+	}
+	if _, ipnet, err := net.ParseCIDR(entry); err == nil {
+		return ipnet, true
+	}
+	ip := net.ParseIP(entry)
+	if ip == nil {
+		return nil, false
+	}
+	bits := 32
+	if ip.To4() == nil {
+		bits = 128
+	}
+	return &net.IPNet{IP: ip, Mask: net.CIDRMask(bits, bits)}, true
+}
+
+// peerIP extracts the IP of a RemoteAddr-shaped string ("host:port", a bare
+// IP, or a bracketed IPv6). It returns nil for anything that is not an IP
+// literal — a unix-socket peer, a hostname, an empty string — which is never
+// trusted.
+func peerIP(remoteAddr string) net.IP {
+	host := remoteAddr
+	if h, _, err := net.SplitHostPort(remoteAddr); err == nil {
+		host = h
+	}
+	host = strings.TrimSuffix(strings.TrimPrefix(host, "["), "]")
+	return net.ParseIP(host)
+}
+
+// ipInTrusted reports whether ip is covered by any parsable entry. An
+// unparsable entry is skipped (it never grants trust) and does not disable
+// its neighbours; validateTrustedProxies is where it is refused.
+func ipInTrusted(ip net.IP, trusted []string) bool {
+	if ip == nil {
+		return false
+	}
+	for _, entry := range trusted {
+		if ipnet, ok := parseTrustedProxy(entry); ok && ipnet.Contains(ip) {
+			return true
+		}
+	}
+	return false
+}
+
+// IsTrustedProxy reports whether remoteAddr (RemoteAddr form) is inside the
+// trusted list. Unparsable peers and an empty list are never trusted.
+func IsTrustedProxy(remoteAddr string, trusted []string) bool {
+	return ipInTrusted(peerIP(remoteAddr), trusted)
+}
+
+// ForwardedHeaders resolves the client-facing scheme, host and client IP of
+// r, honouring the X-Forwarded-* / X-Real-IP headers only when the direct
+// peer is a trusted proxy.
+func ForwardedHeaders(r *http.Request, trusted []string) ForwardedInfo {
+	info := ForwardedInfo{Scheme: "http", Host: r.Host}
+	if r.TLS != nil {
+		info.Scheme = "https"
+	}
+	if ip := peerIP(r.RemoteAddr); ip != nil {
+		info.ClientIP = ip.String()
+	} else {
+		info.ClientIP = r.RemoteAddr
+	}
+	if !IsTrustedProxy(r.RemoteAddr, trusted) {
+		return info
+	}
+
+	switch proto := strings.ToLower(strings.TrimSpace(r.Header.Get("X-Forwarded-Proto"))); proto {
+	case "http", "https":
+		info.Scheme = proto
+	}
+	if host := strings.TrimSpace(r.Header.Get("X-Forwarded-Host")); host != "" {
+		info.Host = host
+	}
+	if xff := r.Header.Get("X-Forwarded-For"); strings.TrimSpace(xff) != "" {
+		hops := strings.Split(xff, ",")
+		// Walk right to left: the first hop that parses as an IP and is not
+		// itself a trusted proxy is the client. A hop that does not parse as
+		// an IP literal (a hostname, "unknown", or an address still carrying
+		// its port) is skipped rather than accepted — it must never win the
+		// walk and land in session/audit ClientIP as a non-IP string
+		// (cross-review round 8, chunk 3 P2). When every parsable hop is
+		// trusted the left-most parsable one is the best available client
+		// address.
+		chosen := ""
+		for i := len(hops) - 1; i >= 0; i-- {
+			hop := strings.TrimSpace(hops[i])
+			if hop == "" {
+				continue
+			}
+			ip := net.ParseIP(hop)
+			if ip == nil {
+				continue
+			}
+			chosen = hop
+			if !ipInTrusted(ip, trusted) {
+				break
+			}
+		}
+		if chosen != "" {
+			info.ClientIP = chosen
+			return info
+		}
+	}
+	if xri := strings.TrimSpace(r.Header.Get("X-Real-IP")); xri != "" && net.ParseIP(xri) != nil {
+		info.ClientIP = xri
+	}
+	return info
+}
+
+// validateTrustedProxies refuses every entry that is neither a CIDR nor an IP
+// address, with the message text of contracts/config-keys.md, so boot, PATCH
+// and /config/apply say the same thing (FR-039).
+func validateTrustedProxies(cfg *Config) []ValidationError {
+	if cfg == nil {
+		return nil
+	}
+	var errs []ValidationError
+	for i, entry := range cfg.TrustedProxies {
+		if _, ok := parseTrustedProxy(entry); !ok {
+			errs = append(errs, ValidationError{
+				Field:   fmt.Sprintf("trusted_proxies[%d]", i),
+				Message: fmt.Sprintf("trusted_proxies[%d] %q is not a valid CIDR or IP address", i, entry),
+			})
+		}
+	}
+	return errs
+}
+
+// parseTrustedProxiesEnv splits the MCPPROXY_TRUSTED_PROXIES comma list,
+// trimming entries and dropping empty items. Entries are kept verbatim so an
+// invalid one is refused by validateTrustedProxies exactly like a file value.
+func parseTrustedProxiesEnv(value string) []string {
+	var out []string
+	for _, item := range strings.Split(value, ",") {
+		if item = strings.TrimSpace(item); item != "" {
+			out = append(out, item)
+		}
+	}
+	return out
+}
diff --git a/internal/config/trusted_proxies_test.go b/internal/config/trusted_proxies_test.go
new file mode 100644
index 000000000..15258dfc9
--- /dev/null
+++ b/internal/config/trusted_proxies_test.go
@@ -0,0 +1,374 @@
+package config
+
+import (
+	"crypto/tls"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// Spec 107 FR-027 (T047, red until T050): a top-level, edition-neutral
+// `trusted_proxies` list of CIDRs or IP addresses gates EVERY use of
+// X-Forwarded-For / X-Real-IP / X-Forwarded-Proto / X-Forwarded-Host in the
+// process. Default is empty = trust nobody. The single reader is
+// config.ForwardedHeaders(r, trusted) → {Scheme, Host, ClientIP}; the
+// client IP is the right-most hop of X-Forwarded-For that is NOT itself a
+// trusted proxy.
+//
+// Contract these tests pin (implementer: internal/config/trusted_proxies.go):
+//
+//	type ForwardedInfo struct{ Scheme, Host, ClientIP string }
+//	func ForwardedHeaders(r *http.Request, trusted []string) ForwardedInfo
+//	func IsTrustedProxy(remoteAddr string, trusted []string) bool
+//	func validateTrustedProxies(cfg *Config) []ValidationError
+//	Config.TrustedProxies []string `json:"trusted_proxies,omitempty"`
+//	env MCPPROXY_TRUSTED_PROXIES (comma list) in applyTLSEnvOverrides
+//
+// Message text is fixed by contracts/config-keys.md so boot, PATCH and
+// /config/apply say the same thing (FR-039).
+
+func fwdRequest(t *testing.T, remoteAddr string, headers map[string]string) *http.Request {
+	t.Helper()
+	r := httptest.NewRequest(http.MethodGet, "http://origin.example:8080/api/v1/auth/login", nil)
+	r.RemoteAddr = remoteAddr
+	for k, v := range headers {
+		r.Header.Set(k, v)
+	}
+	return r
+}
+
+// TestIsTrustedProxyParsing covers CIDR and bare-IP entries, IPv4 and IPv6,
+// the host:port / bracketed forms RemoteAddr takes, and the two failure
+// shapes (unparsable entry, unparsable peer) that must never grant trust.
+func TestIsTrustedProxyParsing(t *testing.T) {
+	cases := []struct {
+		name       string
+		remoteAddr string
+		trusted    []string
+		want       bool
+	}{
+		{"empty list trusts nobody", "10.0.0.1:1234", nil, false},
+		{"explicitly empty list trusts nobody", "10.0.0.1:1234", []string{}, false},
+		{"IPv4 CIDR match", "10.1.2.3:1234", []string{"10.0.0.0/8"}, true},
+		{"IPv4 CIDR miss", "11.1.2.3:1234", []string{"10.0.0.0/8"}, false},
+		{"bare IPv4 entry is a /32", "192.168.1.5:9", []string{"192.168.1.5"}, true},
+		{"bare IPv4 entry does not cover neighbours", "192.168.1.6:9", []string{"192.168.1.5"}, false},
+		{"IPv6 CIDR match, bracketed peer", "[fd00::1]:443", []string{"fd00::/8"}, true},
+		{"bare IPv6 loopback entry", "[::1]:5000", []string{"::1"}, true},
+		{"IPv6 entry does not match IPv4 peer", "127.0.0.1:5000", []string{"::1"}, false},
+		{"peer without a port still parses", "10.9.9.9", []string{"10.0.0.0/8"}, true},
+		{"second entry matches", "172.16.5.5:1", []string{"10.0.0.0/8", "172.16.0.0/12"}, true},
+		{"whitespace around an entry is tolerated", "10.9.9.9:1", []string{" 10.0.0.0/8 "}, true},
+		{"unparsable entry never grants trust", "10.9.9.9:1", []string{"not-a-cidr"}, false},
+		{"unparsable entry beside a valid one does not break the valid one", "10.9.9.9:1", []string{"garbage", "10.0.0.0/8"}, true},
+		{"unparsable peer (unix socket) is never trusted", "@", []string{"0.0.0.0/0", "::/0"}, false},
+		{"empty peer is never trusted", "", []string{"0.0.0.0/0", "::/0"}, false},
+		{"hostname peer is never trusted", "proxy.internal:80", []string{"0.0.0.0/0"}, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			assert.Equal(t, tc.want, IsTrustedProxy(tc.remoteAddr, tc.trusted))
+		})
+	}
+}
+
+// TestForwardedHeadersUntrustedPeerIgnoresEverything: a direct client cannot
+// spoof the session IP, the callback scheme, the Secure decision or the
+// audit IP (FR-027 invariant). With an untrusted peer every X-Forwarded-*
+// and X-Real-IP header is ignored and RemoteAddr / TLS state / Host are used.
+func TestForwardedHeadersUntrustedPeerIgnoresEverything(t *testing.T) {
+	spoof := map[string]string{
+		"X-Forwarded-For":   "1.2.3.4",
+		"X-Real-IP":         "5.6.7.8",
+		"X-Forwarded-Proto": "https",
+		"X-Forwarded-Host":  "evil.example",
+	}
+
+	t.Run("nil list = trust nobody", func(t *testing.T) {
+		got := ForwardedHeaders(fwdRequest(t, "203.0.113.7:4321", spoof), nil)
+		assert.Equal(t, "203.0.113.7", got.ClientIP, "RemoteAddr host, port stripped")
+		assert.Equal(t, "http", got.Scheme, "plain listener, XFP ignored")
+		assert.Equal(t, "origin.example:8080", got.Host, "r.Host, XFH ignored")
+	})
+
+	t.Run("peer outside the list", func(t *testing.T) {
+		got := ForwardedHeaders(fwdRequest(t, "203.0.113.7:4321", spoof), []string{"10.0.0.0/8"})
+		assert.Equal(t, "203.0.113.7", got.ClientIP)
+		assert.Equal(t, "http", got.Scheme)
+		assert.Equal(t, "origin.example:8080", got.Host)
+	})
+
+	t.Run("in-process TLS decides the scheme when untrusted", func(t *testing.T) {
+		r := fwdRequest(t, "203.0.113.7:4321", map[string]string{"X-Forwarded-Proto": "http"})
+		r.TLS = &tls.ConnectionState{}
+		got := ForwardedHeaders(r, nil)
+		assert.Equal(t, "https", got.Scheme, "r.TLS != nil wins; the untrusted downgrade header is ignored")
+	})
+
+	t.Run("unparsable RemoteAddr falls back to the raw value", func(t *testing.T) {
+		got := ForwardedHeaders(fwdRequest(t, "@", spoof), []string{"0.0.0.0/0"})
+		assert.Equal(t, "@", got.ClientIP, "socket peers keep today's raw fallback and are never trusted")
+		assert.Equal(t, "http", got.Scheme)
+		assert.Equal(t, "origin.example:8080", got.Host)
+	})
+}
+
+// TestForwardedHeadersTrustedPeer: from a trusted peer the four headers are
+// honoured, with the right-most UNTRUSTED X-Forwarded-For hop as the client.
+func TestForwardedHeadersTrustedPeer(t *testing.T) {
+	trusted := []string{"10.0.0.0/8", "172.16.0.0/12"}
+
+	t.Run("single XFF hop", func(t *testing.T) {
+		got := ForwardedHeaders(fwdRequest(t, "10.0.0.2:5555", map[string]string{
+			"X-Forwarded-For":   "198.51.100.9",
+			"X-Forwarded-Proto": "https",
+			"X-Forwarded-Host":  "sso.example.com",
+		}), trusted)
+		assert.Equal(t, "198.51.100.9", got.ClientIP)
+		assert.Equal(t, "https", got.Scheme)
+		assert.Equal(t, "sso.example.com", got.Host)
+	})
+
+	t.Run("right-most untrusted hop wins, not the left-most", func(t *testing.T) {
+		// client → (spoofed prefix) → untrusted hop 203.0.113.50 → trusted 10.0.0.9 → trusted 10.0.0.2 (peer)
+		got := ForwardedHeaders(fwdRequest(t, "10.0.0.2:5555", map[string]string{
+			"X-Forwarded-For": "1.1.1.1, 203.0.113.50, 10.0.0.9",
+		}), trusted)
+		assert.Equal(t, "203.0.113.50", got.ClientIP,
+			"a client-supplied left-most entry (1.1.1.1) must not win; walk right-to-left and stop at the first untrusted hop")
+	})
+
+	t.Run("whitespace and mixed families in XFF", func(t *testing.T) {
+		got := ForwardedHeaders(fwdRequest(t, "[fd00::2]:5555", map[string]string{
+			"X-Forwarded-For": " 2001:db8::5 ,  172.16.1.1 ",
+		}), append(trusted, "fd00::/8"))
+		assert.Equal(t, "2001:db8::5", got.ClientIP)
+	})
+
+	t.Run("every XFF hop trusted → left-most hop", func(t *testing.T) {
+		got := ForwardedHeaders(fwdRequest(t, "10.0.0.2:5555", map[string]string{
+			"X-Forwarded-For": "10.0.0.7, 10.0.0.8",
+		}), trusted)
+		assert.Equal(t, "10.0.0.7", got.ClientIP,
+			"when the chain is entirely trusted there is no untrusted hop; the left-most entry is the best available client address")
+	})
+
+	t.Run("X-Real-IP honoured when XFF is absent", func(t *testing.T) {
+		got := ForwardedHeaders(fwdRequest(t, "10.0.0.2:5555", map[string]string{
+			"X-Real-IP": " 198.51.100.77 ",
+		}), trusted)
+		assert.Equal(t, "198.51.100.77", got.ClientIP)
+	})
+
+	// An unparsable right-most hop (a hostname, a garbage token, or an IP
+	// still carrying its port) must never win the walk: it is skipped like
+	// an untrusted-but-parsable hop would win over it, so the scan keeps
+	// looking left for a real IP instead of handing a non-IP string to the
+	// session/audit ClientIP (cross-review round 8, chunk 3 P2).
+	t.Run("unparsable right-most XFF hop is skipped, not accepted", func(t *testing.T) {
+		got := ForwardedHeaders(fwdRequest(t, "10.0.0.2:5555", map[string]string{
+			"X-Forwarded-For": "198.51.100.9, unknown",
+		}), trusted)
+		assert.Equal(t, "198.51.100.9", got.ClientIP, "the garbage hop is skipped; the next real IP to its left wins")
+	})
+
+	t.Run("XFF hop still carrying its port is skipped, not accepted", func(t *testing.T) {
+		got := ForwardedHeaders(fwdRequest(t, "10.0.0.2:5555", map[string]string{
+			"X-Forwarded-For": "198.51.100.9, 203.0.113.5:1234",
+		}), trusted)
+		assert.Equal(t, "198.51.100.9", got.ClientIP)
+	})
+
+	t.Run("XFF entirely unparsable falls back to the trusted peer", func(t *testing.T) {
+		got := ForwardedHeaders(fwdRequest(t, "10.0.0.2:5555", map[string]string{
+			"X-Forwarded-For": "unknown, garbage",
+		}), trusted)
+		assert.Equal(t, "10.0.0.2", got.ClientIP, "no XFF hop parses as an IP; fall back to the trusted peer, not a garbage string")
+	})
+
+	t.Run("unparsable X-Real-IP falls back to the trusted peer", func(t *testing.T) {
+		got := ForwardedHeaders(fwdRequest(t, "10.0.0.2:5555", map[string]string{
+			"X-Real-IP": "not-an-ip",
+		}), trusted)
+		assert.Equal(t, "10.0.0.2", got.ClientIP)
+	})
+
+	t.Run("XFF takes precedence over X-Real-IP", func(t *testing.T) {
+		got := ForwardedHeaders(fwdRequest(t, "10.0.0.2:5555", map[string]string{
+			"X-Forwarded-For": "198.51.100.1",
+			"X-Real-IP":       "198.51.100.2",
+		}), trusted)
+		assert.Equal(t, "198.51.100.1", got.ClientIP)
+	})
+
+	t.Run("no forwarding headers from a trusted peer → RemoteAddr / TLS / Host", func(t *testing.T) {
+		got := ForwardedHeaders(fwdRequest(t, "10.0.0.2:5555", nil), trusted)
+		assert.Equal(t, "10.0.0.2", got.ClientIP)
+		assert.Equal(t, "http", got.Scheme)
+		assert.Equal(t, "origin.example:8080", got.Host)
+	})
+
+	t.Run("XFP is normalised and restricted to http/https", func(t *testing.T) {
+		got := ForwardedHeaders(fwdRequest(t, "10.0.0.2:5555", map[string]string{"X-Forwarded-Proto": "HTTPS"}), trusted)
+		assert.Equal(t, "https", got.Scheme, "case-insensitive")
+
+		r := fwdRequest(t, "10.0.0.2:5555", map[string]string{"X-Forwarded-Proto": "javascript"})
+		r.TLS = &tls.ConnectionState{}
+		got = ForwardedHeaders(r, trusted)
+		assert.Equal(t, "https", got.Scheme, "an unknown scheme value is ignored; the listener's own TLS state decides")
+	})
+
+	t.Run("XFP downgrade from a trusted peer is honoured", func(t *testing.T) {
+		r := fwdRequest(t, "10.0.0.2:5555", map[string]string{"X-Forwarded-Proto": "http"})
+		r.TLS = &tls.ConnectionState{}
+		got := ForwardedHeaders(r, trusted)
+		assert.Equal(t, "http", got.Scheme, "the trusted ingress is authoritative about the client-facing scheme")
+	})
+
+	t.Run("blank XFH falls back to r.Host", func(t *testing.T) {
+		got := ForwardedHeaders(fwdRequest(t, "10.0.0.2:5555", map[string]string{"X-Forwarded-Host": "   "}), trusted)
+		assert.Equal(t, "origin.example:8080", got.Host)
+	})
+}
+
+// TestTrustedProxiesConfigField pins the wire name, the default and the
+// JSON round trip of the edition-neutral top-level key.
+func TestTrustedProxiesConfigField(t *testing.T) {
+	t.Run("default is empty (trust nobody)", func(t *testing.T) {
+		assert.Empty(t, DefaultConfig().TrustedProxies)
+		cfg := &Config{}
+		require.NoError(t, cfg.Validate())
+		assert.Empty(t, cfg.TrustedProxies, "Validate must not materialise a default")
+	})
+
+	t.Run("json tag is trusted_proxies and is omitted when empty", func(t *testing.T) {
+		raw, err := json.Marshal(&Config{TrustedProxies: []string{"10.0.0.0/8", "::1"}})
+		require.NoError(t, err)
+		assert.Contains(t, string(raw), `"trusted_proxies":["10.0.0.0/8","::1"]`)
+
+		raw, err = json.Marshal(&Config{})
+		require.NoError(t, err)
+		assert.NotContains(t, string(raw), "trusted_proxies")
+
+		var cfg Config
+		require.NoError(t, json.Unmarshal([]byte(`{"trusted_proxies":["192.168.0.0/16"]}`), &cfg))
+		assert.Equal(t, []string{"192.168.0.0/16"}, cfg.TrustedProxies)
+	})
+}
+
+// TestValidateTrustedProxiesAllDoors: FR-039 — the same rule with the same
+// message text is reached from Config.Validate() (boot) and
+// ValidateDetailed() (PATCH / apply), and from the boot loader itself.
+func TestValidateTrustedProxiesAllDoors(t *testing.T) {
+	const wantMsg = `trusted_proxies[1] "10.0.0.0/33" is not a valid CIDR or IP address`
+	bad := []string{"10.0.0.0/8", "10.0.0.0/33"}
+
+	t.Run("validateTrustedProxies reports each bad entry with the contract text", func(t *testing.T) {
+		errs := validateTrustedProxies(&Config{TrustedProxies: []string{"10.0.0.0/8", "10.0.0.0/33", "nope"}})
+		require.Len(t, errs, 2)
+		assert.True(t, strings.HasPrefix(errs[0].Field, "trusted_proxies"), "field=%q", errs[0].Field)
+		assert.Equal(t, wantMsg, errs[0].Message)
+		assert.Equal(t, `trusted_proxies[2] "nope" is not a valid CIDR or IP address`, errs[1].Message)
+	})
+
+	t.Run("valid entries produce no error", func(t *testing.T) {
+		cfg := &Config{TrustedProxies: []string{"10.0.0.0/8", "192.168.1.5", "fd00::/8", "::1", " 172.16.0.0/12 "}}
+		assert.Empty(t, validateTrustedProxies(cfg))
+		require.NoError(t, cfg.Validate())
+		for _, e := range cfg.ValidateDetailed() {
+			assert.False(t, strings.HasPrefix(e.Field, "trusted_proxies"), "unexpected %v", e)
+		}
+	})
+
+	t.Run("Config.Validate (boot door) refuses", func(t *testing.T) {
+		cfg := &Config{TrustedProxies: bad}
+		err := cfg.Validate()
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), wantMsg)
+	})
+
+	t.Run("ValidateDetailed (PATCH / apply door) refuses with the same text", func(t *testing.T) {
+		cfg := &Config{TrustedProxies: bad}
+		errs := cfg.ValidateDetailed()
+		var found bool
+		for _, e := range errs {
+			if strings.HasPrefix(e.Field, "trusted_proxies") {
+				found = true
+				assert.Equal(t, wantMsg, e.Message)
+			}
+		}
+		assert.True(t, found, "ValidateDetailed must carry the trusted_proxies error: %v", errs)
+	})
+
+	t.Run("LoadFromFile refuses a broken file value", func(t *testing.T) {
+		tmp := t.TempDir()
+		cfgPath := filepath.Join(tmp, "mcp_config.json")
+		raw, err := json.Marshal(map[string]any{
+			"listen":          "127.0.0.1:0",
+			"data_dir":        tmp,
+			"trusted_proxies": bad,
+		})
+		require.NoError(t, err)
+		require.NoError(t, os.WriteFile(cfgPath, raw, 0o600))
+		_, err = LoadFromFile(cfgPath)
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), wantMsg)
+	})
+}
+
+// TestTrustedProxiesEnvOverride: MCPPROXY_TRUSTED_PROXIES (comma list) wins
+// over the file value, an unset/empty variable leaves the file value alone,
+// entries are trimmed and empty items dropped, and an invalid env value is
+// refused by the same validation as the file (the override runs before
+// Validate in LoadFromFile).
+func TestTrustedProxiesEnvOverride(t *testing.T) {
+	tmp := t.TempDir()
+	cfgPath := filepath.Join(tmp, "mcp_config.json")
+	raw, err := json.Marshal(map[string]any{
+		"listen":          "127.0.0.1:0",
+		"data_dir":        tmp,
+		"trusted_proxies": []string{"10.0.0.0/8"},
+	})
+	require.NoError(t, err)
+	require.NoError(t, os.WriteFile(cfgPath, raw, 0o600))
+
+	t.Run("file value loads", func(t *testing.T) {
+		t.Setenv("MCPPROXY_TRUSTED_PROXIES", "")
+		cfg, err := LoadFromFile(cfgPath)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"10.0.0.0/8"}, cfg.TrustedProxies)
+	})
+
+	t.Run("env wins over file, trimmed, empties dropped", func(t *testing.T) {
+		t.Setenv("MCPPROXY_TRUSTED_PROXIES", " 172.16.0.0/12, 192.168.1.5 ,, fd00::/8 ,")
+		cfg, err := LoadFromFile(cfgPath)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"172.16.0.0/12", "192.168.1.5", "fd00::/8"}, cfg.TrustedProxies)
+	})
+
+	t.Run("applyTLSEnvOverrides is the seam", func(t *testing.T) {
+		t.Setenv("MCPPROXY_TRUSTED_PROXIES", "10.1.0.0/16")
+		cfg := &Config{TrustedProxies: []string{"10.0.0.0/8"}}
+		applyTLSEnvOverrides(cfg)
+		assert.Equal(t, []string{"10.1.0.0/16"}, cfg.TrustedProxies)
+
+		t.Setenv("MCPPROXY_TRUSTED_PROXIES", "")
+		cfg = &Config{TrustedProxies: []string{"10.0.0.0/8"}}
+		applyTLSEnvOverrides(cfg)
+		assert.Equal(t, []string{"10.0.0.0/8"}, cfg.TrustedProxies, "empty variable leaves the file value")
+	})
+
+	t.Run("invalid env value is refused at boot", func(t *testing.T) {
+		t.Setenv("MCPPROXY_TRUSTED_PROXIES", "10.0.0.0/8,bogus")
+		_, err := LoadFromFile(cfgPath)
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), `trusted_proxies[1] "bogus" is not a valid CIDR or IP address`)
+	})
+}
diff --git a/internal/httpapi/auth_provider_probe_personal_test.go b/internal/httpapi/auth_provider_probe_personal_test.go
new file mode 100644
index 000000000..363a96ea1
--- /dev/null
+++ b/internal/httpapi/auth_provider_probe_personal_test.go
@@ -0,0 +1,103 @@
+//go:build !server
+
+package httpapi
+
+// Spec 107 T049 (US2, FR-030): the personal build has no
+// `GET /api/v1/auth/provider` route — the probe is registered only by the
+// server edition's SetupAll (T053) on an enabled block — so it never answers
+// 200 and never emits `display_name`, whatever the opaque `server_edition`
+// carrier (FR-040) says.
+//
+// Pin, not a red test: it is green on the PR-B base and stays green after
+// T053, which touches only build-tagged server-edition files.
+//
+// DISCREPANCY with FR-030 / T053 ("404 falls out of chi"): the probe path sits
+// under the `/api/v1` mount (server.go:751), and chi runs a sub-mux's
+// middleware — here apiKeyAuthMiddleware (server.go:756) — BEFORE that
+// sub-mux's 404. An unauthenticated caller therefore receives 401, not 404;
+// only a caller presenting the API key sees the route's absence as 404. The
+// frontend probe (T054a, "a 404 means personal edition") has to treat both as
+// "not a server edition", or the mount has to answer 404 for unknown paths
+// before the key check. The cases below pin the behaviour of the code as it
+// stands.
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+)
+
+type providerProbePersonalController struct {
+	baseController
+	cfg *config.Config
+}
+
+func (m *providerProbePersonalController) GetCurrentConfig() any { return m.cfg }
+func (m *providerProbePersonalController) GetConfig() (*config.Config, error) {
+	return m.cfg, nil
+}
+
+func newProviderProbePersonalServer(t *testing.T) *Server {
+	t.Helper()
+	// The carrier claims an enabled server edition; the personal build must
+	// not interpret it (FR-040), so the route stays absent.
+	carrier := &config.ServerEditionConfig{}
+	require.NoError(t, json.Unmarshal([]byte(`{"enabled":true,"admin_emails":["admin@example.com"],"oauth":{"provider":"oidc","client_id":"id","client_secret":"secret","issuer_url":"https://idp.example.test","display_name":"Acme SSO"}}`), carrier))
+	ctrl := &providerProbePersonalController{cfg: &config.Config{
+		Listen:        "127.0.0.1:8080",
+		APIKey:        "test-key",
+		ServerEdition: carrier,
+	}}
+	return NewServer(ctrl, zap.NewNop().Sugar(), nil)
+}
+
+func TestAuthProviderProbe_PersonalBuildHasNoRoute(t *testing.T) {
+	srv := newProviderProbePersonalServer(t)
+
+	t.Run("unauthenticated caller never gets the probe", func(t *testing.T) {
+		rec := httptest.NewRecorder()
+		srv.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/v1/auth/provider", http.NoBody))
+		// Code as it stands: the /api/v1 sub-mux's key middleware answers
+		// before chi's 404 (see the file comment). Either way: not 200, no
+		// label, nothing that looks like a server edition.
+		assert.Equal(t, http.StatusUnauthorized, rec.Code, "body=%s", rec.Body.String())
+		assert.NotEqual(t, http.StatusOK, rec.Code)
+		assert.NotContains(t, rec.Body.String(), "display_name")
+		assert.NotContains(t, rec.Body.String(), "Acme SSO")
+	})
+
+	t.Run("API-key caller sees the route is absent", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodGet, "/api/v1/auth/provider", http.NoBody)
+		req.Header.Set("X-API-Key", "test-key")
+		rec := httptest.NewRecorder()
+		srv.ServeHTTP(rec, req)
+		assert.Equal(t, http.StatusNotFound, rec.Code, "body=%s", rec.Body.String())
+		assert.NotContains(t, rec.Body.String(), "display_name")
+	})
+
+	t.Run("the carrier is not interpreted", func(t *testing.T) {
+		// Same request, a carrier that is absent: identical answer, so the
+		// block's content cannot be what decides.
+		bare := NewServer(&providerProbePersonalController{cfg: &config.Config{Listen: "127.0.0.1:8080", APIKey: "test-key"}}, zap.NewNop().Sugar(), nil)
+		for _, key := range []string{"", "test-key"} {
+			with := httptest.NewRecorder()
+			without := httptest.NewRecorder()
+			reqA := httptest.NewRequest(http.MethodGet, "/api/v1/auth/provider", http.NoBody)
+			reqB := httptest.NewRequest(http.MethodGet, "/api/v1/auth/provider", http.NoBody)
+			if key != "" {
+				reqA.Header.Set("X-API-Key", key)
+				reqB.Header.Set("X-API-Key", key)
+			}
+			srv.ServeHTTP(with, reqA)
+			bare.ServeHTTP(without, reqB)
+			assert.Equal(t, without.Code, with.Code, "key=%q", key)
+		}
+	})
+}
diff --git a/internal/httpapi/middleware.go b/internal/httpapi/middleware.go
index 1a02cbb94..66a7c8e08 100644
--- a/internal/httpapi/middleware.go
+++ b/internal/httpapi/middleware.go
@@ -8,10 +8,33 @@ import (
 	"github.com/go-chi/chi/v5"
 	"go.uber.org/zap"
 
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/reqcontext"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/telemetry"
 )
 
+// TagRequestMeta is the edition-neutral request-metadata tag (Spec 107 T050):
+// it stores {ClientIP, Mount} on the context for the audit line PR-D writes.
+// ClientIP is config.ForwardedHeaders(r, trusted).ClientIP — the forwarded
+// address only from a trusted proxy (FR-027), read through the LIVE provider
+// per request — and Mount is fixed by the mount point the middleware is
+// installed on, never by a header. A nil provider trusts nobody.
+func TagRequestMeta(mount reqcontext.Mount, trusted config.TrustedProxiesProvider) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			var list []string
+			if trusted != nil {
+				list = trusted()
+			}
+			meta := reqcontext.RequestMeta{
+				ClientIP: config.ForwardedHeaders(r, list).ClientIP,
+				Mount:    mount,
+			}
+			next.ServeHTTP(w, r.WithContext(reqcontext.WithRequestMeta(r.Context(), meta)))
+		})
+	}
+}
+
 // XMCPProxyClientHeader is the HTTP header that clients (CLI, web UI, tray)
 // set so the server can attribute requests to a surface for Tier 2 telemetry.
 // Spec 042 User Story 1.
diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go
index 54d8c0cb5..eb870d29a 100644
--- a/internal/httpapi/server.go
+++ b/internal/httpapi/server.go
@@ -666,6 +666,20 @@ func (s *Server) requireServerOp(op string, next http.HandlerFunc) http.HandlerF
 	}
 }
 
+// trustedProxiesProvider yields the LIVE trusted_proxies list through the
+// controller's config (Spec 107 FR-027), evaluated per request.
+func (s *Server) trustedProxiesProvider() config.TrustedProxiesProvider {
+	return func() []string {
+		if s.controller == nil {
+			return nil
+		}
+		if cfg, err := s.controller.GetConfig(); err == nil && cfg != nil {
+			return cfg.TrustedProxies
+		}
+		return nil
+	}
+}
+
 // setupRoutes configures all API routes
 func (s *Server) setupRoutes() {
 	s.logger.Debug("Setting up HTTP API routes")
@@ -753,6 +767,9 @@ func (s *Server) setupRoutes() {
 		// The deadline is per-route: the long-running routes carry their own
 		// budget, everything else gets defaultAPIRequestTimeout.
 		r.Use(apiRequestTimeout(defaultAPIRequestTimeout, longRunningAPIBudgets()))
+		// Spec 107 T050: {ClientIP, Mount: api} for the audit line, with the
+		// forwarded IP believed only from a trusted proxy (live list).
+		r.Use(TagRequestMeta(reqcontext.MountAPI, s.trustedProxiesProvider()))
 		r.Use(s.apiKeyAuthMiddleware())
 		// Spec 042: Tier 2 telemetry middlewares. Both fetch the registry via
 		// a closure so the registry can be installed after route setup.
@@ -1014,8 +1031,9 @@ func (s *Server) setupRoutes() {
 	})
 
 	// SSE events (protected by API key) - support both GET and HEAD
-	s.router.With(s.apiKeyAuthMiddleware()).Method("GET", "/events", http.HandlerFunc(s.handleSSEEvents))
-	s.router.With(s.apiKeyAuthMiddleware()).Method("HEAD", "/events", http.HandlerFunc(s.handleSSEEvents))
+	tagEvents := TagRequestMeta(reqcontext.MountAPI, s.trustedProxiesProvider())
+	s.router.With(tagEvents, s.apiKeyAuthMiddleware()).Method("GET", "/events", http.HandlerFunc(s.handleSSEEvents))
+	s.router.With(tagEvents, s.apiKeyAuthMiddleware()).Method("HEAD", "/events", http.HandlerFunc(s.handleSSEEvents))
 
 	// Note: Swagger UI is mounted directly on the main mux (not via HTTP API server)
 	// See internal/server/server.go for swagger handler registration
diff --git a/internal/httpapi/swagger.go b/internal/httpapi/swagger.go
index 695e164d1..cf280dc0c 100644
--- a/internal/httpapi/swagger.go
+++ b/internal/httpapi/swagger.go
@@ -8,19 +8,23 @@ import (
 
 	"go.uber.org/zap"
 
-	swag "github.com/swaggo/swag/v2"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
 	_ "github.com/smart-mcp-proxy/mcpproxy-go/oas" // Import generated docs
+	swag "github.com/swaggo/swag/v2"
 )
 
 // SetupSwaggerHandler returns a handler for Swagger UI
-// This is exported so it can be mounted on the main mux
-func SetupSwaggerHandler(logger *zap.SugaredLogger) http.Handler {
+// This is exported so it can be mounted on the main mux. trusted yields the
+// LIVE trusted_proxies list (Spec 107 FR-027): X-Forwarded-Proto/-Host shape
+// the advertised server URL only from a trusted peer; nil trusts nobody.
+func SetupSwaggerHandler(logger *zap.SugaredLogger, trusted config.TrustedProxiesProvider) http.Handler {
 	logger.Debug("Setting up Swagger UI handler")
-	return &swaggerHandler{logger: logger}
+	return &swaggerHandler{logger: logger, trusted: trusted}
 }
 
 type swaggerHandler struct {
-	logger *zap.SugaredLogger
+	logger  *zap.SugaredLogger
+	trusted config.TrustedProxiesProvider
 }
 
 func (h *swaggerHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
@@ -102,23 +106,14 @@ func (h *swaggerHandler) overrideServers(doc string, r *http.Request) (string, e
 }
 
 func (h *swaggerHandler) buildServerURL(r *http.Request) string {
-	scheme := r.Header.Get("X-Forwarded-Proto")
-	if scheme == "" {
-		if r.TLS != nil {
-			scheme = "https"
-		} else {
-			scheme = "http"
-		}
+	var trusted []string
+	if h.trusted != nil {
+		trusted = h.trusted()
 	}
-
-	host := r.Header.Get("X-Forwarded-Host")
-	if host == "" {
-		host = r.Host
-	}
-
-	trimmedHost := strings.TrimSuffix(host, "/")
+	fwd := config.ForwardedHeaders(r, trusted)
+	trimmedHost := strings.TrimSuffix(fwd.Host, "/")
 	// Do NOT append /api/v1 here - it's already in the path definitions
-	return fmt.Sprintf("%s://%s", scheme, trimmedHost)
+	return fmt.Sprintf("%s://%s", fwd.Scheme, trimmedHost)
 }
 
 const swaggerHTML = `<!doctype html>
diff --git a/internal/httpapi/swagger_forwarded_test.go b/internal/httpapi/swagger_forwarded_test.go
new file mode 100644
index 000000000..758babd14
--- /dev/null
+++ b/internal/httpapi/swagger_forwarded_test.go
@@ -0,0 +1,100 @@
+package httpapi
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/reqcontext"
+)
+
+// Spec 107 FR-027 (T047/T050): the swagger server URL and the request-metadata
+// tag honour X-Forwarded-* only from a trusted proxy, and both read the
+// trusted list through a LIVE provider — mutating the provider's list after
+// construction changes the next request's answer without a rebuild.
+
+type liveTrusted struct {
+	mu   sync.Mutex
+	list []string
+}
+
+func (l *liveTrusted) set(list []string) { l.mu.Lock(); l.list = list; l.mu.Unlock() }
+func (l *liveTrusted) get() []string     { l.mu.Lock(); defer l.mu.Unlock(); return l.list }
+
+func swaggerServerURL(t *testing.T, h http.Handler, headers map[string]string) string {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, "http://origin.example:8080/swagger/doc.json", http.NoBody)
+	req.RemoteAddr = "127.0.0.1:5555"
+	for k, v := range headers {
+		req.Header.Set(k, v)
+	}
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+	var spec struct {
+		Servers []struct {
+			URL string `json:"url"`
+		} `json:"servers"`
+	}
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &spec))
+	require.NotEmpty(t, spec.Servers)
+	return spec.Servers[0].URL
+}
+
+func TestSwaggerServerURL_ForwardedOnlyFromTrustedProxyAndLive(t *testing.T) {
+	live := &liveTrusted{}
+	h := SetupSwaggerHandler(zap.NewNop().Sugar(), live.get)
+	forwarded := map[string]string{"X-Forwarded-Proto": "https", "X-Forwarded-Host": "api.example.com"}
+
+	assert.Equal(t, "http://origin.example:8080", swaggerServerURL(t, h, forwarded), "untrusted peer: headers ignored")
+
+	live.set([]string{"127.0.0.1/32"})
+	assert.Equal(t, "https://api.example.com", swaggerServerURL(t, h, forwarded), "trusted peer: headers honoured, read live")
+
+	live.set(nil)
+	assert.Equal(t, "http://origin.example:8080", swaggerServerURL(t, h, forwarded), "back to untrusted without a rebuild")
+
+	nilProvider := SetupSwaggerHandler(zap.NewNop().Sugar(), nil)
+	assert.Equal(t, "http://origin.example:8080", swaggerServerURL(t, nilProvider, forwarded), "nil provider trusts nobody")
+}
+
+func TestTagRequestMeta_MountFixedAndClientIPFromTrustedPeerOnly(t *testing.T) {
+	live := &liveTrusted{}
+	var seen reqcontext.RequestMeta
+	var ok bool
+	capture := http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) {
+		seen, ok = reqcontext.GetRequestMeta(r.Context())
+	})
+
+	do := func(h http.Handler, xff string) {
+		req := httptest.NewRequest(http.MethodPost, "/x", http.NoBody)
+		req.RemoteAddr = "127.0.0.1:4444"
+		req.Header.Set("X-Forwarded-For", xff)
+		req.Header.Set("X-Mount", "api") // a header must never pick the mount
+		h.ServeHTTP(httptest.NewRecorder(), req)
+	}
+
+	mcp := TagRequestMeta(reqcontext.MountMCP, live.get)(capture)
+	do(mcp, "1.2.3.4")
+	require.True(t, ok)
+	assert.Equal(t, reqcontext.MountMCP, seen.Mount)
+	assert.Equal(t, "127.0.0.1", seen.ClientIP, "untrusted peer: RemoteAddr")
+
+	live.set([]string{"127.0.0.1/32"})
+	do(mcp, "1.2.3.4")
+	assert.Equal(t, "1.2.3.4", seen.ClientIP, "trusted peer, read live")
+
+	api := TagRequestMeta(reqcontext.MountAPI, live.get)(capture)
+	do(api, "5.6.7.8, 127.0.0.1")
+	assert.Equal(t, reqcontext.MountAPI, seen.Mount)
+	assert.Equal(t, "5.6.7.8", seen.ClientIP, "right-most untrusted hop")
+
+	var _ config.TrustedProxiesProvider = live.get
+}
diff --git a/internal/management/diagnostics.go b/internal/management/diagnostics.go
index 61f09e1ca..9827d57d8 100644
--- a/internal/management/diagnostics.go
+++ b/internal/management/diagnostics.go
@@ -213,6 +213,11 @@ func (s *service) Doctor(ctx context.Context) (*contracts.Diagnostics, error) {
 		diag.RuntimeWarnings = append(diag.RuntimeWarnings, warning)
 	}
 
+	// Registered runtime-warning sources (Spec 107 T052): configuration
+	// findings such as an overridden require_mcp_auth or an unset public_url
+	// on a non-loopback listener, read from the live config at call time.
+	diag.RuntimeWarnings = append(diag.RuntimeWarnings, s.runtimeWarningsFromSources()...)
+
 	// Calculate total issues
 	diag.TotalIssues = len(diag.UpstreamErrors) + len(diag.OAuthRequired) +
 		len(diag.OAuthIssues) + len(diag.MissingSecrets) + len(diag.RuntimeWarnings)
diff --git a/internal/management/diagnostics_serveredition_test.go b/internal/management/diagnostics_serveredition_test.go
new file mode 100644
index 000000000..360fca2ae
--- /dev/null
+++ b/internal/management/diagnostics_serveredition_test.go
@@ -0,0 +1,65 @@
+//go:build server
+
+package management
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+)
+
+// Spec 107 T052: the doctor seam. config.DoctorFindings over the LIVE config
+// is a runtime-warning source; Doctor appends its findings to RuntimeWarnings
+// and counts them in TotalIssues, re-reading the config on every call.
+func TestDoctor_ServerEditionFindingsThroughRuntimeWarningSource(t *testing.T) {
+	block := func(publicURL, secure string) *config.ServerEditionConfig {
+		return &config.ServerEditionConfig{
+			Enabled:             true,
+			AdminEmails:         []string{"admin@example.com"},
+			OAuth:               &config.ServerEditionOAuthConfig{Provider: "google", ClientID: "id", ClientSecret: "secret"},
+			PublicURL:           publicURL,
+			SessionCookieSecure: secure,
+		}
+	}
+	live := &config.Config{Listen: "0.0.0.0:8080", RequireMCPAuth: false, ServerEdition: block("", "false")}
+
+	svc := NewService(newMockRuntime(), live, "", &mockEventEmitter{}, nil, zap.NewNop().Sugar())
+	svc.AddRuntimeWarningSource(func() []string { return config.DoctorFindings(live) })
+
+	diag, err := svc.Doctor(context.Background())
+	require.NoError(t, err)
+	require.Len(t, diag.RuntimeWarnings, 3, "%v", diag.RuntimeWarnings)
+	assert.Contains(t, diag.RuntimeWarnings[0], config.MsgRequireMCPAuthOverridden)
+	assert.Contains(t, diag.RuntimeWarnings[1], "server_edition.public_url is unset")
+	assert.Contains(t, diag.RuntimeWarnings[1], "0.0.0.0:8080")
+	assert.Contains(t, diag.RuntimeWarnings[2], "session_cookie_secure")
+	assert.Equal(t, 3, diag.TotalIssues, "runtime warnings count as issues")
+
+	// Live: the next call reads the current config.
+	live.RequireMCPAuth = true
+	live.ServerEdition = block("https://mcp.example.com", "auto")
+	diag, err = svc.Doctor(context.Background())
+	require.NoError(t, err)
+	assert.Empty(t, diag.RuntimeWarnings)
+	assert.Equal(t, 0, diag.TotalIssues)
+
+	// Loopback listener without public_url is not a finding.
+	live.RequireMCPAuth = false
+	live.Listen = "127.0.0.1:8080"
+	live.ServerEdition = block("", "")
+	diag, err = svc.Doctor(context.Background())
+	require.NoError(t, err)
+	require.Len(t, diag.RuntimeWarnings, 1)
+	assert.Contains(t, diag.RuntimeWarnings[0], config.MsgRequireMCPAuthOverridden)
+}
+
+func TestDoctorFindings_PersonalShapeAndDisabledBlock(t *testing.T) {
+	assert.Empty(t, config.DoctorFindings(nil))
+	assert.Empty(t, config.DoctorFindings(&config.Config{Listen: "0.0.0.0:8080"}), "no block, no finding")
+	assert.Empty(t, config.DoctorFindings(&config.Config{Listen: "0.0.0.0:8080", ServerEdition: &config.ServerEditionConfig{Enabled: false, SessionCookieSecure: "false"}}), "disabled block, no finding")
+}
diff --git a/internal/management/service.go b/internal/management/service.go
index 78f4f2770..e4924eeae 100644
--- a/internal/management/service.go
+++ b/internal/management/service.go
@@ -127,6 +127,14 @@ type Service interface {
 	// setter rather than a constructor parameter. Optional — callers without
 	// a scanner can skip the call and ListServers will return SecurityScan=nil.
 	SetScanSummaryEnricher(e SecurityScanEnricher)
+
+	// AddRuntimeWarningSource registers a producer of free-text findings that
+	// Doctor appends to Diagnostics.RuntimeWarnings (and counts in
+	// TotalIssues) on every call — the `mcpproxy doctor` seam for
+	// configuration findings that are not errors (Spec 107 T052:
+	// config.DoctorFindings over the live config; PR-D adds the audit sink's
+	// failure counter). Sources are consulted in registration order.
+	AddRuntimeWarningSource(source func() []string)
 }
 
 // EventEmitter defines the interface for emitting runtime events.
@@ -182,6 +190,33 @@ type service struct {
 	// guarded by scanEnricherMu so wiring is concurrency-safe.
 	scanEnricher   SecurityScanEnricher
 	scanEnricherMu sync.RWMutex
+
+	// warningSources feed Doctor's RuntimeWarnings; guarded like scanEnricher.
+	warningSources   []func() []string
+	warningSourcesMu sync.RWMutex
+}
+
+// AddRuntimeWarningSource registers one Doctor runtime-warning producer. A nil
+// source is ignored.
+func (s *service) AddRuntimeWarningSource(source func() []string) {
+	if source == nil {
+		return
+	}
+	s.warningSourcesMu.Lock()
+	s.warningSources = append(s.warningSources, source)
+	s.warningSourcesMu.Unlock()
+}
+
+// runtimeWarningsFromSources evaluates every registered source.
+func (s *service) runtimeWarningsFromSources() []string {
+	s.warningSourcesMu.RLock()
+	sources := append([]func() []string(nil), s.warningSources...)
+	s.warningSourcesMu.RUnlock()
+	var out []string
+	for _, src := range sources {
+		out = append(out, src()...)
+	}
+	return out
 }
 
 // SetScanSummaryEnricher installs the SecurityScanEnricher used by
diff --git a/internal/reqcontext/requestmeta.go b/internal/reqcontext/requestmeta.go
new file mode 100644
index 000000000..142e418e8
--- /dev/null
+++ b/internal/reqcontext/requestmeta.go
@@ -0,0 +1,40 @@
+package reqcontext
+
+import "context"
+
+// RequestMetaKey is the context key for RequestMeta.
+const RequestMetaKey ContextKey = "request_meta"
+
+// Mount names the HTTP mount a request entered through. It is fixed by the
+// mount point (Spec 107 T050), never by a header.
+type Mount string
+
+const (
+	// MountMCP is the /mcp* family (the MCP proxy surface).
+	MountMCP Mount = "mcp"
+	// MountAPI is the /api/v1 group and /events (the REST API).
+	MountAPI Mount = "api"
+)
+
+// RequestMeta is the per-request metadata the audit line needs (Spec 107
+// PR-D): the client IP as resolved through the trusted-proxy rule and the
+// mount the request arrived on. RemoteAddr lives only on *http.Request, so the
+// edition-neutral httpapi middleware stores it here.
+type RequestMeta struct {
+	ClientIP string
+	Mount    Mount
+}
+
+// WithRequestMeta stores meta on the context.
+func WithRequestMeta(ctx context.Context, meta RequestMeta) context.Context {
+	return context.WithValue(ctx, RequestMetaKey, meta)
+}
+
+// GetRequestMeta returns the stored meta and whether one was set.
+func GetRequestMeta(ctx context.Context) (RequestMeta, bool) {
+	if ctx == nil {
+		return RequestMeta{}, false
+	}
+	meta, ok := ctx.Value(RequestMetaKey).(RequestMeta)
+	return meta, ok
+}
diff --git a/internal/reqcontext/requestmeta_test.go b/internal/reqcontext/requestmeta_test.go
new file mode 100644
index 000000000..eb79f2c95
--- /dev/null
+++ b/internal/reqcontext/requestmeta_test.go
@@ -0,0 +1,18 @@
+package reqcontext
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestRequestMetaRoundTrip(t *testing.T) {
+	_, ok := GetRequestMeta(context.Background())
+	assert.False(t, ok, "no meta on a bare context")
+
+	ctx := WithRequestMeta(context.Background(), RequestMeta{ClientIP: "198.51.100.9", Mount: MountMCP})
+	got, ok := GetRequestMeta(ctx)
+	assert.True(t, ok)
+	assert.Equal(t, RequestMeta{ClientIP: "198.51.100.9", Mount: MountMCP}, got)
+}
diff --git a/internal/runtime/config_hotreload.go b/internal/runtime/config_hotreload.go
index ba5aa2ac6..d72ae09dd 100644
--- a/internal/runtime/config_hotreload.go
+++ b/internal/runtime/config_hotreload.go
@@ -384,6 +384,13 @@ func DetectConfigChanges(oldCfg, newCfg *config.Config) *ConfigApplyResult {
 	if !slices.Equal(oldCfg.TrustedHosts, newCfg.TrustedHosts) {
 		result.ChangedFields = append(result.ChangedFields, "trusted_hosts")
 	}
+	// trusted_proxies (Spec 107 FR-027 — live). Every reader evaluates the
+	// config provider per request (config.ForwardedHeaders), so reporting the
+	// change is all the propagation needed; slices.Equal for the same
+	// omitempty reason as trusted_hosts.
+	if !slices.Equal(oldCfg.TrustedProxies, newCfg.TrustedProxies) {
+		result.ChangedFields = append(result.ChangedFields, "trusted_proxies")
+	}
 
 	// Environment configuration (can be hot-reloaded)
 	if !reflect.DeepEqual(oldCfg.Environment, newCfg.Environment) {
@@ -416,6 +423,44 @@ func DetectConfigChanges(oldCfg, newCfg *config.Config) *ConfigApplyResult {
 		result.ChangedFields = append(result.ChangedFields, "update_check")
 	}
 
+	// server_edition (Spec 107 FR-039 part 2). Two clauses, because the block
+	// has two lifetimes:
+	//
+	//   - the restart-pinned subset (enabled, oauth.*, public_url,
+	//     session_cookie_secure, session_ttl, bearer_token_ttl,
+	//     credential_encryption_key) is bound once by serveredition/setup.go —
+	//     the login handler, the session store and the credential store are
+	//     built from it — so it is reported as ONE field, `server_edition`,
+	//     with RequiresRestart and a reason naming the key group (never a
+	//     value: the block holds a client secret and an encryption key);
+	//   - admin_emails is read live through ServerEditionConfigProvider by the
+	//     middleware and the login callback, so it is reported on its own as
+	//     `server_edition.admin_emails` and applies hot.
+	//
+	// The projection is build-tagged (internal/config/serveredition_accessors
+	// {,_stub}.go): the server build projects the typed struct; the personal
+	// build returns the opaque canonical-JSON carrier (FR-040), so ANY
+	// difference there is `server_edition`, restart-pinned — it cannot know
+	// which key moved, and must not pretend to. jsonEqual, not DeepEqual, for
+	// the same PATCH round-trip reason as docker_isolation: omitempty collapses
+	// nil-vs-[] on allowed_domains/scopes, and a nil block projects to the same
+	// bytes as `{}`. Like code_execution_pool_size above — and unlike the
+	// early-return keys at the top — this clause accumulates, so a write that
+	// pairs a restart-pinned key with a hot one reports both, and ApplyConfig
+	// can adopt the hot half.
+	if !jsonEqual(config.ServerEditionRestartProjection(oldCfg), config.ServerEditionRestartProjection(newCfg)) {
+		result.ChangedFields = append(result.ChangedFields, "server_edition")
+		result.RequiresRestart = true
+		result.AppliedImmediately = false
+		if result.RestartReason == "" {
+			result.RestartReason = config.ServerEditionRestartReason(oldCfg, newCfg)
+		}
+	}
+	// slices.Equal for the same omitempty reason as trusted_hosts.
+	if !slices.Equal(config.ServerEditionAdminEmails(oldCfg), config.ServerEditionAdminEmails(newCfg)) {
+		result.ChangedFields = append(result.ChangedFields, "server_edition.admin_emails")
+	}
+
 	// If no changes detected
 	if len(result.ChangedFields) == 0 {
 		result.AppliedImmediately = false
diff --git a/internal/runtime/config_hotreload_serveredition_personal_test.go b/internal/runtime/config_hotreload_serveredition_personal_test.go
new file mode 100644
index 000000000..7ad8b9824
--- /dev/null
+++ b/internal/runtime/config_hotreload_serveredition_personal_test.go
@@ -0,0 +1,87 @@
+//go:build !server
+
+package runtime
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+)
+
+// Spec 107 FR-039 part 2 / FR-040 (T055, personal twin): the personal build
+// carries `server_edition` as an opaque canonical-JSON block, so the detector
+// cannot tell `admin_emails` (live under the server build) from the keys that
+// pin a restart there. It compares the raw bytes and reports ANY difference as
+// `server_edition`, restart-pinned — never a partial, never "no changes".
+func TestDetectConfigChanges_PersonalServerEditionCarrierIsRestartPinned(t *testing.T) {
+	const doc = `{
+  "listen": "127.0.0.1:18109",
+  "data_dir": "/d",
+  "server_edition": {
+    "enabled": true,
+    "admin_emails": ["admin@example.com"],
+    "oauth": {"provider": "oidc", "client_id": "client-one", "client_secret": "secret-one", "issuer_url": "https://idp.example.com"},
+    "public_url": "https://mcp.example.com"
+  }
+}`
+	load := func(t *testing.T, raw string) *config.Config {
+		t.Helper()
+		var cfg config.Config
+		require.NoError(t, json.Unmarshal([]byte(raw), &cfg))
+		require.NotNil(t, cfg.ServerEdition)
+		return &cfg
+	}
+
+	t.Run("any byte change is server_edition, restart-pinned", func(t *testing.T) {
+		oldCfg := load(t, doc)
+		// admin_emails is live under the server build; the personal build has
+		// no way to know that and must not pretend to.
+		newCfg := load(t, `{"listen":"127.0.0.1:18109","data_dir":"/d","server_edition":{"enabled":true,"admin_emails":["admin@example.com","second@example.com"],"oauth":{"provider":"oidc","client_id":"client-one","client_secret":"secret-one","issuer_url":"https://idp.example.com"},"public_url":"https://mcp.example.com"}}`)
+
+		result := DetectConfigChanges(oldCfg, newCfg)
+		require.True(t, result.Success)
+		assert.Equal(t, []string{"server_edition"}, result.ChangedFields)
+		assert.NotContains(t, result.ChangedFields, "server_edition.admin_emails")
+		assert.True(t, result.RequiresRestart, "the personal build cannot interpret the block, so every edit is restart-pinned")
+		assert.False(t, result.AppliedImmediately)
+		assert.Contains(t, result.RestartReason, "server_edition")
+		assert.NotContains(t, result.RestartReason, "secret-one")
+	})
+
+	t.Run("key-order-only rewrite (PATCH round-trip) is not a change", func(t *testing.T) {
+		oldCfg := load(t, doc)
+		baseBytes, err := json.Marshal(oldCfg)
+		require.NoError(t, err)
+		var baseMap map[string]interface{}
+		require.NoError(t, json.Unmarshal(baseBytes, &baseMap))
+		baseMap["tools_limit"] = 16
+		mergedBytes, err := json.Marshal(baseMap)
+		require.NoError(t, err)
+		var newCfg config.Config
+		require.NoError(t, json.Unmarshal(mergedBytes, &newCfg))
+
+		result := DetectConfigChanges(oldCfg, &newCfg)
+		assert.Contains(t, result.ChangedFields, "tools_limit")
+		assert.NotContains(t, result.ChangedFields, "server_edition")
+		assert.False(t, result.RequiresRestart)
+	})
+
+	t.Run("block added or removed is server_edition, restart-pinned", func(t *testing.T) {
+		withBlock := load(t, doc)
+		var without config.Config
+		require.NoError(t, json.Unmarshal([]byte(`{"listen":"127.0.0.1:18109","data_dir":"/d"}`), &without))
+		require.Nil(t, without.ServerEdition)
+
+		added := DetectConfigChanges(&without, withBlock)
+		assert.Equal(t, []string{"server_edition"}, added.ChangedFields)
+		assert.True(t, added.RequiresRestart)
+
+		removed := DetectConfigChanges(withBlock, &without)
+		assert.Equal(t, []string{"server_edition"}, removed.ChangedFields)
+		assert.True(t, removed.RequiresRestart)
+	})
+}
diff --git a/internal/runtime/config_hotreload_serveredition_test.go b/internal/runtime/config_hotreload_serveredition_test.go
new file mode 100644
index 000000000..b5fa4a82f
--- /dev/null
+++ b/internal/runtime/config_hotreload_serveredition_test.go
@@ -0,0 +1,208 @@
+//go:build server
+
+package runtime
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+)
+
+// Spec 107 FR-039 part 2 (T055/T056): DetectConfigChanges reports the
+// `server_edition` block. Every key that setup.go binds at construction (the
+// login handler, the session store, the credential store) is restart-pinned
+// and reported as the single field `server_edition` with a reason;
+// `admin_emails` is read live through ServerEditionConfigProvider and is
+// reported as `server_edition.admin_emails` without a restart.
+//
+// Single-key edits only: the detector keeps its early-return shape for
+// listen/routing_mode/data_dir/api_key/tls/timeouts, so a mixed edit that
+// touches one of those reports THAT key alone (see the last subtest) — the
+// restart re-reads everything, which is why the existing keys do the same.
+
+func serverEditionBase() *config.Config {
+	return &config.Config{
+		Listen: "127.0.0.1:8080", DataDir: "/d", TLS: &config.TLSConfig{},
+		ServerEdition: &config.ServerEditionConfig{
+			Enabled:     true,
+			AdminEmails: []string{"admin@example.com"},
+			OAuth: &config.ServerEditionOAuthConfig{
+				Provider:            "oidc",
+				ClientID:            "client-one",
+				ClientSecret:        "secret-one",
+				AllowedDomains:      []string{"example.com"},
+				IssuerURL:           "https://idp.example.com",
+				Scopes:              []string{"openid", "profile", "email"},
+				GroupsClaim:         "groups",
+				EmailVerifiedPolicy: config.EmailVerifiedPolicyRefuseFalse,
+				DisplayName:         "Example SSO",
+			},
+			SessionTTL:              config.Duration(24 * time.Hour),
+			BearerTokenTTL:          config.Duration(24 * time.Hour),
+			CredentialEncryptionKey: "0123456789abcdef0123456789abcdef",
+			PublicURL:               "https://mcp.example.com",
+			SessionCookieSecure:     config.SessionCookieSecureAuto,
+		},
+	}
+}
+
+func TestDetectConfigChanges_ServerEditionRestartPinnedKeys(t *testing.T) {
+	// One case per restart-pinned key of contracts/config-keys.md. `reason`
+	// is the substring the RestartReason must carry so the operator can tell
+	// WHICH part of the block pinned the restart.
+	cases := []struct {
+		name   string
+		mutate func(se *config.ServerEditionConfig)
+		reason string
+	}{
+		{"enabled", func(se *config.ServerEditionConfig) { se.Enabled = false }, "server_edition.enabled requires a restart"},
+		{"oauth.provider", func(se *config.ServerEditionConfig) { se.OAuth.Provider = "google" }, "server_edition.oauth.* is bound at login handler construction"},
+		{"oauth.client_id", func(se *config.ServerEditionConfig) { se.OAuth.ClientID = "client-two" }, "server_edition.oauth.*"},
+		{"oauth.client_secret", func(se *config.ServerEditionConfig) { se.OAuth.ClientSecret = "secret-two" }, "server_edition.oauth.*"},
+		{"oauth.tenant_id", func(se *config.ServerEditionConfig) { se.OAuth.TenantID = "tenant" }, "server_edition.oauth.*"},
+		{"oauth.allowed_domains", func(se *config.ServerEditionConfig) { se.OAuth.AllowedDomains = []string{"other.example"} }, "server_edition.oauth.*"},
+		{"oauth.issuer_url", func(se *config.ServerEditionConfig) { se.OAuth.IssuerURL = "https://idp2.example.com" }, "server_edition.oauth.*"},
+		{"oauth.allow_insecure_issuer", func(se *config.ServerEditionConfig) { se.OAuth.AllowInsecureIssuer = true }, "server_edition.oauth.*"},
+		{"oauth.scopes", func(se *config.ServerEditionConfig) { se.OAuth.Scopes = []string{"openid", "email"} }, "server_edition.oauth.*"},
+		{"oauth.groups_claim", func(se *config.ServerEditionConfig) { se.OAuth.GroupsClaim = "roles" }, "server_edition.oauth.*"},
+		{"oauth.email_verified_policy", func(se *config.ServerEditionConfig) { se.OAuth.EmailVerifiedPolicy = config.EmailVerifiedPolicyIgnore }, "server_edition.oauth.*"},
+		{"oauth.display_name", func(se *config.ServerEditionConfig) { se.OAuth.DisplayName = "Other SSO" }, "server_edition.oauth.*"},
+		{"oauth removed", func(se *config.ServerEditionConfig) { se.OAuth = nil }, "server_edition.oauth.*"},
+		{"public_url", func(se *config.ServerEditionConfig) { se.PublicURL = "https://mcp2.example.com" }, "server_edition.public_url is used at login handler construction"},
+		{"session_cookie_secure", func(se *config.ServerEditionConfig) { se.SessionCookieSecure = config.SessionCookieSecureTrue }, "server_edition.session_cookie_secure"},
+		{"session_ttl", func(se *config.ServerEditionConfig) { se.SessionTTL = config.Duration(time.Hour) }, "server_edition.session_ttl"},
+		{"bearer_token_ttl", func(se *config.ServerEditionConfig) { se.BearerTokenTTL = config.Duration(time.Hour) }, "server_edition.bearer_token_ttl"},
+		// Bound at setup (setup.go NewBBoltAESStore(ResolveMasterKey(...))).
+		{"credential_encryption_key", func(se *config.ServerEditionConfig) { se.CredentialEncryptionKey = "fedcba9876543210fedcba9876543210" }, "server_edition.credential_encryption_key"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			oldCfg, newCfg := serverEditionBase(), serverEditionBase()
+			tc.mutate(newCfg.ServerEdition)
+
+			result := DetectConfigChanges(oldCfg, newCfg)
+			require.True(t, result.Success)
+			assert.Equal(t, []string{"server_edition"}, result.ChangedFields)
+			assert.True(t, result.RequiresRestart, "%s is bound at setup and must be restart-pinned", tc.name)
+			assert.False(t, result.AppliedImmediately)
+			assert.Contains(t, result.RestartReason, tc.reason)
+			// Never the secret itself, whichever key moved.
+			assert.NotContains(t, result.RestartReason, "secret-two")
+			assert.NotContains(t, result.RestartReason, "fedcba9876543210")
+		})
+	}
+
+	// Adding or removing the whole block moves admin_emails too, so both
+	// fields are reported: the restart-pinned group and the live key.
+	t.Run("block added", func(t *testing.T) {
+		oldCfg := serverEditionBase()
+		oldCfg.ServerEdition = nil
+		result := DetectConfigChanges(oldCfg, serverEditionBase())
+		assert.ElementsMatch(t, []string{"server_edition", "server_edition.admin_emails"}, result.ChangedFields)
+		assert.True(t, result.RequiresRestart)
+		assert.Contains(t, result.RestartReason, "server_edition.enabled requires a restart")
+	})
+
+	t.Run("block removed", func(t *testing.T) {
+		newCfg := serverEditionBase()
+		newCfg.ServerEdition = nil
+		result := DetectConfigChanges(serverEditionBase(), newCfg)
+		assert.ElementsMatch(t, []string{"server_edition", "server_edition.admin_emails"}, result.ChangedFields)
+		assert.True(t, result.RequiresRestart)
+	})
+}
+
+func TestDetectConfigChanges_ServerEditionAdminEmailsLive(t *testing.T) {
+	t.Run("admin_emails edit is live", func(t *testing.T) {
+		newCfg := serverEditionBase()
+		newCfg.ServerEdition.AdminEmails = []string{"admin@example.com", "second@example.com"}
+
+		result := DetectConfigChanges(serverEditionBase(), newCfg)
+		require.True(t, result.Success)
+		assert.Equal(t, []string{"server_edition.admin_emails"}, result.ChangedFields)
+		assert.False(t, result.RequiresRestart, "admin_emails is read live through ServerEditionConfigProvider")
+		assert.True(t, result.AppliedImmediately)
+		assert.Empty(t, result.RestartReason)
+	})
+
+	t.Run("nil vs empty admin_emails not reported", func(t *testing.T) {
+		oldCfg, newCfg := serverEditionBase(), serverEditionBase()
+		oldCfg.ServerEdition.AdminEmails = nil
+		newCfg.ServerEdition.AdminEmails = []string{}
+		result := DetectConfigChanges(oldCfg, newCfg)
+		assert.NotContains(t, result.ChangedFields, "server_edition.admin_emails")
+		assert.NotContains(t, result.ChangedFields, "server_edition")
+	})
+}
+
+func TestDetectConfigChanges_ServerEditionNoFalsePositives(t *testing.T) {
+	t.Run("unchanged block not reported", func(t *testing.T) {
+		result := DetectConfigChanges(serverEditionBase(), serverEditionBase())
+		assert.NotContains(t, result.ChangedFields, "server_edition")
+		assert.NotContains(t, result.ChangedFields, "server_edition.admin_emails")
+		assert.False(t, result.RequiresRestart)
+	})
+
+	t.Run("PATCH round-trip not reported", func(t *testing.T) {
+		// PATCH /api/v1/config marshals the live config and decodes the merged
+		// document; omitempty collapses empty slices, which is why the clause
+		// compares JSON rather than reflect.DeepEqual.
+		oldCfg := serverEditionBase()
+		oldCfg.ServerEdition.OAuth.AllowedDomains = []string{}
+		oldCfg.ServerEdition.OAuth.Scopes = []string{}
+		raw, err := json.Marshal(oldCfg)
+		require.NoError(t, err)
+		var newCfg config.Config
+		require.NoError(t, json.Unmarshal(raw, &newCfg))
+
+		result := DetectConfigChanges(oldCfg, &newCfg)
+		assert.NotContains(t, result.ChangedFields, "server_edition")
+		assert.NotContains(t, result.ChangedFields, "server_edition.admin_emails")
+		assert.False(t, result.RequiresRestart)
+	})
+
+	t.Run("absent block equals empty block", func(t *testing.T) {
+		oldCfg, newCfg := serverEditionBase(), serverEditionBase()
+		oldCfg.ServerEdition = nil
+		newCfg.ServerEdition = &config.ServerEditionConfig{}
+		result := DetectConfigChanges(oldCfg, newCfg)
+		assert.Empty(t, result.ChangedFields)
+		assert.False(t, result.RequiresRestart)
+	})
+
+	t.Run("deprecated store_idp_tokens is never reported", func(t *testing.T) {
+		// contracts/config-keys.md: retained decoder, no-op, "—" for
+		// live/restart. A toggle must not pin a restart.
+		newCfg := serverEditionBase()
+		newCfg.ServerEdition.StoreIDPTokens = true
+		result := DetectConfigChanges(serverEditionBase(), newCfg)
+		assert.NotContains(t, result.ChangedFields, "server_edition")
+		assert.False(t, result.RequiresRestart)
+	})
+
+	t.Run("mixed edit with an early-return key reports that key alone", func(t *testing.T) {
+		// Documents the existing early-return shape: listen (and
+		// routing_mode/data_dir/api_key/tls/timeouts) return immediately with
+		// only that field; the restart re-reads the whole file, block included.
+		newCfg := serverEditionBase()
+		newCfg.Listen = "127.0.0.1:9090"
+		newCfg.ServerEdition.OAuth.ClientID = "client-two"
+		result := DetectConfigChanges(serverEditionBase(), newCfg)
+		assert.Equal(t, []string{"listen"}, result.ChangedFields)
+		assert.True(t, result.RequiresRestart)
+	})
+
+	t.Run("restart-pinned key beside a live key reports both", func(t *testing.T) {
+		newCfg := serverEditionBase()
+		newCfg.ServerEdition.AdminEmails = []string{"other@example.com"}
+		newCfg.ServerEdition.PublicURL = "https://mcp2.example.com"
+		result := DetectConfigChanges(serverEditionBase(), newCfg)
+		assert.ElementsMatch(t, []string{"server_edition", "server_edition.admin_emails"}, result.ChangedFields)
+		assert.True(t, result.RequiresRestart)
+	})
+}
diff --git a/internal/runtime/config_hotreload_test.go b/internal/runtime/config_hotreload_test.go
index b15841979..61f6323a0 100644
--- a/internal/runtime/config_hotreload_test.go
+++ b/internal/runtime/config_hotreload_test.go
@@ -1100,3 +1100,30 @@ func TestDetectConfigChanges_RoutingModeNormalization(t *testing.T) {
 		assert.Contains(t, result.ChangedFields, "routing_mode")
 	})
 }
+
+// Spec 107 FR-027 (T047): trusted_proxies is live — reported as a changed
+// field, never restart-pinned; nil vs empty is not a change (omitempty).
+func TestDetectConfigChanges_TrustedProxies(t *testing.T) {
+	mk := func(list []string) *config.Config {
+		return &config.Config{
+			Listen: "127.0.0.1:8080", DataDir: "/d", TLS: &config.TLSConfig{},
+			TrustedProxies: list,
+		}
+	}
+
+	t.Run("trusted_proxies change detected live", func(t *testing.T) {
+		result := DetectConfigChanges(mk(nil), mk([]string{"10.0.0.0/8"}))
+		require.True(t, result.Success)
+		assert.Contains(t, result.ChangedFields, "trusted_proxies")
+		assert.False(t, result.RequiresRestart, "trusted_proxies is hot-reloadable")
+		assert.True(t, result.AppliedImmediately)
+	})
+
+	t.Run("nil vs empty slice not reported", func(t *testing.T) {
+		assert.NotContains(t, DetectConfigChanges(mk(nil), mk([]string{})).ChangedFields, "trusted_proxies")
+	})
+
+	t.Run("unchanged list not reported", func(t *testing.T) {
+		assert.NotContains(t, DetectConfigChanges(mk([]string{"::1"}), mk([]string{"::1"})).ChangedFields, "trusted_proxies")
+	})
+}
diff --git a/internal/runtime/restart_gated.go b/internal/runtime/restart_gated.go
index 1e21559d4..f6d4a2274 100644
--- a/internal/runtime/restart_gated.go
+++ b/internal/runtime/restart_gated.go
@@ -45,6 +45,16 @@ func pinRestartGated(live, desired *config.Config) *config.Config {
 	// the detector, which is exactly why it is easy to miss here — and missing
 	// it would let the API report a pool size that is not in effect.
 	pinned.CodeExecutionPoolSize = live.CodeExecutionPoolSize
+	// server_edition's restart-pinned subset (enabled, oauth.*, public_url,
+	// session_cookie_secure, session_ttl, bearer_token_ttl,
+	// credential_encryption_key — Spec 107 FR-039 part 2) is bound at login
+	// handler / session store / credential store construction, exactly like
+	// the fields above; admin_emails stays hot (#1169). Cross-review round 1,
+	// chunk 3 P1: this block was missing entirely, so e.g. disabling
+	// server_edition.enabled took effect in the live config immediately —
+	// restoring anonymous /mcp access — while DetectConfigChanges still
+	// reported the apply as requiring a restart.
+	pinned.ServerEdition = config.MergeServerEditionRestartGated(live.ServerEdition, desired.ServerEdition)
 	return &pinned
 }
 
diff --git a/internal/runtime/restart_gated_serveredition_test.go b/internal/runtime/restart_gated_serveredition_test.go
new file mode 100644
index 000000000..85ec99018
--- /dev/null
+++ b/internal/runtime/restart_gated_serveredition_test.go
@@ -0,0 +1,86 @@
+//go:build server
+
+package runtime
+
+import (
+	"testing"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestPinRestartGatedCoversServerEdition is the regression test for
+// cross-review round 1, chunk 3 P1: pinRestartGated did not pin ServerEdition
+// at all, so a config apply that only reported "requires restart" for
+// server_edition.enabled (and the rest of the restart-pinned subset — oauth.*,
+// public_url, session_cookie_secure, session_ttl, bearer_token_ttl,
+// credential_encryption_key — Spec 107 FR-039 part 2) actually adopted the new
+// value into the running config immediately. The most severe instance:
+// disabling server_edition.enabled restored anonymous /mcp access at once
+// (config.EffectiveRequireMCPAuth reads it live) while the operator was told a
+// restart was still needed.
+//
+// Mirrors TestPinRestartGatedCoversEveryRestartGatedField's technique (driven
+// off the detector itself) for the one field the edition-neutral test above
+// cannot reach — ServerEditionConfig only exists with real fields under the
+// server build.
+func TestPinRestartGatedCoversServerEdition(t *testing.T) {
+	base := func() *config.Config {
+		c := config.DefaultConfig()
+		c.ServerEdition = &config.ServerEditionConfig{
+			Enabled:     true,
+			AdminEmails: []string{"admin@example.com"},
+			OAuth:       &config.ServerEditionOAuthConfig{Provider: "google", ClientID: "cid", ClientSecret: "secret"},
+		}
+		return c
+	}
+
+	mutations := map[string]func(*config.Config){
+		"enabled": func(c *config.Config) { c.ServerEdition.Enabled = false },
+		"public_url": func(c *config.Config) {
+			c.ServerEdition.PublicURL = "https://mcpproxy.example.com"
+		},
+		"oauth_provider": func(c *config.Config) { c.ServerEdition.OAuth.Provider = "oidc" },
+	}
+
+	for name, mutate := range mutations {
+		t.Run(name, func(t *testing.T) {
+			live := base()
+			desired := base() // independent structs — no shared pointers
+			mutate(desired)
+
+			require.True(t, DetectConfigChanges(live, desired).RequiresRestart,
+				"test premise: server_edition.%s must be restart-gated", name)
+
+			pinned := pinRestartGated(live, desired)
+			result := DetectConfigChanges(live, pinned)
+			assert.False(t, result.RequiresRestart,
+				"pinRestartGated missed server_edition.%s: it would be adopted in memory (e.g. flipping EffectiveRequireMCPAuth) while the API reports it pending", name)
+			assert.Equal(t, live.ServerEdition.Enabled, pinned.ServerEdition.Enabled,
+				"enabled must come from live, never from desired, until restart")
+		})
+	}
+}
+
+// TestPinRestartGatedKeepsServerEditionAdminEmailsHot proves the flip side:
+// admin_emails is deliberately NOT pinned (it is read live through
+// ServerEditionConfigProvider, #1169), so a write that only touches
+// admin_emails must not be forced to live's stale list.
+func TestPinRestartGatedKeepsServerEditionAdminEmailsHot(t *testing.T) {
+	live := &config.Config{ServerEdition: &config.ServerEditionConfig{
+		Enabled:     true,
+		AdminEmails: []string{"old@example.com"},
+		OAuth:       &config.ServerEditionOAuthConfig{Provider: "google", ClientID: "cid", ClientSecret: "secret"},
+	}}
+	desired := &config.Config{ServerEdition: &config.ServerEditionConfig{
+		Enabled:     true,
+		AdminEmails: []string{"new@example.com"},
+		OAuth:       &config.ServerEditionOAuthConfig{Provider: "google", ClientID: "cid", ClientSecret: "secret"},
+	}}
+
+	pinned := pinRestartGated(live, desired)
+	require.NotNil(t, pinned.ServerEdition)
+	assert.Equal(t, []string{"new@example.com"}, pinned.ServerEdition.AdminEmails,
+		"admin_emails must survive pinning: it is the one hot field of the block (#1169)")
+}
diff --git a/internal/server/mcp_auth_forced_personal_test.go b/internal/server/mcp_auth_forced_personal_test.go
new file mode 100644
index 000000000..5c93c16c1
--- /dev/null
+++ b/internal/server/mcp_auth_forced_personal_test.go
@@ -0,0 +1,94 @@
+//go:build !server
+
+package server
+
+// Spec 107 T049 (US2, FR-029) — personal-build twin of mcp_auth_forced_test.go.
+//
+// The personal build carries `server_edition` as an opaque json.RawMessage
+// (FR-040) and never interprets it: config.EffectiveRequireMCPAuth (T052 stub)
+// returns cfg.RequireMCPAuth, the /mcp middleware keeps the #1148 back-compat
+// anonymous administrator, and no boot notice is logged — even when the
+// carrier says `"enabled": true`.
+//
+// Compile-red until T052 lands the `_stub.go` accessor.
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapcore"
+	"go.uber.org/zap/zaptest/observer"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+)
+
+// personalEditionCarrier builds the opaque server_edition carrier the personal
+// build keeps: the only way to construct one from Go code is through its
+// UnmarshalJSON.
+func personalEditionCarrier(t *testing.T) *config.ServerEditionConfig {
+	t.Helper()
+	carrier := &config.ServerEditionConfig{}
+	require.NoError(t, json.Unmarshal([]byte(`{"enabled":true,"admin_emails":["admin@example.com"],"oauth":{"provider":"google","client_id":"id","client_secret":"secret"}}`), carrier))
+	return carrier
+}
+
+func personalForcedAuthConfig(t *testing.T, requireMCPAuth bool) *config.Config {
+	t.Helper()
+	cfg := config.DefaultConfig()
+	cfg.DataDir = t.TempDir()
+	cfg.Listen = "127.0.0.1:0"
+	cfg.APIKey = "test-api-key"
+	cfg.RequireMCPAuth = requireMCPAuth
+	cfg.ServerEdition = personalEditionCarrier(t)
+	return cfg
+}
+
+// TestEffectiveRequireMCPAuth_PersonalBuild: the accessor is the configured
+// value, whatever the opaque carrier says.
+func TestEffectiveRequireMCPAuth_PersonalBuild(t *testing.T) {
+	for _, configured := range []bool{false, true} {
+		cfg := &config.Config{RequireMCPAuth: configured, ServerEdition: personalEditionCarrier(t)}
+		assert.Equal(t, configured, config.EffectiveRequireMCPAuth(cfg), "configured=%v", configured)
+	}
+	assert.False(t, config.EffectiveRequireMCPAuth(&config.Config{}))
+	assert.True(t, config.EffectiveRequireMCPAuth(&config.Config{RequireMCPAuth: true}))
+}
+
+// TestMCPAuthMiddleware_PersonalBuildIgnoresCarrier: the personal edition is
+// unaffected by the block (FR-040 opaque carrier) — no forced auth, no notice.
+func TestMCPAuthMiddleware_PersonalBuildIgnoresCarrier(t *testing.T) {
+	core, logs := observer.New(zapcore.InfoLevel)
+	srv, err := NewServer(personalForcedAuthConfig(t, false), zap.New(core))
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = srv.Shutdown() })
+
+	t.Run("no credential keeps the back-compat anonymous admin", func(t *testing.T) {
+		seen, code := captureAuthContext(t, srv, httptest.NewRequest(http.MethodPost, "/mcp", http.NoBody))
+		require.Equal(t, http.StatusOK, code)
+		require.NotNil(t, seen)
+		assert.True(t, seen.IsAdmin())
+		assert.True(t, seen.Anonymous)
+	})
+
+	t.Run("unrecognised bearer keeps the back-compat anonymous admin", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/mcp", http.NoBody)
+		req.Header.Set("Authorization", "Bearer not-a-credential")
+		seen, code := captureAuthContext(t, srv, req)
+		require.Equal(t, http.StatusOK, code)
+		require.NotNil(t, seen)
+		assert.True(t, seen.Anonymous)
+	})
+
+	t.Run("no boot notice is logged", func(t *testing.T) {
+		for _, e := range logs.All() {
+			assert.False(t, strings.Contains(e.Message, "require_mcp_auth") && strings.Contains(e.Message, "overridden"),
+				"personal build must not log the server-edition override notice: %q", e.Message)
+		}
+	})
+}
diff --git a/internal/server/mcp_auth_forced_test.go b/internal/server/mcp_auth_forced_test.go
new file mode 100644
index 000000000..fc4a1a701
--- /dev/null
+++ b/internal/server/mcp_auth_forced_test.go
@@ -0,0 +1,367 @@
+//go:build server
+
+package server
+
+// Spec 107 T049 (US2, FR-029, FR-043(a)): forced MCP authentication under the
+// server edition.
+//
+// With `server_edition.enabled: true` the /mcp* auth middleware MUST behave as
+// if `require_mcp_auth` were true regardless of the configured value: no
+// credential → 401, an unrecognised bearer (a session cookie, a user JWT) →
+// 401; agent tokens, the global API key and the socket are unchanged. The
+// decision is the build-tagged accessor config.EffectiveRequireMCPAuth (T052:
+// server build `cfg.RequireMCPAuth || server_edition.enabled`, personal build
+// `cfg.RequireMCPAuth`), so internal/server stays edition-neutral. An explicit
+// `require_mcp_auth: false` is not a validation error; boot logs one notice
+// with the contracts/config-keys.md text.
+//
+// Compile-red until T052 lands config.EffectiveRequireMCPAuth; the middleware
+// assertions are then behaviour-red until mcpAuthMiddleware (server.go:353,450)
+// reads the accessor and the boot notice is emitted. The personal-build twin
+// is mcp_auth_forced_personal_test.go.
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapcore"
+	"go.uber.org/zap/zaptest/observer"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/auth"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+	teamsauth "github.com/smart-mcp-proxy/mcpproxy-go/internal/serveredition/auth"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/transport"
+)
+
+// forcedAuthBootNotice is the exact boot-notice text of contracts/config-keys.md
+// (`require_mcp_auth` row).
+const forcedAuthBootNotice = "require_mcp_auth: false is overridden to true because server_edition.enabled is true"
+
+// forcedAuthConfig returns a config with the server-edition block enabled and a
+// valid legacy OAuth block (no network I/O: discovery is lazy, and NewServer
+// does not run SetupAll — wireServerEditionOAuth runs in startCustomHTTPServer).
+func forcedAuthConfig(t *testing.T, apiKey string, requireMCPAuth, editionEnabled bool) *config.Config {
+	t.Helper()
+	cfg := config.DefaultConfig()
+	cfg.DataDir = t.TempDir()
+	cfg.Listen = "127.0.0.1:0"
+	cfg.APIKey = apiKey
+	cfg.RequireMCPAuth = requireMCPAuth
+	cfg.ServerEdition = &config.ServerEditionConfig{
+		Enabled:     editionEnabled,
+		AdminEmails: []string{"admin@example.com"},
+		OAuth: &config.ServerEditionOAuthConfig{
+			Provider:     "google",
+			ClientID:     "test-client-id",
+			ClientSecret: "test-client-secret",
+		},
+	}
+	return cfg
+}
+
+func newForcedAuthTestServer(t *testing.T, cfg *config.Config, logger *zap.Logger) *Server {
+	t.Helper()
+	srv, err := NewServer(cfg, logger)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = srv.Shutdown() })
+	return srv
+}
+
+// mintAgentToken creates a real mcp_agt_ token against the server's HMAC key
+// and storage, so the agent branch of the middleware validates end-to-end.
+func mintAgentToken(t *testing.T, srv *Server, name string) string {
+	t.Helper()
+	cfg := srv.runtime.Config()
+	hmacKey, err := auth.GetOrCreateHMACKey(cfg.DataDir)
+	require.NoError(t, err)
+	raw, err := auth.GenerateToken()
+	require.NoError(t, err)
+	require.NoError(t, srv.runtime.StorageManager().CreateAgentToken(auth.AgentToken{
+		Name:           name,
+		AllowedServers: []string{"*"},
+		Permissions:    []string{"read"},
+		ExpiresAt:      time.Now().Add(time.Hour),
+	}, raw, hmacKey))
+	return raw
+}
+
+// mintUserJWT signs a server-edition user bearer JWT with the same HMAC key the
+// server derives from its data dir — a genuine SSO credential, not a random
+// string, so the "unrecognised bearer" branch is exercised with the real thing.
+func mintUserJWT(t *testing.T, srv *Server) string {
+	t.Helper()
+	cfg := srv.runtime.Config()
+	hmacKey, err := auth.GetOrCreateHMACKey(cfg.DataDir)
+	require.NoError(t, err)
+	token, err := teamsauth.GenerateBearerToken(hmacKey, "01HZUSERAAAAAAAAAAAAAAAAA", "alice@example.com", "Alice", "user", "google", time.Hour)
+	require.NoError(t, err)
+	return token
+}
+
+// TestEffectiveRequireMCPAuth_ServerBuild pins the accessor's truth table on
+// the server build (research D11): the edition flag forces true; otherwise the
+// configured value is returned unchanged.
+func TestEffectiveRequireMCPAuth_ServerBuild(t *testing.T) {
+	cases := []struct {
+		name       string
+		require    bool
+		block      *config.ServerEditionConfig
+		wantForced bool
+	}{
+		{"enabled block forces true over an explicit false", false, &config.ServerEditionConfig{Enabled: true}, true},
+		{"enabled block keeps an explicit true", true, &config.ServerEditionConfig{Enabled: true}, true},
+		{"disabled block returns the configured false", false, &config.ServerEditionConfig{Enabled: false}, false},
+		{"disabled block returns the configured true", true, &config.ServerEditionConfig{Enabled: false}, true},
+		{"absent block returns the configured false", false, nil, false},
+		{"absent block returns the configured true", true, nil, true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg := &config.Config{RequireMCPAuth: tc.require, ServerEdition: tc.block}
+			assert.Equal(t, tc.wantForced, config.EffectiveRequireMCPAuth(cfg))
+		})
+	}
+}
+
+// TestMCPAuthMiddleware_ForcedUnderServerEdition is FR-029 / FR-043(a) at the
+// middleware seam: `require_mcp_auth: false` is configured, the server-edition
+// block is enabled, and every unauthenticated or SSO-credentialed request is
+// refused while the three real MCP credentials keep working.
+func TestMCPAuthMiddleware_ForcedUnderServerEdition(t *testing.T) {
+	const apiKey = "test-api-key-fr029"
+	srv := newForcedAuthTestServer(t, forcedAuthConfig(t, apiKey, false, true), zap.NewNop())
+	require.False(t, srv.runtime.Config().RequireMCPAuth, "fixture: the configured value stays false; only the effective value is forced")
+
+	t.Run("no credential is refused with the existing 401 body", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/mcp", http.NoBody)
+		seen, code := captureAuthContext(t, srv, req)
+		require.Equal(t, http.StatusUnauthorized, code)
+		require.Nil(t, seen, "the downstream handler must not run for an unauthenticated caller")
+	})
+
+	t.Run("no credential 401 body is unchanged and carries no WWW-Authenticate", func(t *testing.T) {
+		rec := httptest.NewRecorder()
+		srv.mcpAuthMiddleware(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {
+			t.Fatal("downstream handler reached without a credential")
+		})).ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/mcp", http.NoBody))
+		require.Equal(t, http.StatusUnauthorized, rec.Code)
+		assert.Contains(t, rec.Body.String(), "Authentication required", "contracts/rest-endpoints.md §9: body unchanged")
+		assert.Empty(t, rec.Header().Get("WWW-Authenticate"), "Spec 089 scope: no challenge header here")
+	})
+
+	t.Run("session cookie alone is refused", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/mcp", http.NoBody)
+		req.AddCookie(&http.Cookie{Name: teamsauth.SessionCookieName, Value: "sess-0123456789abcdef"})
+		seen, code := captureAuthContext(t, srv, req)
+		require.Equal(t, http.StatusUnauthorized, code)
+		require.Nil(t, seen)
+	})
+
+	t.Run("user JWT as Bearer is refused", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/mcp", http.NoBody)
+		req.Header.Set("Authorization", "Bearer "+mintUserJWT(t, srv))
+		rec := httptest.NewRecorder()
+		var seen *auth.AuthContext
+		srv.mcpAuthMiddleware(http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) {
+			seen = auth.AuthContextFromContext(r.Context())
+		})).ServeHTTP(rec, req)
+		require.Equal(t, http.StatusUnauthorized, rec.Code)
+		require.Nil(t, seen, "a JWT is not an MCP credential (research: no second /mcp credential type)")
+		assert.Contains(t, rec.Body.String(), "Invalid authentication token")
+	})
+
+	t.Run("user JWT as X-API-Key is refused", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/mcp", http.NoBody)
+		req.Header.Set("X-API-Key", mintUserJWT(t, srv))
+		seen, code := captureAuthContext(t, srv, req)
+		require.Equal(t, http.StatusUnauthorized, code)
+		require.Nil(t, seen)
+	})
+
+	t.Run("user JWT plus session cookie is refused", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/mcp", http.NoBody)
+		req.Header.Set("Authorization", "Bearer "+mintUserJWT(t, srv))
+		req.AddCookie(&http.Cookie{Name: teamsauth.SessionCookieName, Value: "sess-0123456789abcdef"})
+		seen, code := captureAuthContext(t, srv, req)
+		require.Equal(t, http.StatusUnauthorized, code)
+		require.Nil(t, seen)
+	})
+
+	t.Run("every /mcp route is refused without a credential", func(t *testing.T) {
+		for _, path := range []string{"/mcp", "/mcp/all", "/mcp/code", "/mcp/call", "/mcp/p/research"} {
+			seen, code := captureAuthContext(t, srv, httptest.NewRequest(http.MethodPost, path, http.NoBody))
+			assert.Equal(t, http.StatusUnauthorized, code, path)
+			assert.Nil(t, seen, path)
+		}
+	})
+
+	t.Run("agent token is unchanged", func(t *testing.T) {
+		raw := mintAgentToken(t, srv, "fr029-agent")
+		req := httptest.NewRequest(http.MethodPost, "/mcp", http.NoBody)
+		req.Header.Set("Authorization", "Bearer "+raw)
+		seen, code := captureAuthContext(t, srv, req)
+		require.Equal(t, http.StatusOK, code)
+		require.NotNil(t, seen)
+		assert.Equal(t, auth.AuthTypeAgent, seen.Type)
+		assert.Equal(t, "fr029-agent", seen.AgentName)
+		assert.False(t, seen.Anonymous)
+	})
+
+	t.Run("global API key is unchanged", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/mcp", http.NoBody)
+		req.Header.Set("X-API-Key", apiKey)
+		seen, code := captureAuthContext(t, srv, req)
+		require.Equal(t, http.StatusOK, code)
+		require.NotNil(t, seen)
+		assert.True(t, seen.IsAdmin())
+		assert.False(t, seen.Anonymous)
+		assert.True(t, seen.CanRevealSecrets())
+	})
+
+	t.Run("socket connection without a credential is unchanged", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/mcp", http.NoBody)
+		req = req.WithContext(transport.TagConnectionContext(req.Context(), transport.ConnectionSourceTray))
+		seen, code := captureAuthContext(t, srv, req)
+		require.Equal(t, http.StatusOK, code)
+		require.NotNil(t, seen)
+		assert.True(t, seen.IsAdmin())
+		assert.False(t, seen.Anonymous, "OS-level socket auth is a real identity")
+	})
+
+	t.Run("socket connection with an unrecognised token is unchanged", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/mcp", http.NoBody)
+		req.Header.Set("X-API-Key", "not-the-key")
+		req = req.WithContext(transport.TagConnectionContext(req.Context(), transport.ConnectionSourceTray))
+		seen, code := captureAuthContext(t, srv, req)
+		require.Equal(t, http.StatusOK, code)
+		require.NotNil(t, seen)
+		assert.False(t, seen.Anonymous)
+	})
+
+	t.Run("no AnonymousContext is ever handed out", func(t *testing.T) {
+		// FR-029 invariant: in the published container no unauthenticated
+		// caller receives an admin-typed AnonymousContext (server.go:381-384,
+		// :455-458). Sweep the credential shapes that used to reach it.
+		shapes := map[string]func(*http.Request){
+			"nothing":        func(*http.Request) {},
+			"unknown bearer": func(r *http.Request) { r.Header.Set("Authorization", "Bearer not-a-credential") },
+			"unknown apikey": func(r *http.Request) { r.Header.Set("X-API-Key", "not-a-credential") },
+			"query apikey":   func(r *http.Request) { r.URL.RawQuery = "apikey=not-a-credential" },
+			"cookie":         func(r *http.Request) { r.AddCookie(&http.Cookie{Name: teamsauth.SessionCookieName, Value: "x"}) },
+		}
+		for name, shape := range shapes {
+			req := httptest.NewRequest(http.MethodPost, "/mcp", http.NoBody)
+			shape(req)
+			seen, code := captureAuthContext(t, srv, req)
+			assert.Equal(t, http.StatusUnauthorized, code, name)
+			if seen != nil {
+				assert.False(t, seen.Anonymous, "%s: anonymous admin context reached the handler", name)
+			}
+		}
+	})
+}
+
+// TestMCPAuthMiddleware_ServerBuildDisabledBlockKeepsBackCompat proves the
+// override keys on `server_edition.enabled`, not on the build tag: a server
+// build with the block disabled behaves exactly like the personal build.
+func TestMCPAuthMiddleware_ServerBuildDisabledBlockKeepsBackCompat(t *testing.T) {
+	srv := newForcedAuthTestServer(t, forcedAuthConfig(t, "test-api-key", false, false), zap.NewNop())
+
+	seen, code := captureAuthContext(t, srv, httptest.NewRequest(http.MethodPost, "/mcp", http.NoBody))
+	require.Equal(t, http.StatusOK, code)
+	require.NotNil(t, seen)
+	assert.True(t, seen.IsAdmin())
+	assert.True(t, seen.Anonymous, "back-compat anonymous admin stays for a disabled block (#1148)")
+}
+
+func loggedMessages(logs *observer.ObservedLogs) []string {
+	var out []string
+	for _, e := range logs.All() {
+		out = append(out, e.Message)
+	}
+	return out
+}
+
+// TestServerEdition_ForcedMCPAuthBootNotice: an explicit `require_mcp_auth:
+// false` under an enabled block is not a validation error (no boot failure on
+// upgrade for the installs that run with it off) but boot MUST log exactly one
+// notice with the contracts/config-keys.md text. Nothing is logged when the
+// value is already true or the block is disabled/absent.
+func TestServerEdition_ForcedMCPAuthBootNotice(t *testing.T) {
+	notices := func(logs *observer.ObservedLogs) []observer.LoggedEntry {
+		var out []observer.LoggedEntry
+		for _, e := range logs.All() {
+			if strings.Contains(e.Message, "require_mcp_auth") && strings.Contains(e.Message, "overridden") {
+				out = append(out, e)
+			}
+		}
+		return out
+	}
+
+	t.Run("explicit false under an enabled block logs one notice", func(t *testing.T) {
+		core, logs := observer.New(zapcore.InfoLevel)
+		newForcedAuthTestServer(t, forcedAuthConfig(t, "k", false, true), zap.New(core))
+
+		got := notices(logs)
+		require.Len(t, got, 1, "exactly one boot notice; messages seen: %v", loggedMessages(logs))
+		assert.Contains(t, got[0].Message, forcedAuthBootNotice)
+		assert.GreaterOrEqual(t, got[0].Level, zapcore.InfoLevel)
+		assert.LessOrEqual(t, got[0].Level, zapcore.WarnLevel, "a notice, never an error: the value is overridden, not refused")
+	})
+
+	t.Run("explicit true under an enabled block logs nothing", func(t *testing.T) {
+		core, logs := observer.New(zapcore.InfoLevel)
+		newForcedAuthTestServer(t, forcedAuthConfig(t, "k", true, true), zap.New(core))
+		assert.Empty(t, notices(logs))
+	})
+
+	t.Run("false under a disabled block logs nothing", func(t *testing.T) {
+		core, logs := observer.New(zapcore.InfoLevel)
+		newForcedAuthTestServer(t, forcedAuthConfig(t, "k", false, false), zap.New(core))
+		assert.Empty(t, notices(logs))
+	})
+
+	t.Run("false with no block logs nothing", func(t *testing.T) {
+		core, logs := observer.New(zapcore.InfoLevel)
+		cfg := forcedAuthConfig(t, "k", false, false)
+		cfg.ServerEdition = nil
+		newForcedAuthTestServer(t, cfg, zap.New(core))
+		assert.Empty(t, notices(logs))
+	})
+}
+
+// TestConnectServiceWiring_UsesEffectiveRequireMCPAuth pins the connect
+// service wiring in server.go to the build-tagged accessor. FR-029 forces
+// /mcp authentication under an enabled server_edition regardless of the
+// configured require_mcp_auth; connect.Service decides whether to embed a
+// credential in generated client configs from exactly the value it is
+// threaded. Wiring it from the raw config.RequireMCPAuth field (as it stood
+// before cross-review round 3) reintroduces credential-less client configs
+// that /mcp then answers 401 to on their first real call — the mirror image
+// of the Spec 078 leak this field exists to prevent.
+//
+// A source guard, not a behavioural one: exercising the real defect needs a
+// listening HTTP server (startCustomHTTPServer, not NewServer alone — see the
+// file comment above), out of proportion for a P2 wiring regression with an
+// accessor already proven correct at every other call site (server.go:378,
+// :475, TestEffectiveRequireMCPAuth_ServerBuild above).
+func TestConnectServiceWiring_UsesEffectiveRequireMCPAuth(t *testing.T) {
+	src, err := os.ReadFile("server.go")
+	require.NoError(t, err)
+	text := string(src)
+
+	require.True(t, strings.Contains(text, "connect.NewService("), "fixture: the connect wiring block must still exist")
+	assert.NotContains(t, text, "WithRequireMCPAuth(cfg.RequireMCPAuth)",
+		"connect must be wired from config.EffectiveRequireMCPAuth(cfg), not the raw field (FR-029)")
+	assert.NotContains(t, text, "c.Listen, c.APIKey, c.RequireMCPAuth",
+		"the live config-provider closure must return config.EffectiveRequireMCPAuth(c), not the raw field (FR-029)")
+	assert.Contains(t, text, "WithRequireMCPAuth(config.EffectiveRequireMCPAuth(cfg))")
+	assert.Contains(t, text, "c.Listen, c.APIKey, config.EffectiveRequireMCPAuth(c)")
+}
diff --git a/internal/server/server.go b/internal/server/server.go
index c3daf64a8..08dbc6846 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -32,6 +32,7 @@ import (
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/oauth"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/observability"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/profile"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/reqcontext"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/runtime"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/runtime/stateview"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/secret"
@@ -260,6 +261,17 @@ func NewServerWithConfigPath(cfg *config.Config, configPath string, logger *zap.
 	)
 	rt.SetManagementService(mgmtService)
 
+	// Spec 107 T052: configuration findings for `mcpproxy doctor`, read from
+	// the LIVE config on every Doctor call (never the boot pointer).
+	mgmtService.AddRuntimeWarningSource(func() []string {
+		return config.DoctorFindings(rt.Config())
+	})
+	// Spec 107 FR-029: an explicit require_mcp_auth: false under an enabled
+	// server-edition block is overridden, never refused — one boot notice.
+	if config.RequireMCPAuthOverridden(cfg) {
+		logger.Warn(config.MsgRequireMCPAuthOverridden)
+	}
+
 	server := &Server{
 		logger:              logger,
 		runtime:             rt,
@@ -333,6 +345,17 @@ func NewServerWithConfigPath(cfg *config.Config, configPath string, logger *zap.
 	return server, nil
 }
 
+// trustedProxiesProvider yields the LIVE trusted_proxies list (Spec 107
+// FR-027) through the runtime's config snapshot, evaluated per request.
+func (s *Server) trustedProxiesProvider() config.TrustedProxiesProvider {
+	return func() []string {
+		if cfg := s.runtime.Config(); cfg != nil {
+			return cfg.TrustedProxies
+		}
+		return nil
+	}
+}
+
 // mcpAuthMiddleware wraps the MCP endpoint handler to inject AuthContext into the
 // request context. The MCP endpoint is not behind the REST API key middleware, so
 // this middleware extracts tokens from the request and creates the appropriate
@@ -342,15 +365,17 @@ func NewServerWithConfigPath(cfg *config.Config, configPath string, logger *zap.
 // AuthContext with server/permission scopes. For the global API key, it sets an
 // admin AuthContext.
 //
-// When config.RequireMCPAuth is true, unauthenticated requests are rejected with
-// 401 Unauthorized. When false (default), unauthenticated requests get admin
-// context for backward compatibility. Tray connections always bypass auth.
+// When config.EffectiveRequireMCPAuth is true (require_mcp_auth, or an enabled
+// server-edition block — Spec 107 FR-029), unauthenticated requests are
+// rejected with 401 Unauthorized. When false (default), unauthenticated
+// requests get admin context for backward compatibility. Tray connections
+// always bypass auth.
 func (s *Server) mcpAuthMiddleware(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		token := httpapi.ExtractToken(r)
 		if token == "" {
 			// Check if MCP auth is required
-			if cfg := s.runtime.Config(); cfg != nil && cfg.RequireMCPAuth {
+			if cfg := s.runtime.Config(); config.EffectiveRequireMCPAuth(cfg) {
 				// Tray connections are always trusted, even with require_mcp_auth
 				source := transport.GetConnectionSource(r.Context())
 				if source == transport.ConnectionSourceTray {
@@ -447,7 +472,7 @@ func (s *Server) mcpAuthMiddleware(next http.Handler) http.Handler {
 		}
 
 		// Token provided but doesn't match anything
-		if cfg := s.runtime.Config(); cfg != nil && cfg.RequireMCPAuth {
+		if cfg := s.runtime.Config(); config.EffectiveRequireMCPAuth(cfg) {
 			// When auth is required, reject unrecognized tokens
 			http.Error(w, `{"error":"Invalid authentication token"}`, http.StatusUnauthorized)
 			return
@@ -2668,7 +2693,10 @@ func (s *Server) startCustomHTTPServer(ctx context.Context, streamableServer *se
 	//
 	// streamingNoDeadline is the OUTERMOST wrapper on every MCP route so a tool
 	// call slower than http.Server.WriteTimeout is not truncated (GH #965).
-	mcpHandler := s.streamingNoDeadline(s.hostValidationMiddleware(s.mcpAuthMiddleware(loggingHandler(streamableServer))))
+	// Spec 107 T050: tag every MCP-mount request with {ClientIP, Mount: mcp}
+	// for the audit line (the mount is fixed here, never by a header).
+	tagMCP := httpapi.TagRequestMeta(reqcontext.MountMCP, s.trustedProxiesProvider())
+	mcpHandler := s.streamingNoDeadline(s.hostValidationMiddleware(tagMCP(s.mcpAuthMiddleware(loggingHandler(streamableServer)))))
 	mux.Handle("/mcp", mcpHandler)
 	mux.Handle("/mcp/", mcpHandler) // Handle trailing slash
 
@@ -2677,21 +2705,21 @@ func (s *Server) startCustomHTTPServer(ctx context.Context, streamableServer *se
 	// /mcp/all → direct mode (all tools with serverName__toolName naming)
 	directStreamable := server.NewStreamableHTTPServer(s.mcpProxy.GetMCPServerForMode(config.RoutingModeDirect),
 		clientFacingStreamableOptions()...)
-	directHandler := s.streamingNoDeadline(s.hostValidationMiddleware(s.mcpAuthMiddleware(loggingHandler(directStreamable))))
+	directHandler := s.streamingNoDeadline(s.hostValidationMiddleware(tagMCP(s.mcpAuthMiddleware(loggingHandler(directStreamable)))))
 	mux.Handle("/mcp/all", directHandler)
 	mux.Handle("/mcp/all/", directHandler)
 
 	// /mcp/code → code_execution mode (JS orchestration)
 	codeExecStreamable := server.NewStreamableHTTPServer(s.mcpProxy.GetMCPServerForMode(config.RoutingModeCodeExecution),
 		clientFacingStreamableOptions()...)
-	codeExecHandler := s.streamingNoDeadline(s.hostValidationMiddleware(s.mcpAuthMiddleware(loggingHandler(codeExecStreamable))))
+	codeExecHandler := s.streamingNoDeadline(s.hostValidationMiddleware(tagMCP(s.mcpAuthMiddleware(loggingHandler(codeExecStreamable)))))
 	mux.Handle("/mcp/code", codeExecHandler)
 	mux.Handle("/mcp/code/", codeExecHandler)
 
 	// /mcp/call → retrieve_tools mode (focused: retrieve_tools + call_tool_read/write/destructive)
 	callToolStreamable := server.NewStreamableHTTPServer(s.mcpProxy.GetMCPServerForMode(config.RoutingModeRetrieveTools),
 		clientFacingStreamableOptions()...)
-	callToolHandler := s.streamingNoDeadline(s.hostValidationMiddleware(s.mcpAuthMiddleware(loggingHandler(callToolStreamable))))
+	callToolHandler := s.streamingNoDeadline(s.hostValidationMiddleware(tagMCP(s.mcpAuthMiddleware(loggingHandler(callToolStreamable)))))
 	mux.Handle("/mcp/call", callToolHandler)
 	mux.Handle("/mcp/call/", callToolHandler)
 
@@ -2700,7 +2728,7 @@ func (s *Server) startCustomHTTPServer(ctx context.Context, streamableServer *se
 	// so that agent-token scope can compose downstream with the profile scope.
 	profileStreamable := server.NewStreamableHTTPServer(s.mcpProxy.GetMCPServerForMode(config.RoutingModeRetrieveTools),
 		clientFacingStreamableOptions()...)
-	profileHandler := s.streamingNoDeadline(s.hostValidationMiddleware(s.mcpAuthMiddleware(s.profileMiddleware(loggingHandler(profileStreamable)))))
+	profileHandler := s.streamingNoDeadline(s.hostValidationMiddleware(tagMCP(s.mcpAuthMiddleware(s.profileMiddleware(loggingHandler(profileStreamable))))))
 	mux.Handle("/mcp/p/", profileHandler)
 	mux.Handle("/mcp/p", profileHandler)
 
@@ -2752,7 +2780,13 @@ func (s *Server) startCustomHTTPServer(ctx context.Context, streamableServer *se
 	// Wire client connect service
 	if cfg := s.runtime.Config(); cfg != nil {
 		connectSvc := connect.NewService(cfg.Listen, cfg.APIKey).
-			WithRequireMCPAuth(cfg.RequireMCPAuth).
+			// The effective value (Spec 107 FR-029: forced true under an
+			// enabled server_edition regardless of the raw config), never the
+			// raw field — otherwise a server-edition deployment with
+			// require_mcp_auth: false writes credential-less client configs
+			// while /mcp itself still demands one, so every generated client
+			// gets a 401 on its first real call (cross-review round 3).
+			WithRequireMCPAuth(config.EffectiveRequireMCPAuth(cfg)).
 			// Read listen/api_key/require_mcp_auth LIVE so a runtime toggle (the
 			// /mcp middleware already honors require_mcp_auth per-request) is
 			// reflected in what connect writes, instead of the startup snapshot
@@ -2762,7 +2796,7 @@ func (s *Server) startCustomHTTPServer(ctx context.Context, streamableServer *se
 				if c == nil {
 					return "", "", false
 				}
-				return c.Listen, c.APIKey, c.RequireMCPAuth
+				return c.Listen, c.APIKey, config.EffectiveRequireMCPAuth(c)
 			})
 		httpAPIServer.SetConnectService(connectSvc)
 
@@ -2917,7 +2951,7 @@ func (s *Server) startCustomHTTPServer(ctx context.Context, streamableServer *se
 	s.logger.Info("Registered pprof endpoints", zap.String("path", "/debug/pprof/"))
 
 	// Swagger UI (OpenAPI documentation) - mounted directly on main mux for /swagger/* access
-	swaggerHandler := httpapi.SetupSwaggerHandler(s.logger.Sugar())
+	swaggerHandler := httpapi.SetupSwaggerHandler(s.logger.Sugar(), s.trustedProxiesProvider())
 	mux.Handle("/swagger/", swaggerHandler)
 	s.logger.Info("Registered Swagger UI endpoint", zap.String("swagger_endpoint", "/swagger/*"))
 
diff --git a/internal/server/serveredition_wire.go b/internal/server/serveredition_wire.go
index 144c7e707..251df79fd 100644
--- a/internal/server/serveredition_wire.go
+++ b/internal/server/serveredition_wire.go
@@ -8,6 +8,7 @@ import (
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/httpapi"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/serveredition"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/serveredition/users"
 )
 
 // wireServerEditionOAuth sets up server edition multi-user OAuth routes on the HTTP API server.
@@ -44,4 +45,23 @@ func wireServerEditionOAuth(s *Server, httpAPIServer *httpapi.Server) {
 	if err := serveredition.SetupAll(deps); err != nil {
 		s.logger.Error("Failed to initialize server features", zap.Error(err))
 	}
+
+	// Spec 107 (US7, telemetry v13): install the user counter behind
+	// member_count_bucket. Only a count crosses this seam — the closure reads
+	// the user store and returns len(); no user record, email, group or IdP
+	// subject is ever handed to telemetry. Installed regardless of SetupAll's
+	// outcome and of whether the block is enabled: a server-edition binary
+	// with the block off reports "0" from an empty bucket, which is the same
+	// value the personal edition reports with no counter at all. nil-safe on
+	// the telemetry side (short-lived CLI commands have no service).
+	if ts := s.runtime.TelemetryService(); ts != nil {
+		userStore := users.NewUserStore(sm.GetDB())
+		ts.SetUserCounter(func() (int, error) {
+			list, err := userStore.ListUsers()
+			if err != nil {
+				return 0, err
+			}
+			return len(list), nil
+		})
+	}
 }
diff --git a/internal/serveredition/api/admin_handlers.go b/internal/serveredition/api/admin_handlers.go
index 58068c9a0..1e2e0304f 100644
--- a/internal/serveredition/api/admin_handlers.go
+++ b/internal/serveredition/api/admin_handlers.go
@@ -144,13 +144,37 @@ func (h *AdminHandlers) RegisterRoutesWithPrefix(r chi.Router, prefix string) {
 // --- Response types ---
 
 // UserProfileResponse represents a user profile in admin responses.
+//
+// Spec 107 FR-008/FR-023 (contracts/rest-endpoints.md §4): groups is always
+// an array (never null), groups_updated_at and subject_rebind_armed_at are
+// RFC 3339 or null — the keys are present on every row.
 type UserProfileResponse struct {
-	ID          string `json:"id"`
-	Email       string `json:"email"`
-	DisplayName string `json:"display_name"`
-	Provider    string `json:"provider"`
-	LastLoginAt string `json:"last_login_at"`
-	Disabled    bool   `json:"disabled"`
+	ID                   string   `json:"id"`
+	Email                string   `json:"email"`
+	DisplayName          string   `json:"display_name"`
+	Provider             string   `json:"provider"`
+	LastLoginAt          string   `json:"last_login_at"`
+	Disabled             bool     `json:"disabled"`
+	Groups               []string `json:"groups"`
+	GroupsUpdatedAt      *string  `json:"groups_updated_at"`
+	SubjectRebindArmedAt *string  `json:"subject_rebind_armed_at"`
+}
+
+// rfc3339OrNil renders a timestamp for the wire: nil for the zero time.
+func rfc3339OrNil(t time.Time) *string {
+	if t.IsZero() {
+		return nil
+	}
+	s := t.UTC().Format(time.RFC3339)
+	return &s
+}
+
+// rfc3339PtrOrNil renders an optional timestamp for the wire.
+func rfc3339PtrOrNil(t *time.Time) *string {
+	if t == nil {
+		return nil
+	}
+	return rfc3339OrNil(*t)
 }
 
 // SessionResponse represents a session in admin responses.
@@ -182,13 +206,20 @@ func (h *AdminHandlers) listUsers(w http.ResponseWriter, r *http.Request) {
 
 	profiles := make([]*UserProfileResponse, 0, len(allUsers))
 	for _, u := range allUsers {
+		groups := u.Groups
+		if groups == nil {
+			groups = []string{}
+		}
 		profiles = append(profiles, &UserProfileResponse{
-			ID:          u.ID,
-			Email:       u.Email,
-			DisplayName: u.DisplayName,
-			Provider:    u.Provider,
-			LastLoginAt: u.LastLoginAt.Format("2006-01-02T15:04:05Z"),
-			Disabled:    u.Disabled,
+			ID:                   u.ID,
+			Email:                u.Email,
+			DisplayName:          u.DisplayName,
+			Provider:             u.Provider,
+			LastLoginAt:          u.LastLoginAt.Format("2006-01-02T15:04:05Z"),
+			Disabled:             u.Disabled,
+			Groups:               groups,
+			GroupsUpdatedAt:      rfc3339OrNil(u.GroupsUpdatedAt),
+			SubjectRebindArmedAt: rfc3339PtrOrNil(u.SubjectRebindArmedAt),
 		})
 	}
 
@@ -228,10 +259,14 @@ func (h *AdminHandlers) disableUser(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	user, err := h.userStore.GetUser(userID)
+	// SetUserDisabled re-reads and writes the record inside one transaction
+	// (cross-review round 1, chunk 2 P1): a blind GetUser+UpdateUser here
+	// could overwrite a concurrent login's own atomic write (groups, subject,
+	// last-login, or its own clearing of this same rebind flag).
+	user, _, err := h.userStore.SetUserDisabled(userID, true)
 	if err != nil {
-		h.logger.Errorw("failed to get user for disable", "user_id", userID, "error", err)
-		writeError(w, http.StatusInternalServerError, "Failed to get user")
+		h.logger.Errorw("failed to disable user", "user_id", userID, "error", err)
+		writeError(w, http.StatusInternalServerError, "Failed to disable user")
 		return
 	}
 	if user == nil {
@@ -239,13 +274,6 @@ func (h *AdminHandlers) disableUser(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	user.Disabled = true
-	if err := h.userStore.UpdateUser(user); err != nil {
-		h.logger.Errorw("failed to disable user", "user_id", userID, "error", err)
-		writeError(w, http.StatusInternalServerError, "Failed to disable user")
-		return
-	}
-
 	// Revoke all sessions for the disabled user.
 	if err := h.sessionManager.RevokeUserSessions(userID); err != nil {
 		h.logger.Errorw("failed to revoke sessions for disabled user", "user_id", userID, "error", err)
@@ -284,10 +312,18 @@ func (h *AdminHandlers) enableUser(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	user, err := h.userStore.GetUser(userID)
+	// Spec 107 FR-023: a REAL disabled→enabled transition opens the
+	// single-use rebind window — the next successful login for this record
+	// may present a new provider subject. Enabling an already-enabled user is
+	// not a transition and neither re-arms nor closes an open window.
+	// SetUserDisabled re-reads and writes the record inside one transaction
+	// (cross-review round 1, chunk 2 P1): a blind GetUser+UpdateUser here
+	// could overwrite a concurrent login's own atomic write, including its
+	// own consumption of this same rebind flag.
+	user, armed, err := h.userStore.SetUserDisabled(userID, false)
 	if err != nil {
-		h.logger.Errorw("failed to get user for enable", "user_id", userID, "error", err)
-		writeError(w, http.StatusInternalServerError, "Failed to get user")
+		h.logger.Errorw("failed to enable user", "user_id", userID, "error", err)
+		writeError(w, http.StatusInternalServerError, "Failed to enable user")
 		return
 	}
 	if user == nil {
@@ -295,14 +331,7 @@ func (h *AdminHandlers) enableUser(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	user.Disabled = false
-	if err := h.userStore.UpdateUser(user); err != nil {
-		h.logger.Errorw("failed to enable user", "user_id", userID, "error", err)
-		writeError(w, http.StatusInternalServerError, "Failed to enable user")
-		return
-	}
-
-	h.logger.Infow("user enabled", "user_id", userID, "email", user.Email)
+	h.logger.Infow("user enabled", "user_id", userID, "email", user.Email, "subject_rebind_armed", armed)
 	writeJSON(w, http.StatusOK, map[string]string{"message": "User enabled"})
 }
 
diff --git a/internal/serveredition/api/admin_handlers_rebind_test.go b/internal/serveredition/api/admin_handlers_rebind_test.go
new file mode 100644
index 000000000..bc57ff611
--- /dev/null
+++ b/internal/serveredition/api/admin_handlers_rebind_test.go
@@ -0,0 +1,195 @@
+//go:build server
+
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/serveredition/users"
+)
+
+// Spec 107 T038/T045 — the administrator-opened rebind window (FR-023):
+// `enable` arms `subject_rebind_armed_at` only on a real disabled→enabled
+// transition, `disable` clears it, and GET /admin/users exposes the field
+// beside `groups` / `groups_updated_at` (contracts/rest-endpoints.md §4).
+//
+// Compile-red until T044 adds User.SubjectRebindArmedAt / Groups /
+// GroupsUpdatedAt; behaviour-red until T045 wires the handlers.
+
+func rebindArmedAt(t *testing.T, store *users.UserStore, id string) *time.Time {
+	t.Helper()
+	u, err := store.GetUser(id)
+	require.NoError(t, err)
+	require.NotNil(t, u)
+	return u.SubjectRebindArmedAt
+}
+
+func postAdmin(t *testing.T, router http.Handler, path string) *httptest.ResponseRecorder {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodPost, path, nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	return w
+}
+
+func TestEnableUser_ArmsSubjectRebindOnRealTransition(t *testing.T) {
+	handlers, store := adminTestSetup(t, nil)
+	router := adminTestRouter(handlers, adminAuthContext())
+
+	user := createTestUser(t, store, "user-rebind", "rebind@example.com", "Rebind Me", "google")
+	user.Disabled = true
+	require.NoError(t, store.UpdateUser(user))
+	require.Nil(t, rebindArmedAt(t, store, user.ID), "precondition: closed")
+
+	before := time.Now().UTC()
+	w := postAdmin(t, router, "/api/v1/admin/users/user-rebind/enable")
+	require.Equal(t, http.StatusOK, w.Code)
+
+	updated, err := store.GetUser(user.ID)
+	require.NoError(t, err)
+	assert.False(t, updated.Disabled)
+	armed := updated.SubjectRebindArmedAt
+	require.NotNil(t, armed, "a real disabled→enabled transition opens the rebind window")
+	assert.WithinDuration(t, before, *armed, 5*time.Second)
+	assert.Equal(t, time.UTC, armed.Location(), "stored in UTC like every other timestamp on the record")
+	assert.Equal(t, "sub-user-rebind", updated.ProviderSubjectID, "enable does not clear the binding — the next login does")
+
+	// A second enable on an already-enabled user is not a transition: it
+	// neither re-arms (no fresh timestamp) nor closes the window.
+	time.Sleep(5 * time.Millisecond)
+	w = postAdmin(t, router, "/api/v1/admin/users/user-rebind/enable")
+	require.Equal(t, http.StatusOK, w.Code)
+	again := rebindArmedAt(t, store, user.ID)
+	require.NotNil(t, again, "a no-op enable must not close the window")
+	assert.True(t, again.Equal(*armed), "a no-op enable must not re-arm: %v != %v", again, armed)
+}
+
+func TestEnableUser_AlreadyEnabledDoesNotArm(t *testing.T) {
+	handlers, store := adminTestSetup(t, nil)
+	router := adminTestRouter(handlers, adminAuthContext())
+
+	user := createTestUser(t, store, "user-noop", "noop@example.com", "No Op", "google")
+
+	w := postAdmin(t, router, "/api/v1/admin/users/user-noop/enable")
+	require.Equal(t, http.StatusOK, w.Code)
+
+	assert.Nil(t, rebindArmedAt(t, store, user.ID), "enable on an enabled user is not a transition and must not arm")
+}
+
+func TestDisableUser_ClearsSubjectRebindWindow(t *testing.T) {
+	handlers, store := adminTestSetup(t, nil)
+	router := adminTestRouter(handlers, adminAuthContext())
+
+	user := createTestUser(t, store, "user-close", "close@example.com", "Close Me", "google")
+	armedAt := time.Now().UTC()
+	user.SubjectRebindArmedAt = &armedAt
+	require.NoError(t, store.UpdateUser(user))
+	require.NotNil(t, rebindArmedAt(t, store, user.ID), "precondition: armed")
+
+	w := postAdmin(t, router, "/api/v1/admin/users/user-close/disable")
+	require.Equal(t, http.StatusOK, w.Code)
+
+	updated, err := store.GetUser(user.ID)
+	require.NoError(t, err)
+	assert.True(t, updated.Disabled)
+	assert.Nil(t, updated.SubjectRebindArmedAt, "disable closes an open window")
+	assert.Equal(t, "sub-user-close", updated.ProviderSubjectID, "disable does not clear the binding (FR-023)")
+}
+
+func TestDisableEnableCycle_ArmsExactlyOnce(t *testing.T) {
+	handlers, store := adminTestSetup(t, nil)
+	router := adminTestRouter(handlers, adminAuthContext())
+
+	user := createTestUser(t, store, "user-cycle", "cycle@example.com", "Cycle", "google")
+
+	require.Equal(t, http.StatusOK, postAdmin(t, router, "/api/v1/admin/users/user-cycle/disable").Code)
+	assert.Nil(t, rebindArmedAt(t, store, user.ID), "disable never arms")
+
+	require.Equal(t, http.StatusOK, postAdmin(t, router, "/api/v1/admin/users/user-cycle/enable").Code)
+	first := rebindArmedAt(t, store, user.ID)
+	require.NotNil(t, first)
+
+	// disable → enable again: a new real transition re-arms with a new time.
+	time.Sleep(5 * time.Millisecond)
+	require.Equal(t, http.StatusOK, postAdmin(t, router, "/api/v1/admin/users/user-cycle/disable").Code)
+	assert.Nil(t, rebindArmedAt(t, store, user.ID))
+	require.Equal(t, http.StatusOK, postAdmin(t, router, "/api/v1/admin/users/user-cycle/enable").Code)
+	second := rebindArmedAt(t, store, user.ID)
+	require.NotNil(t, second)
+	assert.True(t, second.After(*first), "a fresh transition carries a fresh timestamp")
+}
+
+// GET /admin/users carries the additive fields of rest-endpoints.md §4:
+// `groups: string[]`, `groups_updated_at: string|null`,
+// `subject_rebind_armed_at: string|null`. Decoded as raw JSON so the wire
+// shape — not a Go field name — is what is pinned.
+func TestAdminListUsers_ExposesGroupsAndRebindWindow(t *testing.T) {
+	handlers, store := adminTestSetup(t, nil)
+	router := adminTestRouter(handlers, adminAuthContext())
+
+	armedAt := time.Date(2026, 9, 16, 10, 30, 0, 0, time.UTC)
+	groupsAt := time.Date(2026, 9, 16, 9, 0, 0, 0, time.UTC)
+
+	armed := createTestUser(t, store, "user-armed", "armed@example.com", "Armed", "google")
+	armed.Groups = []string{"eng", "ops"}
+	armed.GroupsUpdatedAt = groupsAt
+	armed.SubjectRebindArmedAt = &armedAt
+	require.NoError(t, store.UpdateUser(armed))
+
+	// A record that has never logged in since the upgrade: no groups, no
+	// window — decoded from JSON as the zero values.
+	createTestUser(t, store, "user-plain", "plain@example.com", "Plain", "github")
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/users", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	require.Equal(t, http.StatusOK, w.Code)
+
+	var rows []map[string]json.RawMessage
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &rows))
+	require.Len(t, rows, 2)
+
+	byID := map[string]map[string]json.RawMessage{}
+	for _, row := range rows {
+		var id string
+		require.NoError(t, json.Unmarshal(row["id"], &id))
+		byID[id] = row
+	}
+
+	armedRow := byID["user-armed"]
+	require.NotNil(t, armedRow)
+	for _, key := range []string{"groups", "groups_updated_at", "subject_rebind_armed_at"} {
+		require.Contains(t, armedRow, key, "GET /admin/users must carry %q", key)
+	}
+	var groups []string
+	require.NoError(t, json.Unmarshal(armedRow["groups"], &groups))
+	assert.Equal(t, []string{"eng", "ops"}, groups)
+	var groupsUpdatedAt, rebindArmedAtWire string
+	require.NoError(t, json.Unmarshal(armedRow["groups_updated_at"], &groupsUpdatedAt))
+	require.NoError(t, json.Unmarshal(armedRow["subject_rebind_armed_at"], &rebindArmedAtWire))
+	parsedGroupsAt, err := time.Parse(time.RFC3339, groupsUpdatedAt)
+	require.NoError(t, err, "groups_updated_at is RFC 3339: %q", groupsUpdatedAt)
+	assert.True(t, parsedGroupsAt.Equal(groupsAt))
+	parsedArmedAt, err := time.Parse(time.RFC3339, rebindArmedAtWire)
+	require.NoError(t, err, "subject_rebind_armed_at is RFC 3339: %q", rebindArmedAtWire)
+	assert.True(t, parsedArmedAt.Equal(armedAt))
+
+	plainRow := byID["user-plain"]
+	require.NotNil(t, plainRow)
+	for _, key := range []string{"groups", "groups_updated_at", "subject_rebind_armed_at"} {
+		require.Contains(t, plainRow, key, "the keys are present on every row, never dropped for zero values")
+	}
+	var plainGroups []string
+	require.NoError(t, json.Unmarshal(plainRow["groups"], &plainGroups))
+	assert.NotNil(t, plainGroups, "groups is always an array (`string[]`), never null")
+	assert.Empty(t, plainGroups)
+	assert.Equal(t, "null", string(plainRow["groups_updated_at"]), "zero groups_updated_at is null on the wire")
+	assert.Equal(t, "null", string(plainRow["subject_rebind_armed_at"]), "a closed window is null on the wire")
+}
diff --git a/internal/serveredition/api/auth_endpoints.go b/internal/serveredition/api/auth_endpoints.go
index 055c981d2..306885e61 100644
--- a/internal/serveredition/api/auth_endpoints.go
+++ b/internal/serveredition/api/auth_endpoints.go
@@ -53,15 +53,52 @@ func (h *AuthEndpoints) RegisterRoutesWithPrefix(r chi.Router, prefix string) {
 	r.Post(prefix+"/auth/token", h.generateToken)
 }
 
+// RegisterPublicRoutesWithPrefix registers the routes that need NO
+// authentication: the edition probe GET {prefix}/auth/provider (Spec 107
+// FR-030). Setup mounts it beside login/callback, outside every auth group,
+// and only on an enabled block — a disabled block registers nothing, so 404
+// falls out of chi exactly as on the personal build.
+func (h *AuthEndpoints) RegisterPublicRoutesWithPrefix(r chi.Router, prefix string) {
+	r.Get(prefix+"/auth/provider", h.getProvider)
+}
+
+// ProviderProbeResponse is the whole body of GET /api/v1/auth/provider
+// (contracts/rest-endpoints.md §1): an operator-chosen label and nothing else.
+type ProviderProbeResponse struct {
+	DisplayName string `json:"display_name"`
+}
+
+// getProvider answers the public edition probe: no authentication, no side
+// effects (no pending login state), only {display_name} — oauth.display_name,
+// falling back to the provider family name. It never returns the issuer,
+// client id, tenant id, scopes, domains or provider family.
+func (h *AuthEndpoints) getProvider(w http.ResponseWriter, _ *http.Request) {
+	label := ""
+	if h.teamsConfig != nil && h.teamsConfig.OAuth != nil {
+		label = h.teamsConfig.OAuth.DisplayName
+		if label == "" {
+			label = h.teamsConfig.OAuth.Provider
+		}
+	}
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Cache-Control", "no-store")
+	writeJSON(w, http.StatusOK, ProviderProbeResponse{DisplayName: label})
+}
+
 // --- Response types ---
 
 // MeResponse represents the current user's profile.
+//
+// Spec 107 FR-008 (contracts/rest-endpoints.md §2): groups is the caller's
+// own stored groups ([] when none), groups_updated_at RFC 3339 or null.
 type MeResponse struct {
-	ID          string `json:"id"`
-	Email       string `json:"email"`
-	DisplayName string `json:"display_name"`
-	Role        string `json:"role"`
-	Provider    string `json:"provider"`
+	ID              string   `json:"id"`
+	Email           string   `json:"email"`
+	DisplayName     string   `json:"display_name"`
+	Role            string   `json:"role"`
+	Provider        string   `json:"provider"`
+	Groups          []string `json:"groups"`
+	GroupsUpdatedAt *string  `json:"groups_updated_at"`
 }
 
 // TokenResponse contains a generated bearer token.
@@ -93,12 +130,18 @@ func (h *AuthEndpoints) getMe(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	groups := user.Groups
+	if groups == nil {
+		groups = []string{}
+	}
 	writeJSON(w, http.StatusOK, MeResponse{
-		ID:          user.ID,
-		Email:       user.Email,
-		DisplayName: user.DisplayName,
-		Role:        ac.Role,
-		Provider:    user.Provider,
+		ID:              user.ID,
+		Email:           user.Email,
+		DisplayName:     user.DisplayName,
+		Role:            ac.Role,
+		Provider:        user.Provider,
+		Groups:          groups,
+		GroupsUpdatedAt: rfc3339OrNil(user.GroupsUpdatedAt),
 	})
 }
 
diff --git a/internal/serveredition/api/auth_provider_probe_test.go b/internal/serveredition/api/auth_provider_probe_test.go
new file mode 100644
index 000000000..be2ffae24
--- /dev/null
+++ b/internal/serveredition/api/auth_provider_probe_test.go
@@ -0,0 +1,255 @@
+//go:build server
+
+package api_test
+
+// Spec 107 T049 (US2, FR-030): the public edition probe `GET /api/v1/auth/provider`.
+//
+// contracts/rest-endpoints.md §1: no authentication, no side effects (allocates
+// no pending login state), returns ONLY `{display_name}` — an operator-chosen
+// label, falling back to the provider family name — and never the issuer,
+// client id, tenant id, scopes, domains or provider family. It is registered
+// by SetupAll only on an enabled block (T053 mounts it beside login/callback,
+// outside every auth group), so a disabled block registers nothing and 404
+// falls out of chi.
+//
+// Compile-red until T053 adds AuthEndpoints.RegisterPublicRoutesWithPrefix
+// (the public sibling of RegisterRoutesWithPrefix, auth_endpoints.go:51);
+// the SetupAll-driven cases are behaviour-red on the PR-B base (404 today).
+//
+// External test package: the wiring cases need serveredition.SetupAll, which
+// imports this package.
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.etcd.io/bbolt"
+	"go.uber.org/zap"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/serveredition"
+	teamsapi "github.com/smart-mcp-proxy/mcpproxy-go/internal/serveredition/api"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/storage"
+)
+
+const providerProbePath = "/api/v1/auth/provider"
+
+// forbiddenProbeValues are the configured secrets and identifiers the probe
+// must never disclose; every fixture below plants them so a leak is caught by
+// a substring check on the raw body.
+var forbiddenProbeValues = []string{
+	"https://idp.example.test",  // issuer_url
+	"probe-client-id",           // client_id
+	"probe-client-secret",       // client_secret
+	"11111111-2222-3333-4444",   // tenant_id
+	"probe-scope-secret",        // scopes
+	"probe-domain.example.test", // allowed_domains
+	"probe-groups-claim",        // groups_claim
+}
+
+func probeOAuthBlock(provider, displayName string) *config.ServerEditionOAuthConfig {
+	return &config.ServerEditionOAuthConfig{
+		Provider:       provider,
+		ClientID:       "probe-client-id",
+		ClientSecret:   "probe-client-secret",
+		TenantID:       "11111111-2222-3333-4444",
+		AllowedDomains: []string{"probe-domain.example.test"},
+		IssuerURL:      "https://idp.example.test",
+		Scopes:         []string{"openid", "probe-scope-secret"},
+		GroupsClaim:    "probe-groups-claim",
+		DisplayName:    displayName,
+	}
+}
+
+func probeBlock(enabled bool, oauth *config.ServerEditionOAuthConfig) *config.ServerEditionConfig {
+	return &config.ServerEditionConfig{
+		Enabled:        enabled,
+		AdminEmails:    []string{"admin@example.com"},
+		SessionTTL:     config.Duration(24 * time.Hour),
+		BearerTokenTTL: config.Duration(24 * time.Hour),
+		OAuth:          oauth,
+	}
+}
+
+func probeGet(t *testing.T, h http.Handler) *httptest.ResponseRecorder {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, providerProbePath, http.NoBody)
+	req.Host = "localhost:8080"
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	return rec
+}
+
+// assertProbeBody checks the exact contract shape: 200, JSON, exactly one key
+// `display_name` with the expected value, no cookies, no redirect, no leak.
+func assertProbeBody(t *testing.T, rec *httptest.ResponseRecorder, wantDisplayName string) {
+	t.Helper()
+	require.Equal(t, http.StatusOK, rec.Code, "body=%s", rec.Body.String())
+	assert.Contains(t, rec.Header().Get("Content-Type"), "application/json")
+	assert.Empty(t, rec.Header().Values("Set-Cookie"), "the probe must not start a session")
+	assert.Empty(t, rec.Header().Get("Location"), "the probe must not redirect to the IdP")
+
+	var body map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body), "body=%s", rec.Body.String())
+	require.Len(t, body, 1, "only {display_name}: %s", rec.Body.String())
+	got, ok := body["display_name"].(string)
+	require.True(t, ok, "display_name must be a string: %s", rec.Body.String())
+	assert.True(t, strings.EqualFold(wantDisplayName, got), "display_name: want %q (case-insensitive), got %q", wantDisplayName, got)
+	assert.LessOrEqual(t, len(got), 64)
+
+	for _, secret := range forbiddenProbeValues {
+		assert.NotContains(t, rec.Body.String(), secret, "the probe leaked a configured value")
+	}
+}
+
+// TestAuthProviderProbe_DisplayName drives the handler directly. The
+// collaborators are nil on purpose: the probe reads only the boot block, so a
+// nil user store, session manager and HMAC key must not matter — which is
+// also the structural guarantee that it cannot touch the OAuth handler's
+// pendingStates (that map lives in package auth and has no exported reader).
+func TestAuthProviderProbe_DisplayName(t *testing.T) {
+	cases := []struct {
+		name        string
+		provider    string
+		displayName string
+		want        string
+	}{
+		{"oidc with display_name", "oidc", "Acme SSO", "Acme SSO"},
+		{"oidc falls back to the family name", "oidc", "", "oidc"},
+		{"google falls back to the family name", "google", "", "google"},
+		{"github falls back to the family name", "github", "", "github"},
+		{"microsoft falls back to the family name", "microsoft", "", "microsoft"},
+		{"legacy provider honours display_name", "google", "Sign in with Corp Google", "Sign in with Corp Google"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			block := probeBlock(true, probeOAuthBlock(tc.provider, tc.displayName))
+			block.ApplyDefaults()
+			require.NoError(t, block.Validate())
+
+			endpoints := teamsapi.NewAuthEndpoints(nil, nil, block, nil, zap.NewNop().Sugar())
+			router := chi.NewRouter()
+			endpoints.RegisterPublicRoutesWithPrefix(router, "/api/v1")
+
+			first := probeGet(t, router)
+			assertProbeBody(t, first, tc.want)
+
+			// Side-effect free: repeated calls are identical and nothing is
+			// allocated per call (a probe that delegated to HandleLogin would
+			// 302 and grow pendingStates).
+			for i := 0; i < 50; i++ {
+				again := probeGet(t, router)
+				require.Equal(t, first.Body.String(), again.Body.String())
+			}
+		})
+	}
+}
+
+// TestAuthProviderProbe_NoAuthenticationRequired: the route is public — an
+// unrelated bearer, a wrong API key or a stale session cookie change nothing.
+func TestAuthProviderProbe_NoAuthenticationRequired(t *testing.T) {
+	block := probeBlock(true, probeOAuthBlock("oidc", "Acme SSO"))
+	block.ApplyDefaults()
+	endpoints := teamsapi.NewAuthEndpoints(nil, nil, block, nil, zap.NewNop().Sugar())
+	router := chi.NewRouter()
+	endpoints.RegisterPublicRoutesWithPrefix(router, "/api/v1")
+
+	shapes := map[string]func(*http.Request){
+		"stale cookie":   func(r *http.Request) { r.AddCookie(&http.Cookie{Name: "mcpproxy_session", Value: "stale"}) },
+		"unknown bearer": func(r *http.Request) { r.Header.Set("Authorization", "Bearer not-a-credential") },
+		"wrong api key":  func(r *http.Request) { r.Header.Set("X-API-Key", "wrong") },
+	}
+	for name, shape := range shapes {
+		req := httptest.NewRequest(http.MethodGet, providerProbePath, http.NoBody)
+		shape(req)
+		rec := httptest.NewRecorder()
+		router.ServeHTTP(rec, req)
+		assert.Equal(t, http.StatusOK, rec.Code, name)
+		assert.JSONEq(t, `{"display_name":"Acme SSO"}`, rec.Body.String(), name)
+	}
+}
+
+// probeSetup drives the production wiring (serveredition.SetupAll) with the
+// given block on a bare chi router and returns the router plus SetupAll's
+// error.
+func probeSetup(t *testing.T, block *config.ServerEditionConfig) (chi.Router, error) {
+	t.Helper()
+	tmpDir := t.TempDir()
+	db, err := bbolt.Open(tmpDir+"/probe.db", 0o600, &bbolt.Options{Timeout: time.Second})
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = db.Close() })
+
+	logger := zap.NewNop().Sugar()
+	tokens, err := storage.NewManager(t.TempDir(), logger)
+	require.NoError(t, err)
+	t.Cleanup(func() { tokens.Close() })
+
+	cfg := &config.Config{DataDir: tmpDir, ServerEdition: block}
+	router := chi.NewRouter()
+	setupErr := serveredition.SetupAll(serveredition.Dependencies{
+		Router:         router,
+		DB:             db,
+		Logger:         logger,
+		DataDir:        tmpDir,
+		Config:         cfg,
+		ConfigProvider: func() *config.Config { return cfg },
+		StorageManager: tokens,
+	})
+	return router, setupErr
+}
+
+// TestAuthProviderProbe_WiredBySetupAll: the production setup mounts the probe
+// beside login/callback, outside the session/JWT auth group.
+func TestAuthProviderProbe_WiredBySetupAll(t *testing.T) {
+	router, err := probeSetup(t, probeBlock(true, probeOAuthBlock("oidc", "Acme SSO")))
+	require.NoError(t, err)
+
+	assertProbeBody(t, probeGet(t, router), "Acme SSO")
+
+	// The authenticated sibling on the same router still refuses an
+	// unauthenticated caller — the probe is public by its own registration,
+	// not because the auth group was weakened.
+	me := httptest.NewRecorder()
+	router.ServeHTTP(me, httptest.NewRequest(http.MethodGet, "/api/v1/auth/me", http.NoBody))
+	assert.Equal(t, http.StatusUnauthorized, me.Code)
+}
+
+// TestAuthProviderProbe_404WhenDisabledOrOAuthAbsent: a disabled block registers
+// nothing (SetupAll returns early), and an enabled block without `oauth` fails
+// validation before any route is mounted, so both answer like the personal
+// build. NOTE: on a bare chi router the answer is 404. In the production
+// router the probe path also sits under the `/api/v1` mount whose
+// apiKeyAuthMiddleware runs before that sub-mux's 404
+// (internal/httpapi/server.go:751-756), so an unauthenticated caller of an
+// unregistered probe receives 401 there — see
+// internal/httpapi/auth_provider_probe_personal_test.go.
+func TestAuthProviderProbe_404WhenDisabledOrOAuthAbsent(t *testing.T) {
+	t.Run("server_edition.enabled false", func(t *testing.T) {
+		router, err := probeSetup(t, probeBlock(false, probeOAuthBlock("oidc", "Acme SSO")))
+		require.NoError(t, err)
+		rec := probeGet(t, router)
+		assert.Equal(t, http.StatusNotFound, rec.Code)
+		assert.NotContains(t, rec.Body.String(), "display_name")
+	})
+
+	t.Run("oauth block absent", func(t *testing.T) {
+		router, err := probeSetup(t, probeBlock(true, nil))
+		require.Error(t, err, "an enabled block without oauth must not set up")
+		rec := probeGet(t, router)
+		assert.Equal(t, http.StatusNotFound, rec.Code)
+		assert.NotContains(t, rec.Body.String(), "display_name")
+	})
+
+	t.Run("server_edition block absent", func(t *testing.T) {
+		router, err := probeSetup(t, nil)
+		require.NoError(t, err)
+		assert.Equal(t, http.StatusNotFound, probeGet(t, router).Code)
+	})
+}
diff --git a/internal/serveredition/api/connector_provider.go b/internal/serveredition/api/connector_provider.go
index e5b075bc3..314152533 100644
--- a/internal/serveredition/api/connector_provider.go
+++ b/internal/serveredition/api/connector_provider.go
@@ -16,6 +16,16 @@ import (
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/serveredition/broker"
 )
 
+// connectorCacheCap bounds the number of distinct (server, base URL)
+// connectors held at once. With public_url unset, base comes from r.Host —
+// caller-controlled on every direct HTTP/1.1 request, trusted-proxy or not —
+// so without a cap a caller could mint one permanently-cached OAuthConnector
+// (plus its in-memory PKCE/state map) per distinct Host header value, an
+// unbounded memory-growth DoS (cross-review round 7, chunk 3 P2). A single
+// deployment normally resolves to one or a handful of origins, so this is
+// generous headroom, not a tight budget.
+const connectorCacheCap = 256
+
 // connectorProvider builds and caches one broker.OAuthConnector per
 // oauth_connect upstream (keyed by serverKey). The same connector instance must
 // serve both the connect redirect and the callback because the connector holds
@@ -26,9 +36,18 @@ type connectorProvider struct {
 	logger *zap.Logger
 	audit  broker.AuditSink // connect-flow audit sink (spec 074 T10); nil = no-op
 
-	mu      sync.Mutex
-	baseURL string // gateway public origin, e.g. "https://gw.example.com"
-	cache   map[string]*broker.OAuthConnector
+	// publicURL is server_edition.public_url (restart-pinned): when set it is
+	// the sole source of the gateway origin (Spec 107 FR-025).
+	publicURL string
+	// trustedProxies yields the LIVE trusted_proxies list (FR-027); nil
+	// trusts nobody.
+	trustedProxies config.TrustedProxiesProvider
+
+	mu    sync.Mutex
+	cache map[string]*broker.OAuthConnector // keyed by serverKey + "|" + base URL
+	// order is cache's insertion order, oldest first; it bounds cache at
+	// connectorCacheCap entries by evicting the oldest on overflow.
+	order []string
 }
 
 // newConnectorProvider constructs an empty provider. A nil audit sink disables
@@ -45,23 +64,39 @@ func newConnectorProvider(store broker.CredentialStore, logger *zap.Logger, audi
 	}
 }
 
-// observeBaseURL records the gateway's public origin the first time it is seen
-// (from an incoming request). The connect callback URL registered with the
-// upstream authorization server is derived from it, and OAuth requires the
-// redirect_uri to be byte-identical between the authorize request and the token
-// exchange — so it is fixed once and reused for the lifetime of a connector.
-func (p *connectorProvider) observeBaseURL(r *http.Request) {
-	base := baseURLFromRequest(r)
+// setFrontDoor installs the public_url and the live trusted-proxy provider.
+func (p *connectorProvider) setFrontDoor(publicURL string, trusted config.TrustedProxiesProvider) {
 	p.mu.Lock()
 	defer p.mu.Unlock()
-	if p.baseURL == "" {
-		p.baseURL = base
+	p.publicURL = strings.TrimSuffix(publicURL, "/")
+	p.trustedProxies = trusted
+}
+
+// baseURL resolves the gateway's public origin for one request: public_url
+// when set, otherwise the scheme and host a trusted proxy forwarded, otherwise
+// the listener's own scheme and Host. There is NO first-seen latch (Spec 107
+// FR-025): the origin is resolved per request, and the connector cache is
+// keyed by it, so the connect redirect and its callback — shaped identically
+// by the same ingress — share one connector while a hostile first request
+// cannot poison every later one.
+func (p *connectorProvider) baseURL(r *http.Request) string {
+	p.mu.Lock()
+	publicURL, trusted := p.publicURL, p.trustedProxies
+	p.mu.Unlock()
+	if publicURL != "" {
+		return publicURL
+	}
+	var list []string
+	if trusted != nil {
+		list = trusted()
 	}
+	fwd := config.ForwardedHeaders(r, list)
+	return fwd.Scheme + "://" + fwd.Host
 }
 
 // connector returns the cached connector for an oauth_connect upstream, building
 // it on first use. It errors for non-oauth_connect or unbrokered servers.
-func (p *connectorProvider) connector(server *config.ServerConfig) (*broker.OAuthConnector, error) {
+func (p *connectorProvider) connector(r *http.Request, server *config.ServerConfig) (*broker.OAuthConnector, error) {
 	if server == nil || server.AuthBroker == nil {
 		return nil, fmt.Errorf("connector provider: server has no auth_broker configuration")
 	}
@@ -69,7 +104,8 @@ func (p *connectorProvider) connector(server *config.ServerConfig) (*broker.OAut
 		return nil, fmt.Errorf("connector provider: server %q is not an oauth_connect upstream", server.Name)
 	}
 
-	key := oauth.GenerateServerKey(server.Name, server.URL)
+	base := p.baseURL(r)
+	key := oauth.GenerateServerKey(server.Name, server.URL) + "|" + base
 
 	p.mu.Lock()
 	defer p.mu.Unlock()
@@ -86,21 +122,41 @@ func (p *connectorProvider) connector(server *config.ServerConfig) (*broker.OAut
 		ClientID:              ab.ClientID,
 		ClientSecret:          ab.ClientSecret,
 		Scopes:                ab.Scopes,
-		RedirectURI:           p.callbackURLLocked(server.Name),
+		RedirectURI:           base + connectCallbackPath(server.Name),
 		Resource:              ab.Resource,
 	}
 	conn, err := broker.NewOAuthConnector(p.store, cfg, p.logger, p.audit)
 	if err != nil {
 		return nil, err
 	}
+	if len(p.order) >= connectorCacheCap {
+		p.evictOneLocked()
+	}
 	p.cache[key] = conn
+	p.order = append(p.order, key)
 	return conn, nil
 }
 
-// callbackURLLocked builds the gateway callback URL for a server. Caller holds p.mu.
-func (p *connectorProvider) callbackURLLocked(serverName string) string {
-	base := strings.TrimSuffix(p.baseURL, "/")
-	return base + connectCallbackPath(serverName)
+// evictOneLocked drops one entry to make room for a new one. It prefers the
+// oldest connector with no in-flight connect flow over strict insertion
+// order: a pure FIFO could evict a connector whose user is mid-flow (between
+// the /connect redirect and their /callback), turning a caller varying its
+// own Host header into a cross-user denial-of-service against a real,
+// in-progress login rather than just bounding memory (cross-review round 8,
+// chunk 3 P2). Caller holds p.mu. If every cached connector has a pending
+// flow (impossible in practice at connectorCacheCap, but never a reason to
+// grow unbounded), the oldest is evicted anyway — the cap is never violated.
+func (p *connectorProvider) evictOneLocked() {
+	victim := 0
+	for i, key := range p.order {
+		if !p.cache[key].HasPendingFlow() {
+			victim = i
+			break
+		}
+	}
+	key := p.order[victim]
+	p.order = append(p.order[:victim], p.order[victim+1:]...)
+	delete(p.cache, key)
 }
 
 // connectCallbackPath is the relative callback route for a server's connect flow.
@@ -112,17 +168,3 @@ func connectCallbackPath(serverName string) string {
 func connectInitiatePath(serverName string) string {
 	return "/api/v1/user/credentials/" + url.PathEscape(serverName) + "/connect"
 }
-
-// baseURLFromRequest derives the gateway's public origin (scheme://host),
-// honoring X-Forwarded-Proto for reverse-proxy deployments. Mirrors the OAuth
-// login handler's buildCallbackURL scheme detection.
-func baseURLFromRequest(r *http.Request) string {
-	scheme := "http"
-	if r.TLS != nil {
-		scheme = "https"
-	}
-	if proto := r.Header.Get("X-Forwarded-Proto"); proto != "" {
-		scheme = proto
-	}
-	return scheme + "://" + r.Host
-}
diff --git a/internal/serveredition/api/connector_provider_test.go b/internal/serveredition/api/connector_provider_test.go
new file mode 100644
index 000000000..bea80df0e
--- /dev/null
+++ b/internal/serveredition/api/connector_provider_test.go
@@ -0,0 +1,130 @@
+//go:build server
+
+package api
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+)
+
+func connectTestServer(name string) *config.ServerConfig {
+	return &config.ServerConfig{
+		Name: name,
+		URL:  "https://upstream.example/" + name,
+		AuthBroker: &config.AuthBrokerConfig{
+			Mode:                  config.AuthBrokerModeOAuthConnect,
+			TokenEndpoint:         "https://idp.example/token",
+			AuthorizationEndpoint: "https://idp.example/authorize",
+			ClientID:              "client-id",
+			ClientSecret:          "client-secret",
+		},
+	}
+}
+
+// With public_url unset, base comes from r.Host — caller-controlled on every
+// direct request. Without a bound, a caller varying its own Host header could
+// grow the connector cache (and its in-memory PKCE/state) without limit
+// (cross-review round 7, chunk 3 P2). The cache must stay bounded, evicting
+// the oldest entry rather than growing forever.
+func TestConnectorProvider_CacheIsBounded(t *testing.T) {
+	store := credTestStore(t)
+	p := newConnectorProvider(store, nil, nil)
+	server := connectTestServer("s")
+
+	for i := 0; i < connectorCacheCap+10; i++ {
+		r := httptest.NewRequest(http.MethodGet, "/api/v1/user/credentials/s/connect", nil)
+		r.Host = fmt.Sprintf("host-%d.attacker.example", i)
+		_, err := p.connector(r, server)
+		require.NoError(t, err)
+	}
+
+	p.mu.Lock()
+	size := len(p.cache)
+	orderLen := len(p.order)
+	p.mu.Unlock()
+
+	assert.LessOrEqual(t, size, connectorCacheCap, "cache must never exceed its cap")
+	assert.Equal(t, size, orderLen, "cache and its eviction order must stay in sync")
+}
+
+// The most recently used bases must survive eviction: a caller cycling
+// through more distinct Host values than the cap must not evict the base it
+// is actively using between its /connect and its /callback.
+func TestConnectorProvider_CacheKeepsRecentEntries(t *testing.T) {
+	store := credTestStore(t)
+	p := newConnectorProvider(store, nil, nil)
+	server := connectTestServer("s")
+
+	last := fmt.Sprintf("host-%d.example", connectorCacheCap+9)
+	for i := 0; i < connectorCacheCap+10; i++ {
+		r := httptest.NewRequest(http.MethodGet, "/api/v1/user/credentials/s/connect", nil)
+		r.Host = fmt.Sprintf("host-%d.example", i)
+		_, err := p.connector(r, server)
+		require.NoError(t, err)
+	}
+
+	r := httptest.NewRequest(http.MethodGet, "/api/v1/user/credentials/s/connect", nil)
+	r.Host = last
+	conn1, err := p.connector(r, server)
+	require.NoError(t, err)
+
+	conn2, err := p.connector(r, server)
+	require.NoError(t, err)
+	assert.Same(t, conn1, conn2, "the just-used base's connector is still cached, not rebuilt")
+}
+
+// A connector holding an in-flight connect flow (BuildAuthorizationURL called,
+// callback not yet received) must survive eviction even when it is the
+// oldest entry: a caller varying its own Host header must not be able to
+// evict another user's pending login and turn their upcoming callback into a
+// spurious invalid-state failure (cross-review round 8, chunk 3 P2).
+func TestConnectorProvider_EvictionSparesPendingFlow(t *testing.T) {
+	store := credTestStore(t)
+	p := newConnectorProvider(store, nil, nil)
+	server := connectTestServer("s")
+
+	// First entry (oldest by insertion order) starts a pending flow.
+	r0 := httptest.NewRequest(http.MethodGet, "/api/v1/user/credentials/s/connect", nil)
+	r0.Host = "host-0.example"
+	conn0, err := p.connector(r0, server)
+	require.NoError(t, err)
+	_, _, err = conn0.BuildAuthorizationURL("alice")
+	require.NoError(t, err)
+
+	// Fill the cache to its cap with distinct, flow-free hosts.
+	for i := 1; i < connectorCacheCap; i++ {
+		r := httptest.NewRequest(http.MethodGet, "/api/v1/user/credentials/s/connect", nil)
+		r.Host = fmt.Sprintf("host-%d.example", i)
+		_, err := p.connector(r, server)
+		require.NoError(t, err)
+	}
+
+	// One more distinct host forces an eviction: host-0 (pending) must be
+	// spared in favour of the oldest flow-free entry (host-1).
+	rNew := httptest.NewRequest(http.MethodGet, "/api/v1/user/credentials/s/connect", nil)
+	rNew.Host = "host-new.example"
+	_, err = p.connector(rNew, server)
+	require.NoError(t, err)
+
+	p.mu.Lock()
+	_, host0Cached := p.cache[fmt.Sprintf("%s|http://host-0.example", conn0.ServerKey())]
+	_, host1Cached := p.cache[fmt.Sprintf("%s|http://host-1.example", conn0.ServerKey())]
+	size := len(p.cache)
+	p.mu.Unlock()
+
+	assert.True(t, host0Cached, "the connector with a pending flow must not be evicted")
+	assert.False(t, host1Cached, "an idle connector is evicted in its place")
+	assert.Equal(t, connectorCacheCap, size, "the cap is still enforced")
+
+	// The pending flow is still resolvable against the surviving connector.
+	conn0Again, err := p.connector(r0, server)
+	require.NoError(t, err)
+	assert.Same(t, conn0, conn0Again)
+}
diff --git a/internal/serveredition/api/credential_handlers.go b/internal/serveredition/api/credential_handlers.go
index fe6da58d2..fb34867be 100644
--- a/internal/serveredition/api/credential_handlers.go
+++ b/internal/serveredition/api/credential_handlers.go
@@ -64,6 +64,12 @@ func (h *CredentialHandlers) SetAdminServersProvider(provider AdminServersProvid
 	h.adminServers = provider
 }
 
+// SetFrontDoor installs server_edition.public_url and the live trusted-proxy
+// provider the connect flow's base URL is resolved from (Spec 107 FR-025/027).
+func (h *CredentialHandlers) SetFrontDoor(publicURL string, trusted config.TrustedProxiesProvider) {
+	h.connectors.setFrontDoor(publicURL, trusted)
+}
+
 func (h *CredentialHandlers) currentAdminServers() []*config.ServerConfig {
 	if h.adminServers != nil {
 		return h.adminServers()
@@ -234,8 +240,7 @@ func (h *CredentialHandlers) connect(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	h.connectors.observeBaseURL(r)
-	conn, err := h.connectors.connector(srv)
+	conn, err := h.connectors.connector(r, srv)
 	if err != nil {
 		h.logger.Errorw("failed to build connector", "user_id", userID, "server", srv.Name, "error", err)
 		writeError(w, http.StatusInternalServerError, "Failed to initiate connect flow")
@@ -272,7 +277,7 @@ func (h *CredentialHandlers) callback(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	conn, err := h.connectors.connector(srv)
+	conn, err := h.connectors.connector(r, srv)
 	if err != nil {
 		h.logger.Errorw("failed to resolve connector for callback", "server", srv.Name, "error", err)
 		writeError(w, http.StatusInternalServerError, "Failed to complete connect flow")
diff --git a/internal/serveredition/auth/front_door_test.go b/internal/serveredition/auth/front_door_test.go
new file mode 100644
index 000000000..496b61e5c
--- /dev/null
+++ b/internal/serveredition/auth/front_door_test.go
@@ -0,0 +1,164 @@
+//go:build server
+
+package auth
+
+// Spec 107 T048 (PR-B, Phase B.3) — the handler-level half of the front door:
+// the post-login `redirect_uri` matrix of FR-028 / US2.7 driven through the
+// production HandleLogin → fake IdP → HandleCallback path.
+//
+// Every row of the matrix is asserted at THREE points, because each one can
+// regress on its own:
+//
+//  1. `RedirectRejected` on the pending state HandleLogin stores (the flag is
+//     decided at login time, before the IdP is ever contacted);
+//  2. the browser lands on `/ui/` (rejected) or on the requested path
+//     (honoured) after the callback;
+//  3. the terminal LoginResult carries `redirect_rejected` in Flags exactly
+//     when the value was replaced (FR-017 — the flag rides on the attempt's
+//     auth_event line in PR-D, never on the page).
+//
+// The percent-encoded forms exist because `r.URL.Query().Get` percent-decodes
+// before the sanitiser runs, so `/%5Cevil.example` reaches it as `/\evil.example`
+// and `/ok%0D%0ASet-Cookie:x` as a CRLF injection; the literal tab and CRLF
+// rows cannot be sent through a Go HTTP server (the request line is refused
+// with 400 before any handler runs), so they are delivered as raw query bytes
+// on the request object — exactly what a non-Go ingress that forwards the
+// request target verbatim would hand the handler.
+//
+// The harness-level half (public_url, Secure cookie, trusted proxies, the
+// scheme-disagreement warning) lives in internal/serveredition/front_door_test.go
+// because the wiring harness of T046 is in that package.
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/tests/oauthserver"
+)
+
+// redirectMatrixRow is one FR-028 fixture: the raw query value as the request
+// target carries it, whether the sanitiser must replace it, and where the
+// browser must land after the callback.
+type redirectMatrixRow struct {
+	name       string
+	rawQuery   string // bytes placed after `redirect_uri=` in the raw query
+	rejected   bool
+	wantTarget string
+}
+
+// redirectMatrix is the US2.7 + FR-028 matrix from tasks.md T048. The
+// `wantTarget` of an honoured row is the value the sanitiser admits (a
+// same-origin path, query kept); every rejected row lands on /ui/.
+var redirectMatrix = []redirectMatrixRow{
+	{name: "absolute https origin", rawQuery: "https://evil.example/", rejected: true, wantTarget: "/ui/"},
+	{name: "protocol-relative", rawQuery: "//evil.example", rejected: true, wantTarget: "/ui/"},
+	{name: "backslash after slash", rawQuery: `/\evil.example`, rejected: true, wantTarget: "/ui/"},
+	{name: "javascript scheme", rawQuery: "javascript:alert(1)", rejected: true, wantTarget: "/ui/"},
+	{name: "encoded CRLF header injection", rawQuery: "/ok%0D%0ASet-Cookie:x", rejected: true, wantTarget: "/ui/"},
+	{name: "encoded NUL", rawQuery: "/ok%00", rejected: true, wantTarget: "/ui/"},
+	{name: "encoded backslash", rawQuery: "/%5Cevil.example", rejected: true, wantTarget: "/ui/"},
+	{name: "encoded double slash", rawQuery: "/%2F%2Fevil.example", rejected: true, wantTarget: "/ui/"},
+	{name: "literal tab", rawQuery: "/ok\t", rejected: true, wantTarget: "/ui/"},
+	{name: "literal CRLF", rawQuery: "/ok\r\n", rejected: true, wantTarget: "/ui/"},
+	{name: "same-origin path with query", rawQuery: "/my/tokens?x=1", rejected: false, wantTarget: "/my/tokens?x=1"},
+	{name: "same-origin path with encoded query", rawQuery: "/my/tokens%3Fx%3D1", rejected: false, wantTarget: "/my/tokens?x=1"},
+	{name: "root", rawQuery: "/", rejected: false, wantTarget: "/"},
+	{name: "empty falls back to /ui/ without a flag", rawQuery: "", rejected: false, wantTarget: "/ui/"},
+}
+
+// loginWithRawRedirect calls HandleLogin with the raw query bytes and returns
+// the authorization URL the handler redirected to and the state it minted.
+func (r *refusalRig) loginWithRawRedirect(rid, rawQuery string) (*url.URL, string) {
+	r.t.Helper()
+	req := withRequestID(httptest.NewRequest(http.MethodGet, "http://"+refusalHost+"/api/v1/auth/login", nil), rid)
+	req.URL.RawQuery = "redirect_uri=" + rawQuery
+	w := httptest.NewRecorder()
+	r.handler.HandleLogin(w, req)
+	require.Equal(r.t, http.StatusFound, w.Code, "login must redirect to the IdP; body=%s", w.Body.String())
+	loc, err := url.Parse(w.Header().Get("Location"))
+	require.NoError(r.t, err)
+	state := loc.Query().Get("state")
+	require.NotEmpty(r.t, state, "the authorization URL must carry the pending state")
+	return loc, state
+}
+
+// pendingRedirectRejected reads the RedirectRejected flag of a pending state.
+func (r *refusalRig) pendingRedirectRejected(state string) (rejected bool, stored string) {
+	r.handler.statesMu.Lock()
+	defer r.handler.statesMu.Unlock()
+	pending, ok := r.handler.pendingStates[state]
+	require.True(r.t, ok, "state %q must be pending after login", state)
+	return pending.RedirectRejected, pending.RedirectURI
+}
+
+// TestFrontDoor_RedirectURIMatrix drives every FR-028 row end to end.
+func TestFrontDoor_RedirectURIMatrix(t *testing.T) {
+	for _, row := range redirectMatrix {
+		t.Run(row.name, func(t *testing.T) {
+			rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+			rid := "rid-" + row.name
+
+			authURL, state := rig.loginWithRawRedirect(rid, row.rawQuery)
+
+			// 1. Decided at login, carried on the pending state.
+			rejected, stored := rig.pendingRedirectRejected(state)
+			assert.Equal(t, row.rejected, rejected, "RedirectRejected on the pending state for %q", row.rawQuery)
+			assert.Equal(t, row.wantTarget, stored, "the pending state stores the value the callback will redirect to")
+
+			// The rejected value never reaches the IdP either: the authorization
+			// URL carries no trace of it.
+			assert.NotContains(t, authURL.String(), "evil.example")
+			assert.NotContains(t, authURL.String(), "javascript")
+
+			// 2. The browser lands where the sanitiser decided.
+			cb := rig.authorizeForm(authURL, "approve")
+			w := rig.callback(rid, cb.String())
+			require.Equal(t, http.StatusFound, w.Code, "login must succeed; body=%s", w.Body.String())
+			assert.Equal(t, row.wantTarget, w.Header().Get("Location"))
+
+			// 3. The terminal result carries the flag exactly when replaced.
+			res := rig.results.exactlyOne(t)
+			assert.Equal(t, LoginOK, res.Reason)
+			assert.Equal(t, rid, res.RequestID)
+			if row.rejected {
+				assert.Contains(t, flagsOf(res), string(FlagRedirectRejected))
+			} else {
+				assert.NotContains(t, flagsOf(res), string(FlagRedirectRejected))
+			}
+		})
+	}
+}
+
+// TestFrontDoor_RejectedRedirectIsNeverEchoed: the replacement is silent —
+// no error status, no reflection of the offending value on the login redirect
+// or on the callback response (FR-028: "never an error, never echoed").
+func TestFrontDoor_RejectedRedirectIsNeverEchoed(t *testing.T) {
+	rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+	const rid = "rid-echo"
+	const evil = "https://evil.example/pwn"
+
+	req := withRequestID(httptest.NewRequest(http.MethodGet, "http://"+refusalHost+"/api/v1/auth/login", nil), rid)
+	req.URL.RawQuery = "redirect_uri=" + url.QueryEscape(evil)
+	w := httptest.NewRecorder()
+	rig.handler.HandleLogin(w, req)
+	require.Equal(t, http.StatusFound, w.Code)
+	for k, vs := range w.Header() {
+		for _, v := range vs {
+			assert.NotContains(t, v, "evil.example", "header %s must not echo the rejected value", k)
+		}
+	}
+	assert.NotContains(t, w.Body.String(), "evil.example")
+
+	authURL, err := url.Parse(w.Header().Get("Location"))
+	require.NoError(t, err)
+	cb := rig.authorizeForm(authURL, "approve")
+	cw := rig.callback(rid, cb.String())
+	require.Equal(t, http.StatusFound, cw.Code)
+	assert.Equal(t, "/ui/", cw.Header().Get("Location"))
+	assert.NotContains(t, cw.Body.String(), "evil.example")
+}
diff --git a/internal/serveredition/auth/integration_test.go b/internal/serveredition/auth/integration_test.go
index ce22e063f..ab0275eb6 100644
--- a/internal/serveredition/auth/integration_test.go
+++ b/internal/serveredition/auth/integration_test.go
@@ -116,7 +116,7 @@ func setupIntegration(t *testing.T, email, name, userSub string, oauthCfg *confi
 	// Register the mock provider in the package-level registry so that
 	// GetProvider("google", ...) returns endpoints pointing at the mock.
 	origFactory := providerRegistry["google"]
-	providerRegistry["google"] = func(_ string) *OAuthProvider {
+	providerRegistry["google"] = func(_ *config.ServerEditionOAuthConfig) *OAuthProvider {
 		return &OAuthProvider{
 			Name:         "google",
 			AuthURL:      mockProvider.server.URL + "/authorize",
@@ -148,7 +148,7 @@ func setupIntegration(t *testing.T, email, name, userSub string, oauthCfg *confi
 
 	// -- Components --
 	sessionMgr := NewSessionManager(store, sessionTTL, false)
-	oauthH := NewOAuthHandler(store, sessionMgr, teamsCfg, hmacKey, logger)
+	oauthH := NewOAuthHandler(store, sessionMgr, StaticServerEditionConfig(teamsCfg), hmacKey, logger)
 	authMW := NewServerEditionAuthMiddleware(sessionMgr, store, StaticServerEditionConfig(teamsCfg), hmacKey, logger)
 
 	// -- Router --
@@ -476,8 +476,10 @@ func TestIntegration_DomainRestriction(t *testing.T) {
 	assert.Equal(t, http.StatusForbidden, cbResp.StatusCode,
 		"login from disallowed domain should be rejected with 403")
 
+	// Spec 107 FR-024: the generic page, never the reason.
 	body, _ := io.ReadAll(cbResp.Body)
-	assert.Contains(t, string(body), "domain not allowed")
+	assert.Contains(t, string(body), "Sign-in was not permitted")
+	assert.NotContains(t, string(body), "domain not allowed")
 }
 
 // ---------- Expired session ----------
diff --git a/internal/serveredition/auth/login_pages.go b/internal/serveredition/auth/login_pages.go
new file mode 100644
index 000000000..d02e5c2fc
--- /dev/null
+++ b/internal/serveredition/auth/login_pages.go
@@ -0,0 +1,81 @@
+//go:build server
+
+package auth
+
+// The two login outcome pages of Spec 107 FR-024 / contracts/rest-endpoints.md
+// §10: ONE generic 403 page for every refusal reason and ONE 503 page for
+// every unavailability. Each carries only the request id, so an operator can
+// find the closed reason in the server log (and, in PR-D, the auth_event
+// line) while the page discloses nothing about why — not the reason, not the
+// IdP's error text, never a claim value or a token.
+
+import (
+	"html/template"
+	"net/http"
+)
+
+const (
+	loginRefusedTitle     = "Sign-in was not permitted"
+	loginUnavailableTitle = "Sign-in is temporarily unavailable"
+)
+
+var loginPageTemplate = template.Must(template.New("login-page").Parse(`<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{.Title}}</title>
+<style>
+body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;background:#f6f7f9;color:#1f2933;margin:0;display:flex;min-height:100vh;align-items:center;justify-content:center}
+main{background:#fff;border-radius:8px;box-shadow:0 1px 3px rgba(0,0,0,.12);padding:32px 40px;max-width:480px;width:calc(100% - 32px);box-sizing:border-box}
+h1{font-size:20px;margin:0 0 12px}
+p{margin:0 0 12px;line-height:1.5}
+code{background:#eef0f3;border-radius:4px;padding:2px 6px;font-size:13px}
+a{color:#2563eb}
+</style>
+</head>
+<body>
+<main>
+<h1>{{.Title}}</h1>
+<p>{{.Body}}</p>
+<p>Reference: <code>ref {{.RequestID}}</code></p>
+<p><a href="/api/v1/auth/login">Try again</a></p>
+</main>
+</body>
+</html>
+`))
+
+type loginPageData struct {
+	Title     string
+	Body      string
+	RequestID string
+}
+
+// writeLoginRefusedPage renders the generic 403 page.
+func writeLoginRefusedPage(w http.ResponseWriter, requestID string) {
+	writeLoginPage(w, http.StatusForbidden, loginPageData{
+		Title:     loginRefusedTitle,
+		Body:      "Your sign-in request could not be completed. If you believe this is a mistake, contact your administrator and quote the reference below.",
+		RequestID: requestID,
+	})
+}
+
+// writeLoginUnavailablePage renders the 503 page.
+func writeLoginUnavailablePage(w http.ResponseWriter, requestID string) {
+	writeLoginPage(w, http.StatusServiceUnavailable, loginPageData{
+		Title:     loginUnavailableTitle,
+		Body:      "Sign-in cannot be completed right now. Please try again in a few minutes; if the problem persists, contact your administrator and quote the reference below.",
+		RequestID: requestID,
+	})
+}
+
+func writeLoginPage(w http.ResponseWriter, status int, data loginPageData) {
+	if data.RequestID == "" {
+		data.RequestID = "-"
+	}
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	w.Header().Set("Cache-Control", "no-store")
+	w.Header().Set("X-Content-Type-Options", "nosniff")
+	w.WriteHeader(status)
+	_ = loginPageTemplate.Execute(w, data)
+}
diff --git a/internal/serveredition/auth/oauth_handler.go b/internal/serveredition/auth/oauth_handler.go
index b20127874..bb07e3edf 100644
--- a/internal/serveredition/auth/oauth_handler.go
+++ b/internal/serveredition/auth/oauth_handler.go
@@ -3,13 +3,16 @@
 package auth
 
 import (
+	"context"
 	"crypto/rand"
 	"crypto/sha256"
 	"encoding/base64"
 	"encoding/hex"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
+	"net/url"
 	"strings"
 	"sync"
 	"time"
@@ -17,47 +20,278 @@ import (
 	"go.uber.org/zap"
 
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/reqcontext"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/secret"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/serveredition/users"
 )
 
+// LoginRefusal is the closed terminal-result vocabulary of one login attempt
+// (Spec 107 FR-013 `auth_event.reason`). Every callback branch maps to exactly
+// one value; the value reaches the server log and the audit line, never the
+// page rendered to the user (FR-024).
+type LoginRefusal string
+
+// The FR-013 vocabulary. "ok" and "logout" are the two non-refusals.
+const (
+	LoginOK                      LoginRefusal = "ok"
+	LoginLogout                  LoginRefusal = "logout"
+	LoginAuthorizationDenied     LoginRefusal = "authorization_denied"
+	LoginIDTokenInvalid          LoginRefusal = "id_token_invalid"
+	LoginNonceMismatch           LoginRefusal = "nonce_mismatch"
+	LoginAudienceMismatch        LoginRefusal = "audience_mismatch"
+	LoginIssuerMismatch          LoginRefusal = "issuer_mismatch"
+	LoginTokenExpired            LoginRefusal = "token_expired"
+	LoginEmailMissing            LoginRefusal = "email_missing"
+	LoginEmailUnverified         LoginRefusal = "email_unverified"
+	LoginDomainNotAllowed        LoginRefusal = "domain_not_allowed"
+	LoginSubjectMismatch         LoginRefusal = "subject_mismatch"
+	LoginUserinfoSubjectMismatch LoginRefusal = "userinfo_subject_mismatch"
+	LoginUserDisabled            LoginRefusal = "user_disabled"
+	LoginStateInvalid            LoginRefusal = "state_invalid"
+	LoginProviderError           LoginRefusal = "provider_error"
+	LoginDiscoveryFailed         LoginRefusal = "discovery_failed"
+	LoginInternalError           LoginRefusal = "internal_error"
+)
+
+// IsUnavailable reports the 503 class (FR-024): an IdP-side failure or a
+// proxy-side failure after verification, never the user's fault.
+func (r LoginRefusal) IsUnavailable() bool {
+	switch r {
+	case LoginProviderError, LoginDiscoveryFailed, LoginInternalError:
+		return true
+	}
+	return false
+}
+
+// LoginFlag is a non-terminal fact of one attempt (FR-013 `flags`).
+type LoginFlag string
+
+// The closed flags vocabulary.
+const (
+	FlagProviderRebound    LoginFlag = "provider_rebound"
+	FlagRedirectRejected   LoginFlag = "redirect_rejected"
+	FlagGroupsClaimMissing LoginFlag = "groups_claim_missing"
+)
+
+// Surfaces a LoginResult is reported on.
+const (
+	LoginSurfaceLogin  = "login"
+	LoginSurfaceLogout = "logout"
+)
+
+// LoginResult is the typed terminal result of one login (or logout) attempt,
+// reported exactly once through OAuthHandler.LoginResultObserver.
+//
+// Identity is stage-dependent (FR-013): UserID when the attempt reached the
+// user store and a record exists; otherwise EmailHash only when a verified
+// email is known and the store was not yet consulted; neither before an
+// identity is established. The two never appear together.
+type LoginResult struct {
+	RequestID string
+	Surface   string // LoginSurfaceLogin | LoginSurfaceLogout
+	Reason    LoginRefusal
+	UserID    string
+	EmailHash string // hex SHA-256 of the normalised email
+	Flags     []LoginFlag
+}
+
+// loginStore is the narrow user-store seam the callback writes through.
+type loginStore interface {
+	UpdateUserLogin(ctx context.Context, claims users.LoginClaims) (users.LoginOutcome, error)
+	GetUserByEmail(email string) (*users.User, error)
+}
+
+// sessionCreator is the narrow session seam the callback creates through.
+type sessionCreator interface {
+	CreateSession(userID string, r *http.Request) (*users.Session, error)
+}
+
+// bearerSignerFunc mints the user JWT; defaulted to GenerateBearerToken.
+type bearerSignerFunc func(hmacKey []byte, userID, email, displayName, role, provider string, ttl time.Duration) (string, error)
+
 // OAuthHandler handles the OAuth login/callback/logout HTTP endpoints.
 type OAuthHandler struct {
 	userStore      *users.UserStore
 	sessionManager *SessionManager
-	config         *config.ServerEditionConfig
-	hmacKey        []byte
-	logger         *zap.SugaredLogger
+	// config yields the LIVE server-edition block: the login role is derived
+	// from the current admin_emails, never the boot pointer (#1169).
+	config ServerEditionConfigProvider
+	// oauthCfg is the boot OAuth block the provider was built from; oauth.*
+	// is restart-pinned (contracts/config-keys.md).
+	oauthCfg *config.ServerEditionOAuthConfig
+	// provider is resolved ONCE at construction (T042) so the oidc discovery
+	// and JWKS caches live as long as the handler; providerErr records a
+	// registry miss, reported as internal_error on every attempt.
+	provider    *OAuthProvider
+	providerErr error
+	hmacKey     []byte
+	logger      *zap.SugaredLogger
+
+	// publicURL is server_edition.public_url from the boot block (restart-
+	// pinned): when set it is the sole source of the callback URL (FR-025).
+	publicURL string
+	// trustedProxies yields the LIVE trusted_proxies list (FR-027); nil
+	// trusts nobody. Evaluated per request, never captured.
+	trustedProxies config.TrustedProxiesProvider
+
+	// Fault-injection seams (T044), defaulted to the real implementations.
+	loginStore     loginStore
+	sessionCreator sessionCreator
+	bearerSigner   bearerSignerFunc
+	// sessionPersist/sessionCleanup isolate the second, bearer-token-bearing
+	// write from sessionCreator.CreateSession's own persist (cross-review
+	// round 3): sessionCleanup best-effort-deletes the bearer-less row
+	// sessionCreator already wrote when sessionPersist fails, so a
+	// persistence fault never leaves an orphan, unusable session sitting
+	// until its TTL expires.
+	sessionPersist func(*users.Session) error
+	sessionCleanup func(string) error
+
+	// LoginResultObserver receives the typed terminal result of every attempt
+	// exactly once (nil = no-op). PR-D installs the auth_event emitter here.
+	LoginResultObserver func(LoginResult)
 
 	// CSRF state storage (in-memory, keyed by state string)
 	pendingStates map[string]*oauthState
 	statesMu      sync.Mutex
+	lastSweep     time.Time // guarded by statesMu; throttles the age sweep
 }
 
 type oauthState struct {
-	CodeVerifier string    // PKCE code verifier
-	RedirectURI  string    // Where to redirect after login
-	CreatedAt    time.Time // For cleanup
+	CodeVerifier     string    // PKCE code verifier
+	Nonce            string    // OIDC nonce bound to this state (`oidc` only)
+	RedirectURI      string    // Where to redirect after login (same-origin path)
+	RedirectRejected bool      // The requested redirect_uri was replaced by /ui/
+	CreatedAt        time.Time // For cleanup and cap eviction
 }
 
-// stateMaxAge is the maximum age for pending OAuth states before cleanup.
-const stateMaxAge = 10 * time.Minute
+const (
+	// stateMaxAge is the maximum age for pending OAuth states before cleanup.
+	stateMaxAge = 10 * time.Minute
+	// stateSweepInterval throttles the age sweep HandleLogin runs.
+	stateSweepInterval = time.Minute
+	// maxPendingStates bounds the map (FR-021): the oldest entry is evicted on
+	// insert when full, in addition to the age sweep.
+	maxPendingStates = 10000
+	// defaultLoginRedirect is where a login lands without a valid redirect_uri.
+	defaultLoginRedirect = "/ui/"
+)
 
-// NewOAuthHandler creates a new OAuthHandler.
+// NewOAuthHandler creates a new OAuthHandler. The provider is resolved from
+// the block cfg yields at construction; discovery stays lazy, so no network
+// I/O happens here.
 func NewOAuthHandler(
 	userStore *users.UserStore,
 	sessionManager *SessionManager,
-	cfg *config.ServerEditionConfig,
+	cfg ServerEditionConfigProvider,
 	hmacKey []byte,
 	logger *zap.SugaredLogger,
 ) *OAuthHandler {
-	return &OAuthHandler{
+	h := &OAuthHandler{
 		userStore:      userStore,
 		sessionManager: sessionManager,
 		config:         cfg,
 		hmacKey:        hmacKey,
 		logger:         logger,
+		loginStore:     userStore,
+		sessionCreator: sessionManager,
+		bearerSigner:   GenerateBearerToken,
+		sessionPersist: userStore.CreateSession,
+		sessionCleanup: userStore.DeleteSession,
 		pendingStates:  make(map[string]*oauthState),
 	}
+	if cfg != nil {
+		if boot := cfg(); boot != nil {
+			h.publicURL = strings.TrimSuffix(boot.PublicURL, "/")
+			if boot.OAuth != nil {
+				h.oauthCfg = boot.Clone().OAuth
+				// Resolve `${env:...}`/`${keyring:...}` refs HERE, on this
+				// handler-private clone, never on the config object
+				// LoadFromFile/GetDesiredConfig hand out — cross-review
+				// round 6, chunk 3 P2: config.LoadFromFile deliberately
+				// stops short of resolving oauth.client_id/client_secret in
+				// place, because that object is round-tripped back to disk
+				// by SaveConfig on every later PATCH /api/v1/config or
+				// /config/apply (even one editing an unrelated field),
+				// which used to persist the resolved plaintext secret over
+				// the operator's `${env:...}` reference. This clone is
+				// never persisted, so it is the one safe place to hold the
+				// live value the token endpoint actually needs.
+				// config.ServerEditionConfig.Validate() already proved both
+				// refs resolve to a non-empty value at boot/PATCH time; a
+				// failure here (the env var was unset in between) is
+				// treated as "not configured" rather than sending the
+				// literal placeholder text to the IdP.
+				resolvedID, idErr := secret.NewResolver().ExpandSecretRefs(context.Background(), h.oauthCfg.ClientID)
+				resolvedSecret, secretErr := secret.NewResolver().ExpandSecretRefs(context.Background(), h.oauthCfg.ClientSecret)
+				if idErr != nil || secretErr != nil || resolvedID == "" || resolvedSecret == "" {
+					if logger != nil {
+						logger.Errorw("server_edition.oauth.client_id/client_secret failed to resolve at handler construction",
+							"client_id_err", idErr, "client_secret_err", secretErr)
+					}
+					h.oauthCfg = nil
+				} else {
+					h.oauthCfg.ClientID = resolvedID
+					h.oauthCfg.ClientSecret = resolvedSecret
+					h.provider, h.providerErr = GetProviderFromConfig(h.oauthCfg)
+				}
+			}
+		}
+	}
+	if h.oauthCfg == nil {
+		h.providerErr = errors.New("OAuth not configured")
+	}
+	return h
+}
+
+// SetTrustedProxiesProvider installs the live trusted_proxies provider the
+// callback-URL and scheme resolution read per request (Spec 107 FR-027).
+func (h *OAuthHandler) SetTrustedProxiesProvider(p config.TrustedProxiesProvider) {
+	h.trustedProxies = p
+}
+
+// CallbackURL returns the OAuth callback URL for one request: from public_url
+// when set (Host and X-Forwarded-* are then ignored), otherwise from the
+// forwarded headers of a trusted proxy or the listener's own scheme and Host.
+func (h *OAuthHandler) CallbackURL(r *http.Request) string {
+	if h.publicURL != "" {
+		return h.publicURL + callbackPath
+	}
+	fwd := config.ForwardedHeaders(r, h.currentTrustedProxies())
+	return fwd.Scheme + "://" + fwd.Host + callbackPath
+}
+
+func (h *OAuthHandler) currentTrustedProxies() []string {
+	if h.trustedProxies == nil {
+		return nil
+	}
+	return h.trustedProxies()
+}
+
+// warnSchemeDisagreement logs ONE operator-readable warning, keyed by the
+// request id, when the observed callback scheme disagrees with public_url's
+// scheme in EITHER direction (FR-025: "the observed request scheme ...
+// disagrees with it"; cross-review round 1, chunk 3 P3 — this used to check
+// only the https-configured/http-observed direction, so an http public_url
+// behind an ingress that terminates TLS and forwards a trusted
+// X-Forwarded-Proto: https produced no warning at all). The login is never
+// blocked either way.
+func (h *OAuthHandler) warnSchemeDisagreement(r *http.Request, requestID string) {
+	if h.publicURL == "" {
+		return
+	}
+	publicIsHTTPS := strings.HasPrefix(strings.ToLower(h.publicURL), "https://")
+	observedIsHTTPS := config.ForwardedHeaders(r, h.currentTrustedProxies()).Scheme == "https"
+	if publicIsHTTPS == observedIsHTTPS {
+		return
+	}
+	if publicIsHTTPS {
+		h.logger.Warnw("public_url is https but the OAuth callback arrived over http; the callback URL still follows public_url — check the ingress forwards X-Forwarded-Proto from an address in trusted_proxies",
+			"request_id", requestID, "public_url", h.publicURL, "remote_addr", r.RemoteAddr)
+		return
+	}
+	h.logger.Warnw("public_url is http but the OAuth callback arrived over https; the callback URL still follows public_url — the Secure cookie decision and redirect_uri may not match the deployment's real scheme",
+		"request_id", requestID, "public_url", h.publicURL, "remote_addr", r.RemoteAddr)
 }
 
 // HandleLogin initiates the OAuth login flow by redirecting the user to the
@@ -68,227 +302,287 @@ func (h *OAuthHandler) HandleLogin(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 		return
 	}
+	attempt := h.newAttempt(r)
 
-	if h.config.OAuth == nil {
-		http.Error(w, "OAuth not configured", http.StatusInternalServerError)
+	if h.providerErr != nil {
+		attempt.unavailable(w, LoginInternalError, "provider", h.providerErr)
 		return
 	}
 
 	// Clean up stale states to prevent memory leaks
-	h.cleanupStaleStates()
+	h.maybeCleanupStaleStates()
 
-	// Generate random state (32 bytes, hex encoded)
-	stateBytes := make([]byte, 32)
-	if _, err := rand.Read(stateBytes); err != nil {
-		h.logger.Errorw("failed to generate state", "error", err)
-		http.Error(w, "internal server error", http.StatusInternalServerError)
+	state, err := randomToken(32, hex.EncodeToString)
+	if err != nil {
+		attempt.unavailable(w, LoginInternalError, "state generation", err)
 		return
 	}
-	state := hex.EncodeToString(stateBytes)
-
-	// Generate PKCE code verifier (32 bytes, base64url encoded, no padding)
-	verifierBytes := make([]byte, 32)
-	if _, err := rand.Read(verifierBytes); err != nil {
-		h.logger.Errorw("failed to generate code verifier", "error", err)
-		http.Error(w, "internal server error", http.StatusInternalServerError)
+	codeVerifier, err := randomToken(32, base64.RawURLEncoding.EncodeToString)
+	if err != nil {
+		attempt.unavailable(w, LoginInternalError, "code verifier generation", err)
 		return
 	}
-	codeVerifier := base64.RawURLEncoding.EncodeToString(verifierBytes)
-
-	// Compute code challenge: SHA256(verifier), base64url encoded, no padding
 	challengeHash := sha256.Sum256([]byte(codeVerifier))
 	codeChallenge := base64.RawURLEncoding.EncodeToString(challengeHash[:])
 
-	// Store state for validation in callback
-	redirectURI := r.URL.Query().Get("redirect_uri")
-	if redirectURI == "" {
-		redirectURI = "/ui/"
-	}
-
-	h.statesMu.Lock()
-	h.pendingStates[state] = &oauthState{
-		CodeVerifier: codeVerifier,
-		RedirectURI:  redirectURI,
-		CreatedAt:    time.Now(),
-	}
-	h.statesMu.Unlock()
-
-	// Get provider configuration
-	provider, err := GetProvider(h.config.OAuth.Provider, h.config.OAuth.TenantID)
-	if err != nil {
-		h.logger.Errorw("failed to get OAuth provider", "error", err)
-		http.Error(w, "OAuth provider configuration error", http.StatusInternalServerError)
-		return
+	redirectURI, rejected := sanitizeLoginRedirect(r.URL.Query().Get("redirect_uri"))
+	callbackURL := h.CallbackURL(r)
+
+	// Build the authorization URL before allocating the pending state, so a
+	// refused login (discovery rejected, IdP unreachable) leaves none behind.
+	// Login never asks the IdP for offline access: the session and the bearer
+	// JWT carry the user, and the IdP refresh token that `store_idp_tokens`
+	// once persisted had no reader (Spec 107 FR-033).
+	var (
+		authURL string
+		nonce   string
+	)
+	if h.provider.IsGenericOIDC() {
+		nonce, err = randomToken(32, base64.RawURLEncoding.EncodeToString)
+		if err != nil {
+			attempt.unavailable(w, LoginInternalError, "nonce generation", err)
+			return
+		}
+		authURL, err = h.provider.oidc.authorizationURL(r.Context(), callbackURL, state, nonce, codeChallenge)
+		if err != nil {
+			attempt.fail(w, err)
+			return
+		}
+	} else {
+		authURL = h.provider.BuildAuthURL(h.oauthCfg.ClientID, callbackURL, state, codeChallenge)
 	}
 
-	// Build the callback URL from the request
-	callbackURL := buildCallbackURL(r)
-
-	// Build the authorization URL. Login never asks the IdP for offline access:
-	// the session and the bearer JWT carry the user, and the IdP refresh token
-	// that `store_idp_tokens` once persisted had no reader (Spec 107 FR-033).
-	authURL := provider.BuildAuthURL(h.config.OAuth.ClientID, callbackURL, state, codeChallenge)
+	h.storePendingState(state, &oauthState{
+		CodeVerifier:     codeVerifier,
+		Nonce:            nonce,
+		RedirectURI:      redirectURI,
+		RedirectRejected: rejected,
+		CreatedAt:        time.Now(),
+	})
 
-	h.logger.Infow("initiating OAuth login", "provider", h.config.OAuth.Provider)
+	h.logger.Infow("initiating OAuth login", "provider", h.provider.Name, "request_id", attempt.requestID, "redirect_rejected", rejected)
 	http.Redirect(w, r, authURL, http.StatusFound)
 }
 
 // HandleCallback handles the OAuth provider callback after user authentication.
 // GET /api/v1/auth/callback?code=xxx&state=yyy
+//
+// The pending state is consumed FIRST; only then is the response classified:
+// an IdP authorization error (`error=…`, RFC 6749 §4.1.2.1) on a live state
+// is authorization_denied, a missing or unknown state is state_invalid.
 func (h *OAuthHandler) HandleCallback(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodGet {
 		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 		return
 	}
+	attempt := h.newAttempt(r)
 
-	if h.config.OAuth == nil {
-		http.Error(w, "OAuth not configured", http.StatusInternalServerError)
-		return
-	}
-
-	code := r.URL.Query().Get("code")
-	state := r.URL.Query().Get("state")
-
-	// Validate required parameters
-	if code == "" {
-		h.logger.Warnw("OAuth callback missing code parameter")
-		writeJSONError(w, http.StatusBadRequest, "missing code parameter")
+	// The pending state is consumed FIRST, exactly as the doc comment above
+	// promises: a broken provider config must not let an absent, unknown or
+	// expired state read as anything but state_invalid, and must not let an
+	// arbitrary caller distinguish "OAuth is misconfigured" from "OAuth is
+	// fine but your state is bad" (cross-review round 7, chunk 2 P3).
+	q := r.URL.Query()
+	pending, ok := h.consumePendingState(q.Get("state"))
+	if !ok {
+		attempt.refuse(w, LoginStateInvalid, "state missing, unknown or expired")
 		return
 	}
-	if state == "" {
-		h.logger.Warnw("OAuth callback missing state parameter")
-		writeJSONError(w, http.StatusBadRequest, "missing state parameter")
-		return
+	if pending.RedirectRejected {
+		attempt.flag(FlagRedirectRejected)
 	}
 
-	// Validate and consume state (CSRF protection)
-	h.statesMu.Lock()
-	pending, ok := h.pendingStates[state]
-	if ok {
-		delete(h.pendingStates, state)
+	if h.providerErr != nil {
+		attempt.unavailable(w, LoginInternalError, "provider", h.providerErr)
+		return
 	}
-	h.statesMu.Unlock()
 
-	if !ok {
-		h.logger.Warnw("OAuth callback with invalid state", "state", state)
-		writeJSONError(w, http.StatusBadRequest, "invalid or expired state parameter")
+	if idpErr := q.Get("error"); idpErr != "" {
+		// The IdP's error and description reach the server log only.
+		h.logger.Warnw("IdP answered the authorization request with an error",
+			"request_id", attempt.requestID, "idp_error", idpErr, "idp_error_description", q.Get("error_description"))
+		attempt.refuse(w, LoginAuthorizationDenied, "authorization response error")
 		return
 	}
-
-	// Get provider
-	provider, err := GetProvider(h.config.OAuth.Provider, h.config.OAuth.TenantID)
-	if err != nil {
-		h.logger.Errorw("failed to get OAuth provider", "error", err)
-		http.Error(w, "OAuth provider configuration error", http.StatusInternalServerError)
+	code := q.Get("code")
+	if code == "" {
+		attempt.refuse(w, LoginAuthorizationDenied, "authorization response carries neither code nor error")
 		return
 	}
 
-	// Build the callback URL (must match the one used in login)
-	callbackURL := buildCallbackURL(r)
-
-	// Exchange code for tokens
-	tokenResp, err := provider.ExchangeCode(
-		r.Context(),
-		code,
-		callbackURL,
-		h.config.OAuth.ClientID,
-		h.config.OAuth.ClientSecret,
-		pending.CodeVerifier,
+	h.warnSchemeDisagreement(r, attempt.requestID)
+	callbackURL := h.CallbackURL(r)
+	var (
+		userInfo *OAuthUserInfo
+		err      error
 	)
-	if err != nil {
-		h.logger.Errorw("OAuth code exchange failed", "error", err)
-		http.Error(w, "authentication failed", http.StatusInternalServerError)
-		return
+	if h.provider.IsGenericOIDC() {
+		userInfo, err = h.oidcIdentity(r.Context(), attempt, code, callbackURL, pending)
+	} else {
+		userInfo, err = h.legacyIdentity(r.Context(), code, callbackURL, pending)
 	}
-
-	// Fetch user info (try ID token first for OIDC providers, fall back to userinfo endpoint)
-	userInfo, err := provider.FetchUserInfoFromToken(r.Context(), tokenResp)
 	if err != nil {
-		h.logger.Errorw("failed to fetch user info", "error", err)
-		http.Error(w, "failed to retrieve user information", http.StatusInternalServerError)
+		attempt.fail(w, err)
 		return
 	}
-
 	if userInfo.Email == "" {
-		h.logger.Warnw("OAuth user info missing email")
-		http.Error(w, "email address is required", http.StatusBadRequest)
+		attempt.refuse(w, LoginEmailMissing, "email claim missing")
 		return
 	}
+	attempt.emailHash = emailHash(userInfo.Email)
 
-	// Check allowed domains
 	if !h.isDomainAllowed(userInfo.Email) {
-		h.logger.Warnw("OAuth login domain not allowed",
-			"email", userInfo.Email,
-			"allowed_domains", h.config.OAuth.AllowedDomains,
-		)
-		writeJSONError(w, http.StatusForbidden, "email domain not allowed")
+		attempt.refuse(w, LoginDomainNotAllowed, "email domain not in allowed_domains")
 		return
 	}
 
-	// Upsert user: find existing or create new
-	user, err := h.upsertUser(userInfo, h.config.OAuth.Provider)
+	// Upsert through the transaction-owned store contract (FR-023).
+	groups := userInfo.Groups
+	if groups == nil {
+		groups = []string{} // legacy providers store []
+	}
+	outcome, err := h.loginStore.UpdateUserLogin(r.Context(), users.LoginClaims{
+		Email:       userInfo.Email,
+		Provider:    h.provider.Name,
+		Subject:     userInfo.SubjectID,
+		Name:        userInfo.DisplayName,
+		AvatarURL:   userInfo.AvatarURL,
+		Groups:      groups,
+		GroupsKnown: true,
+	})
 	if err != nil {
-		h.logger.Errorw("failed to upsert user", "error", err)
-		http.Error(w, "failed to create user account", http.StatusInternalServerError)
+		switch {
+		case errors.Is(err, users.ErrSubjectMismatch):
+			attempt.setUserID(h.lookupUserID(userInfo.Email))
+			attempt.refuse(w, LoginSubjectMismatch, "provider subject differs from the stored binding")
+		case errors.Is(err, users.ErrUserDisabled):
+			attempt.setUserID(h.lookupUserID(userInfo.Email))
+			attempt.refuse(w, LoginUserDisabled, "user record disabled")
+		default:
+			// The store WAS consulted here (the upsert itself failed), so
+			// FR-013's "store not yet consulted" condition for email_hash no
+			// longer holds and no user record was established either — the
+			// event must carry neither identity field (cross-review round 8,
+			// chunk 2 P2).
+			attempt.clearEmailHash()
+			attempt.unavailable(w, LoginInternalError, "user store", err)
+		}
 		return
 	}
+	user := outcome.User
+	attempt.setUserID(user.ID)
+	if outcome.Rebound {
+		attempt.flag(FlagProviderRebound)
+	}
 
-	// Determine role
+	// Role from the CURRENT admin_emails.
 	role := "user"
-	if h.config.IsAdminEmail(user.Email) {
+	if live := h.liveConfig(); live != nil && live.IsAdminEmail(user.Email) {
 		role = "admin"
 	}
 
-	// Generate JWT bearer token
-	bearerToken, err := GenerateBearerToken(
-		h.hmacKey,
-		user.ID,
-		user.Email,
-		user.DisplayName,
-		role,
-		user.Provider,
-		h.config.BearerTokenTTL.Duration(),
-	)
+	bearerToken, err := h.bearerSigner(h.hmacKey, user.ID, user.Email, user.DisplayName, role, user.Provider, h.bearerTokenTTL())
 	if err != nil {
-		h.logger.Errorw("failed to generate bearer token", "error", err)
-		http.Error(w, "failed to generate access token", http.StatusInternalServerError)
+		attempt.unavailable(w, LoginInternalError, "bearer token signer", err)
 		return
 	}
 
-	// Create session
-	session, err := h.sessionManager.CreateSession(user.ID, r)
+	session, err := h.sessionCreator.CreateSession(user.ID, r)
 	if err != nil {
-		h.logger.Errorw("failed to create session", "error", err)
-		http.Error(w, "failed to create session", http.StatusInternalServerError)
+		attempt.unavailable(w, LoginInternalError, "session creation", err)
 		return
 	}
-
-	// Store bearer token in session
 	session.BearerToken = bearerToken
-	if err := h.sessionManager.store.CreateSession(session); err != nil {
-		h.logger.Errorw("failed to update session with bearer token", "error", err)
-		http.Error(w, "failed to create session", http.StatusInternalServerError)
+	if err := h.sessionPersist(session); err != nil {
+		// The bearer-less row sessionCreator.CreateSession already wrote is
+		// cleaned up best-effort: its own error is discarded, since the
+		// persistence failure above is already reported and a delete failure
+		// here must not mask it (the row then simply expires at its TTL).
+		_ = h.sessionCleanup(session.ID)
+		attempt.unavailable(w, LoginInternalError, "session persistence", err)
 		return
 	}
-
-	// Set session cookie
 	h.sessionManager.SetSessionCookie(w, session)
 
 	h.logger.Infow("OAuth login successful",
+		"request_id", attempt.requestID,
 		"user_id", user.ID,
-		"email", user.Email,
 		"provider", user.Provider,
 		"role", role,
+		"created", outcome.Created,
+		"rebound", outcome.Rebound,
 	)
+	attempt.succeed()
 
-	// Redirect to the original destination or dashboard
 	redirectTarget := pending.RedirectURI
 	if redirectTarget == "" {
-		redirectTarget = "/ui/"
+		redirectTarget = defaultLoginRedirect
 	}
 	http.Redirect(w, r, redirectTarget, http.StatusFound)
 }
 
+// oidcIdentity runs the `oidc` callback half: token exchange, verified ID
+// token, email/email_verified policy, groups (FR-021/FR-022/FR-008).
+func (h *OAuthHandler) oidcIdentity(ctx context.Context, attempt *loginAttempt, code, callbackURL string, pending *oauthState) (*OAuthUserInfo, error) {
+	prov := h.provider.oidc
+	tokenResp, err := prov.exchangeCode(ctx, code, callbackURL, pending.CodeVerifier)
+	if err != nil {
+		return nil, err
+	}
+	claims, err := prov.verifyIDToken(ctx, tokenResp.IDToken, pending.Nonce)
+	if err != nil {
+		return nil, err
+	}
+	if claims.Email == "" {
+		return nil, newOIDCError(LoginEmailMissing, "id_token has no email claim", nil)
+	}
+	switch policy := h.oauthCfg.EmailVerifiedPolicy; policy {
+	case config.EmailVerifiedPolicyIgnore:
+	case config.EmailVerifiedPolicyRequireTrue:
+		if claims.EmailVerified == nil || !*claims.EmailVerified {
+			return nil, newOIDCError(LoginEmailUnverified, "email_verified is not true (policy require_true)", nil)
+		}
+	default: // refuse_false
+		if claims.EmailVerified != nil && !*claims.EmailVerified {
+			return nil, newOIDCError(LoginEmailUnverified, "email_verified is false (policy refuse_false)", nil)
+		}
+	}
+	// The email is now verified: the attempt carries its hash from here on.
+	attempt.emailHash = emailHash(claims.Email)
+
+	groups, missing, err := prov.resolveGroups(ctx, claims, tokenResp.AccessToken)
+	if err != nil {
+		return nil, err
+	}
+	if missing {
+		attempt.flag(FlagGroupsClaimMissing)
+		attempt.groupsClaimMissing = true
+	}
+	return &OAuthUserInfo{
+		Email:         claims.Email,
+		DisplayName:   claims.Name,
+		SubjectID:     claims.Subject,
+		AvatarURL:     claims.Picture,
+		Groups:        groups,
+		EmailVerified: claims.EmailVerified,
+	}, nil
+}
+
+// legacyIdentity runs the unchanged google/github/microsoft callback half
+// (US2.10): client_secret_post exchange, then the ID token payload or the
+// provider's userinfo/emails endpoints.
+func (h *OAuthHandler) legacyIdentity(ctx context.Context, code, callbackURL string, pending *oauthState) (*OAuthUserInfo, error) {
+	tokenResp, err := h.provider.ExchangeCode(ctx, code, callbackURL, h.oauthCfg.ClientID, h.oauthCfg.ClientSecret, pending.CodeVerifier)
+	if err != nil {
+		return nil, newOIDCError(LoginProviderError, "token exchange", err)
+	}
+	userInfo, err := h.provider.FetchUserInfoFromToken(ctx, tokenResp)
+	if err != nil {
+		return nil, newOIDCError(LoginProviderError, "userinfo", err)
+	}
+	return userInfo, nil
+}
+
 // HandleLogout handles user logout by revoking the session and clearing the cookie.
 // POST /api/v1/auth/logout
 func (h *OAuthHandler) HandleLogout(w http.ResponseWriter, r *http.Request) {
@@ -316,16 +610,224 @@ func (h *OAuthHandler) HandleLogout(w http.ResponseWriter, r *http.Request) {
 		// Continue with cookie clearing even if revoke fails
 	}
 
-	// Clear session cookie
-	h.sessionManager.ClearSessionCookie(w)
+	// Clear session cookie with the Secure attribute it was set with.
+	h.sessionManager.ClearSessionCookieFor(w, r, session)
 
 	h.logger.Infow("user logged out", "user_id", session.UserID, "session_id", session.ID)
+	h.observe(LoginResult{
+		RequestID: reqcontext.GetRequestID(r.Context()),
+		Surface:   LoginSurfaceLogout,
+		Reason:    LoginLogout,
+		UserID:    session.UserID,
+	})
 
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(http.StatusOK)
 	json.NewEncoder(w).Encode(map[string]string{"status": "logged_out"}) //nolint:errcheck
 }
 
+// --- attempt bookkeeping -------------------------------------------------------
+
+// loginAttempt accumulates the stage-dependent identity and flags of one
+// attempt and renders exactly one terminal outcome.
+type loginAttempt struct {
+	h                  *OAuthHandler
+	requestID          string
+	userID             string
+	emailHash          string
+	flags              []LoginFlag
+	groupsClaimMissing bool
+	reported           bool
+}
+
+func (h *OAuthHandler) newAttempt(r *http.Request) *loginAttempt {
+	return &loginAttempt{h: h, requestID: reqcontext.GetRequestID(r.Context())}
+}
+
+func (a *loginAttempt) flag(f LoginFlag) { a.flags = append(a.flags, f) }
+
+// setUserID records that the store was reached and a record exists; the
+// email hash is dropped, the two never appear together (FR-013).
+func (a *loginAttempt) setUserID(id string) {
+	if id == "" {
+		return
+	}
+	a.userID, a.emailHash = id, ""
+}
+
+// clearEmailHash drops a provisional email hash once the store has been
+// consulted and failed without establishing a record: FR-013 reserves
+// email_hash for reasons where the store was not yet consulted, and it must
+// never appear alongside a failed-but-attempted upsert either.
+func (a *loginAttempt) clearEmailHash() {
+	a.emailHash = ""
+}
+
+func (a *loginAttempt) result(reason LoginRefusal) LoginResult {
+	return LoginResult{
+		RequestID: a.requestID,
+		Surface:   LoginSurfaceLogin,
+		Reason:    reason,
+		UserID:    a.userID,
+		EmailHash: a.emailHash,
+		Flags:     append([]LoginFlag(nil), a.flags...),
+	}
+}
+
+// report delivers the terminal result once.
+func (a *loginAttempt) report(reason LoginRefusal) {
+	if a.reported {
+		return
+	}
+	a.reported = true
+	a.h.observe(a.result(reason))
+}
+
+// refuse renders the generic 403 page; the reason and the failed check reach
+// the log only.
+func (a *loginAttempt) refuse(w http.ResponseWriter, reason LoginRefusal, check string) {
+	a.h.logger.Warnw("login refused", "request_id", a.requestID, "reason", string(reason), "check", check, "user_id", a.userID)
+	a.report(reason)
+	writeLoginRefusedPage(w, a.requestID)
+}
+
+// unavailable renders the 503 page for the IdP-side and proxy-side failure
+// class.
+func (a *loginAttempt) unavailable(w http.ResponseWriter, reason LoginRefusal, check string, err error) {
+	a.h.logger.Errorw("login unavailable", "request_id", a.requestID, "reason", string(reason), "check", check, "error", err, "user_id", a.userID)
+	a.report(reason)
+	writeLoginUnavailablePage(w, a.requestID)
+}
+
+// fail classifies a provider/verification error into its closed reason.
+func (a *loginAttempt) fail(w http.ResponseWriter, err error) {
+	var oerr *oidcError
+	if !errors.As(err, &oerr) {
+		a.unavailable(w, LoginInternalError, "unclassified", err)
+		return
+	}
+	if oerr.reason.IsUnavailable() {
+		a.unavailable(w, oerr.reason, oerr.check, oerr.err)
+		return
+	}
+	check := oerr.check
+	if oerr.err != nil {
+		check += ": " + oerr.err.Error()
+	}
+	a.refuse(w, oerr.reason, check)
+}
+
+// succeed reports the ok result (and the groups_claim_missing warning).
+func (a *loginAttempt) succeed() {
+	if a.groupsClaimMissing {
+		a.h.logger.Warnw("groups_claim_missing: the verified identity carried no usable groups claim; stored []",
+			"request_id", a.requestID, "user_id", a.userID, "groups_claim", a.h.oauthCfg.GroupsClaim)
+	}
+	a.report(LoginOK)
+}
+
+func (h *OAuthHandler) observe(res LoginResult) {
+	if h.LoginResultObserver != nil {
+		h.LoginResultObserver(res)
+	}
+}
+
+// --- helpers ------------------------------------------------------------------
+
+// liveConfig returns the current server-edition block (nil-safe).
+func (h *OAuthHandler) liveConfig() *config.ServerEditionConfig {
+	if h.config == nil {
+		return nil
+	}
+	return h.config()
+}
+
+func (h *OAuthHandler) bearerTokenTTL() time.Duration {
+	if live := h.liveConfig(); live != nil && live.BearerTokenTTL.Duration() > 0 {
+		return live.BearerTokenTTL.Duration()
+	}
+	return 24 * time.Hour
+}
+
+// lookupUserID resolves the record id for a refused login that reached the
+// store (subject_mismatch, user_disabled); best effort.
+func (h *OAuthHandler) lookupUserID(email string) string {
+	u, err := h.loginStore.GetUserByEmail(email)
+	if err != nil || u == nil {
+		return ""
+	}
+	return u.ID
+}
+
+// emailHash is the FR-013 email_hash: hex SHA-256 of the normalised email.
+func emailHash(email string) string {
+	sum := sha256.Sum256([]byte(strings.ToLower(strings.TrimSpace(email))))
+	return hex.EncodeToString(sum[:])
+}
+
+// randomToken draws n random bytes and encodes them.
+func randomToken(n int, encode func([]byte) string) (string, error) {
+	b := make([]byte, n)
+	if _, err := rand.Read(b); err != nil {
+		return "", fmt.Errorf("generating random token: %w", err)
+	}
+	return encode(b), nil
+}
+
+// storePendingState inserts a state, evicting the oldest entry when the cap
+// is reached (FR-021).
+func (h *OAuthHandler) storePendingState(state string, s *oauthState) {
+	h.statesMu.Lock()
+	defer h.statesMu.Unlock()
+	for len(h.pendingStates) >= maxPendingStates {
+		var (
+			oldestKey string
+			oldest    time.Time
+			first     = true
+		)
+		for k, v := range h.pendingStates {
+			if first || v.CreatedAt.Before(oldest) {
+				oldestKey, oldest, first = k, v.CreatedAt, false
+			}
+		}
+		delete(h.pendingStates, oldestKey)
+	}
+	h.pendingStates[state] = s
+}
+
+// consumePendingState removes and returns the pending state (CSRF check).
+func (h *OAuthHandler) consumePendingState(state string) (*oauthState, bool) {
+	if state == "" {
+		return nil, false
+	}
+	h.statesMu.Lock()
+	defer h.statesMu.Unlock()
+	pending, ok := h.pendingStates[state]
+	if !ok {
+		return nil, false
+	}
+	delete(h.pendingStates, state)
+	if time.Since(pending.CreatedAt) > stateMaxAge {
+		return nil, false
+	}
+	return pending, true
+}
+
+// maybeCleanupStaleStates runs the age sweep at most once per sweep interval,
+// so a burst of logins is not O(n) per request; the cap eviction on insert
+// bounds the map regardless.
+func (h *OAuthHandler) maybeCleanupStaleStates() {
+	h.statesMu.Lock()
+	due := time.Since(h.lastSweep) >= stateSweepInterval
+	if due {
+		h.lastSweep = time.Now()
+	}
+	h.statesMu.Unlock()
+	if due {
+		h.cleanupStaleStates()
+	}
+}
+
 // cleanupStaleStates removes pending states older than stateMaxAge.
 func (h *OAuthHandler) cleanupStaleStates() {
 	h.statesMu.Lock()
@@ -339,10 +841,34 @@ func (h *OAuthHandler) cleanupStaleStates() {
 	}
 }
 
+// sanitizeLoginRedirect admits redirect_uri only as a same-origin path
+// (contracts/rest-endpoints.md §10, research D10): a single leading "/", not
+// "//" or "/\", no scheme, host, backslash, CR, LF or control character —
+// checked on the percent-decoded value. Anything else is replaced by /ui/
+// and reported as rejected.
+func sanitizeLoginRedirect(raw string) (target string, rejected bool) {
+	if raw == "" {
+		return defaultLoginRedirect, false
+	}
+	if !strings.HasPrefix(raw, "/") || strings.HasPrefix(raw, "//") || strings.HasPrefix(raw, "/\\") {
+		return defaultLoginRedirect, true
+	}
+	for _, c := range raw {
+		if c < 0x20 || c == 0x7f || c == '\\' {
+			return defaultLoginRedirect, true
+		}
+	}
+	u, err := url.Parse(raw)
+	if err != nil || u.Scheme != "" || u.Host != "" || u.User != nil || u.Opaque != "" {
+		return defaultLoginRedirect, true
+	}
+	return raw, false
+}
+
 // isDomainAllowed checks if the user's email domain is in the allowed domains list.
 // Returns true if no allowed domains are configured (allow all).
 func (h *OAuthHandler) isDomainAllowed(email string) bool {
-	if h.config.OAuth == nil || len(h.config.OAuth.AllowedDomains) == 0 {
+	if h.oauthCfg == nil || len(h.oauthCfg.AllowedDomains) == 0 {
 		return true
 	}
 
@@ -352,7 +878,7 @@ func (h *OAuthHandler) isDomainAllowed(email string) bool {
 	}
 	domain := strings.ToLower(parts[1])
 
-	for _, allowed := range h.config.OAuth.AllowedDomains {
+	for _, allowed := range h.oauthCfg.AllowedDomains {
 		if strings.EqualFold(allowed, domain) {
 			return true
 		}
@@ -360,46 +886,5 @@ func (h *OAuthHandler) isDomainAllowed(email string) bool {
 	return false
 }
 
-// upsertUser finds an existing user by email or creates a new one.
-// If the user exists, LastLoginAt is updated.
-func (h *OAuthHandler) upsertUser(info *OAuthUserInfo, provider string) (*users.User, error) {
-	existing, err := h.userStore.GetUserByEmail(info.Email)
-	if err != nil {
-		return nil, fmt.Errorf("looking up user: %w", err)
-	}
-
-	if existing != nil {
-		// Update last login time and any changed profile info
-		existing.LastLoginAt = time.Now().UTC()
-		if info.DisplayName != "" {
-			existing.DisplayName = info.DisplayName
-		}
-		if info.AvatarURL != "" && info.SubjectID != "" {
-			existing.ProviderSubjectID = info.SubjectID
-		}
-		if err := h.userStore.UpdateUser(existing); err != nil {
-			return nil, fmt.Errorf("updating user: %w", err)
-		}
-		return existing, nil
-	}
-
-	// Create new user
-	newUser := users.NewUser(info.Email, info.DisplayName, provider, info.SubjectID)
-	if err := h.userStore.CreateUser(newUser); err != nil {
-		return nil, fmt.Errorf("creating user: %w", err)
-	}
-	return newUser, nil
-}
-
-// buildCallbackURL constructs the OAuth callback URL from the HTTP request.
-func buildCallbackURL(r *http.Request) string {
-	scheme := "http"
-	if r.TLS != nil {
-		scheme = "https"
-	}
-	// Check X-Forwarded-Proto for reverse proxy setups
-	if proto := r.Header.Get("X-Forwarded-Proto"); proto != "" {
-		scheme = proto
-	}
-	return fmt.Sprintf("%s://%s/api/v1/auth/callback", scheme, r.Host)
-}
+// callbackPath is the OAuth callback route relative to the public origin.
+const callbackPath = "/api/v1/auth/callback"
diff --git a/internal/serveredition/auth/oauth_handler_refusal_test.go b/internal/serveredition/auth/oauth_handler_refusal_test.go
new file mode 100644
index 000000000..26ce16974
--- /dev/null
+++ b/internal/serveredition/auth/oauth_handler_refusal_test.go
@@ -0,0 +1,1261 @@
+//go:build server
+
+package auth
+
+// Spec 107 T039 (PR-B, compile-red until T044): every login refusal renders
+// the ONE generic 403 page keyed by a request id, every unavailability renders
+// the ONE 503 page, the typed terminal LoginResult is reported exactly once
+// through the handler's observer hook, and the user store is untouched on
+// every refusal. No audit line is asserted here (T106/T107 in PR-D re-drive
+// these fixtures against the auth_event emitter installed on the same hook).
+//
+// Contract exercised here (tasks.md T042/T044, data-model §1/§7, FR-013,
+// FR-017, FR-021, FR-024, contracts/rest-endpoints.md §10):
+//
+//	// T042 — the provider factory takes the OAuth block and is resolved ONCE
+//	// in NewOAuthHandler (h.provider); a registry swap must precede construction.
+//	var providerRegistry map[string]func(*config.ServerEditionOAuthConfig) *OAuthProvider
+//
+//	// T044 — the handler reads the LIVE server-edition block (role from the
+//	// current admin_emails, never the boot pointer).
+//	func NewOAuthHandler(*users.UserStore, *SessionManager, ServerEditionConfigProvider, []byte, *zap.SugaredLogger) *OAuthHandler
+//
+//	// T044 — closed reason vocabulary (FR-013 auth_event `reason`), string-kinded.
+//	type LoginRefusal string
+//	type LoginResult struct {
+//	    RequestID string
+//	    Surface   string       // "login" | "logout"
+//	    Reason    LoginRefusal // ok | authorization_denied | … | internal_error
+//	    UserID    string       // set when the attempt reached the store and a record exists
+//	    EmailHash string       // hex SHA-256 of the normalised email, only for a verified email
+//	    Flags     []string     // provider_rebound | redirect_rejected | groups_claim_missing
+//	}
+//	// nil = no-op; called exactly once per terminal attempt (FR-017).
+//	OAuthHandler.LoginResultObserver func(LoginResult)
+//
+//	// T044 — fault-injection seams, defaulted to the real implementations.
+//	OAuthHandler.loginStore     loginStore     // UpdateUserLogin(ctx, users.LoginClaims) (users.LoginOutcome, error); GetUserByEmail(string) (*users.User, error)
+//	OAuthHandler.sessionCreator sessionCreator // CreateSession(userID string, r *http.Request) (*users.Session, error)
+//	OAuthHandler.bearerSigner   func(hmacKey []byte, userID, email, displayName, role, provider string, ttl time.Duration) (string, error)
+//
+//	// T044 — pendingStates bounded at 10,000 entries, oldest CreatedAt evicted on insert.
+//	// T041 — config: OAuth.IssuerURL, OAuth.AllowInsecureIssuer, OAuth.Scopes,
+//	//        OAuth.GroupsClaim, OAuth.EmailVerifiedPolicy.
+//	// T044 — users.User.Groups []string, users.User.GroupsUpdatedAt time.Time.
+//
+// The 403 page carries "Sign-in was not permitted (ref <request id>)" and the
+// 503 page "Sign-in is temporarily unavailable (ref <request id>)"
+// (contracts/rest-endpoints.md §10). Neither ever carries the closed reason,
+// the IdP's `error`/`error_description`, a claim value or a token.
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.etcd.io/bbolt"
+	"go.uber.org/zap"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/reqcontext"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/serveredition/users"
+	"github.com/smart-mcp-proxy/mcpproxy-go/tests/oauthserver"
+)
+
+const (
+	refusalUser        = "alice@example.com"
+	refusalPass        = "pass"
+	refusalSub         = "alice-sub-1"
+	refusalHost        = "127.0.0.1"
+	refusalCallbackURI = "http://" + refusalHost + "/api/v1/auth/callback"
+
+	refusalPage403     = "Sign-in was not permitted"
+	refusalPage503     = "Sign-in is temporarily unavailable"
+	pendingStatesCap   = 10000
+	refusalIdPErrorMsg = "Injected error"
+	refusalDenyMsg     = "User denied the authorization request"
+)
+
+var refusalAliceClaims = map[string]any{
+	"sub":            refusalSub,
+	"email":          refusalUser,
+	"email_verified": true,
+	"name":           "Alice Example",
+	"groups":         []any{"eng", "sre"},
+}
+
+// FR-013 auth_event reasons that render the generic 403 page. Every entry in
+// this table is refused with the same page and status (FR-024).
+var refusal403Reasons = []string{
+	"authorization_denied", "id_token_invalid", "nonce_mismatch", "audience_mismatch",
+	"issuer_mismatch", "token_expired", "email_missing", "email_unverified",
+	"domain_not_allowed", "subject_mismatch", "userinfo_subject_mismatch",
+	"user_disabled", "state_invalid",
+}
+
+// ---------------------------------------------------------------------------
+// Observer recorder
+// ---------------------------------------------------------------------------
+
+type loginResultRecorder struct {
+	mu      sync.Mutex
+	results []LoginResult
+}
+
+func (r *loginResultRecorder) observe(res LoginResult) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.results = append(r.results, res)
+}
+
+func (r *loginResultRecorder) all() []LoginResult {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	out := make([]LoginResult, len(r.results))
+	copy(out, r.results)
+	return out
+}
+
+func (r *loginResultRecorder) reset() {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.results = nil
+}
+
+// exactlyOne asserts the FR-017 invariant — one terminal result per attempt —
+// and returns it.
+func (r *loginResultRecorder) exactlyOne(t *testing.T) LoginResult {
+	t.Helper()
+	got := r.all()
+	require.Len(t, got, 1, "exactly one LoginResult per terminal attempt, got %+v", got)
+	return got[0]
+}
+
+// ---------------------------------------------------------------------------
+// Live config holder (ServerEditionConfigProvider)
+// ---------------------------------------------------------------------------
+
+type refusalLiveConfig struct {
+	mu      sync.Mutex
+	current *config.ServerEditionConfig
+}
+
+func (l *refusalLiveConfig) get() *config.ServerEditionConfig {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	return l.current
+}
+
+func (l *refusalLiveConfig) swap(cfg *config.ServerEditionConfig) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	l.current = cfg
+}
+
+// ---------------------------------------------------------------------------
+// Rig
+// ---------------------------------------------------------------------------
+
+type refusalRig struct {
+	t       *testing.T
+	handler *OAuthHandler
+	store   *users.UserStore
+	live    *refusalLiveConfig
+	fake    *oauthserver.ServerResult // nil for the legacy-provider rigs
+	results *loginResultRecorder
+	hmacKey []byte
+	client  *http.Client // drives the fake IdP; never follows redirects
+}
+
+func refusalServerEditionConfig(oauthCfg *config.ServerEditionOAuthConfig) *config.ServerEditionConfig {
+	return &config.ServerEditionConfig{
+		Enabled:        true,
+		AdminEmails:    []string{"admin@example.com"},
+		OAuth:          oauthCfg,
+		SessionTTL:     config.Duration(time.Hour),
+		BearerTokenTTL: config.Duration(time.Hour),
+	}
+}
+
+// newRefusalRig builds an OAuthHandler over a real BBolt store with the
+// observer installed. The provider is resolved once at construction (T042),
+// so any registry swap must happen before this call.
+func newRefusalRig(t *testing.T, oauthCfg *config.ServerEditionOAuthConfig) *refusalRig {
+	t.Helper()
+
+	tmpFile := filepath.Join(t.TempDir(), "refusal.db")
+	db, err := bbolt.Open(tmpFile, 0600, &bbolt.Options{Timeout: time.Second})
+	require.NoError(t, err)
+	t.Cleanup(func() { db.Close() })
+
+	store := users.NewUserStore(db)
+	require.NoError(t, store.EnsureBuckets())
+
+	sessionMgr := NewSessionManager(store, time.Hour, false)
+	live := &refusalLiveConfig{current: refusalServerEditionConfig(oauthCfg)}
+	hmacKey := []byte("test-hmac-key-for-jwt-signing-32b")
+
+	handler := NewOAuthHandler(store, sessionMgr, ServerEditionConfigProvider(live.get), hmacKey, zap.NewNop().Sugar())
+	rec := &loginResultRecorder{}
+	handler.LoginResultObserver = rec.observe
+
+	return &refusalRig{
+		t:       t,
+		handler: handler,
+		store:   store,
+		live:    live,
+		results: rec,
+		hmacKey: hmacKey,
+		client: &http.Client{
+			Timeout: 5 * time.Second,
+			CheckRedirect: func(*http.Request, []*http.Request) error {
+				return http.ErrUseLastResponse
+			},
+		},
+	}
+}
+
+func refusalFakeOptions(mode oauthserver.ErrorMode) oauthserver.Options {
+	return oauthserver.Options{
+		OIDC:               true,
+		ValidUsers:         map[string]string{refusalUser: refusalPass},
+		UserClaims:         map[string]map[string]any{refusalUser: refusalAliceClaims},
+		ClientRedirectURIs: []string{refusalCallbackURI},
+		GroupsClaim:        "groups",
+		ErrorMode:          mode,
+	}
+}
+
+// newOIDCRefusalRig starts the in-process fake OIDC IdP with the given tamper
+// mode and a handler configured with `provider: oidc` against it. mutate may
+// adjust the OAuth block before the handler is constructed.
+func newOIDCRefusalRig(t *testing.T, mode oauthserver.ErrorMode, mutate func(*config.ServerEditionOAuthConfig)) *refusalRig {
+	t.Helper()
+	fake := oauthserver.Start(t, refusalFakeOptions(mode))
+	t.Cleanup(func() { _ = fake.Shutdown() })
+
+	oauthCfg := &config.ServerEditionOAuthConfig{
+		Provider:            "oidc",
+		ClientID:            fake.ClientID,
+		ClientSecret:        fake.ClientSecret,
+		IssuerURL:           fake.IssuerURL, // http://127.0.0.1:<port> — loopback
+		AllowInsecureIssuer: true,
+		Scopes:              []string{"openid", "profile", "email"},
+		GroupsClaim:         "groups",
+		EmailVerifiedPolicy: "refuse_false",
+	}
+	if mutate != nil {
+		mutate(oauthCfg)
+	}
+	rig := newRefusalRig(t, oauthCfg)
+	rig.fake = fake
+	return rig
+}
+
+// withRequestID stamps the request id the RequestIDMiddleware would have put
+// on the context, so the page and the LoginResult can be keyed by it.
+func withRequestID(req *http.Request, rid string) *http.Request {
+	return req.WithContext(reqcontext.WithRequestID(req.Context(), rid))
+}
+
+// login calls HandleLogin with the given request id and returns the recorder
+// and the parsed Location (nil when the response is not a redirect).
+func (r *refusalRig) login(rid string) (*httptest.ResponseRecorder, *url.URL) {
+	r.t.Helper()
+	req := withRequestID(httptest.NewRequest(http.MethodGet, "http://"+refusalHost+"/api/v1/auth/login", nil), rid)
+	w := httptest.NewRecorder()
+	r.handler.HandleLogin(w, req)
+	if w.Code != http.StatusFound {
+		return w, nil
+	}
+	loc, err := url.Parse(w.Header().Get("Location"))
+	require.NoError(r.t, err)
+	return w, loc
+}
+
+// mustLogin is login with the redirect required.
+func (r *refusalRig) mustLogin(rid string) *url.URL {
+	r.t.Helper()
+	w, loc := r.login(rid)
+	require.Equal(r.t, http.StatusFound, w.Code, "login must redirect to the IdP; body=%s", w.Body.String())
+	require.NotNil(r.t, loc)
+	return loc
+}
+
+// idpRedirect returns the Location of a 302 answered by the fake IdP.
+func (r *refusalRig) idpRedirect(resp *http.Response) *url.URL {
+	r.t.Helper()
+	defer resp.Body.Close()
+	_, _ = io.Copy(io.Discard, resp.Body)
+	require.Equal(r.t, http.StatusFound, resp.StatusCode, "fake IdP must redirect back to the callback")
+	loc, err := url.Parse(resp.Header.Get("Location"))
+	require.NoError(r.t, err)
+	require.Equal(r.t, "/api/v1/auth/callback", loc.Path, "IdP redirect must target the callback: %s", loc)
+	return loc
+}
+
+// authorizeGET follows the handler's redirect with a plain GET, for the knobs
+// that answer the authorization request itself with an error redirect.
+func (r *refusalRig) authorizeGET(authURL *url.URL) *url.URL {
+	r.t.Helper()
+	resp, err := r.client.Get(authURL.String())
+	require.NoError(r.t, err)
+	return r.idpRedirect(resp)
+}
+
+// authorizeForm submits the fake's headless login form with every parameter
+// the handler put on the authorization URL (state, nonce, PKCE, redirect_uri)
+// and the given consent action.
+func (r *refusalRig) authorizeForm(authURL *url.URL, action string) *url.URL {
+	r.t.Helper()
+	form := authURL.Query()
+	form.Set("username", refusalUser)
+	form.Set("password", refusalPass)
+	form.Set("action", action)
+	if action == "approve" {
+		form.Set("consent", "on")
+	}
+	resp, err := r.client.PostForm(r.fake.AuthorizationEndpoint, form)
+	require.NoError(r.t, err)
+	return r.idpRedirect(resp)
+}
+
+// callback calls HandleCallback with the given full callback URL.
+func (r *refusalRig) callback(rid string, callbackURL string) *httptest.ResponseRecorder {
+	r.t.Helper()
+	req := withRequestID(httptest.NewRequest(http.MethodGet, callbackURL, nil), rid)
+	req.Host = refusalHost
+	w := httptest.NewRecorder()
+	r.handler.HandleCallback(w, req)
+	return w
+}
+
+// approveFlow drives login → form approve → callback and returns the callback
+// recorder.
+func (r *refusalRig) approveFlow(rid string) *httptest.ResponseRecorder {
+	r.t.Helper()
+	authURL := r.mustLogin(rid)
+	cb := r.authorizeForm(authURL, "approve")
+	return r.callback(rid, cb.String())
+}
+
+func (r *refusalRig) pendingLen() int {
+	r.handler.statesMu.Lock()
+	defer r.handler.statesMu.Unlock()
+	return len(r.handler.pendingStates)
+}
+
+func (r *refusalRig) hasPending(state string) bool {
+	r.handler.statesMu.Lock()
+	defer r.handler.statesMu.Unlock()
+	_, ok := r.handler.pendingStates[state]
+	return ok
+}
+
+// usersSnapshot serialises every user record so "store untouched" is a byte
+// comparison, not a field-by-field guess.
+func (r *refusalRig) usersSnapshot() map[string]string {
+	r.t.Helper()
+	all, err := r.store.ListUsers()
+	require.NoError(r.t, err)
+	out := make(map[string]string, len(all))
+	for _, u := range all {
+		b, err := json.Marshal(u)
+		require.NoError(r.t, err)
+		out[u.ID] = string(b)
+	}
+	return out
+}
+
+func (r *refusalRig) sessionCount() int {
+	r.t.Helper()
+	all, err := r.store.ListSessions()
+	require.NoError(r.t, err)
+	return len(all)
+}
+
+func emailHashOf(email string) string {
+	sum := sha256.Sum256([]byte(strings.ToLower(strings.TrimSpace(email))))
+	return hex.EncodeToString(sum[:])
+}
+
+// ---------------------------------------------------------------------------
+// Page assertions
+// ---------------------------------------------------------------------------
+
+// assertGenericRefusalPage asserts the FR-024 403 page and returns the body
+// with the request id replaced by a placeholder so pages of different
+// attempts can be compared byte-for-byte.
+func assertGenericRefusalPage(t *testing.T, w *httptest.ResponseRecorder, rid string) string {
+	t.Helper()
+	body := w.Body.String()
+	assert.Equal(t, http.StatusForbidden, w.Code, "every refusal is 403; body=%s", body)
+	assert.True(t, strings.HasPrefix(w.Header().Get("Content-Type"), "text/html"), "the refusal is a page, got Content-Type %q", w.Header().Get("Content-Type"))
+	assert.Contains(t, body, refusalPage403)
+	assert.Contains(t, body, rid, "the page must carry the request id")
+	assert.NotContains(t, body, refusalPage503)
+	assertNoRefusalLeak(t, body)
+	assert.Empty(t, w.Result().Cookies(), "a refusal never sets a cookie")
+	return strings.ReplaceAll(body, rid, "<RID>")
+}
+
+// assertUnavailablePage asserts the FR-024 503 page.
+func assertUnavailablePage(t *testing.T, w *httptest.ResponseRecorder, rid string) string {
+	t.Helper()
+	body := w.Body.String()
+	assert.Equal(t, http.StatusServiceUnavailable, w.Code, "unavailability is 503; body=%s", body)
+	assert.True(t, strings.HasPrefix(w.Header().Get("Content-Type"), "text/html"), "the unavailability response is a page, got Content-Type %q", w.Header().Get("Content-Type"))
+	assert.Contains(t, body, refusalPage503)
+	assert.Contains(t, body, rid, "the page must carry the request id")
+	assert.NotContains(t, body, refusalPage403)
+	assertNoRefusalLeak(t, body)
+	assert.Empty(t, w.Result().Cookies(), "an unavailability never sets a cookie")
+	return strings.ReplaceAll(body, rid, "<RID>")
+}
+
+// assertNoRefusalLeak: the closed reason, the IdP's error vocabulary and the
+// claim values reach only the server log, never the page.
+func assertNoRefusalLeak(t *testing.T, body string) {
+	t.Helper()
+	for _, reason := range refusal403Reasons {
+		assert.NotContains(t, body, reason, "the closed reason must not be rendered")
+	}
+	for _, s := range []string{"provider_error", "discovery_failed", "internal_error",
+		"access_denied", "error_description", refusalIdPErrorMsg, refusalDenyMsg,
+		refusalUser, refusalSub, "Alice Example", "eyJ"} {
+		assert.NotContains(t, body, s, "page must not disclose %q", s)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// authorization_denied — the IdP answered the authorization request with an
+// error (FR-013, rest-endpoints §10). Today the callback returns a distinct
+// 400 "missing code parameter" before touching the state
+// (oauth_handler.go:153-157).
+// ---------------------------------------------------------------------------
+
+func TestHandleCallback_Refusal_AuthorizationDenied(t *testing.T) {
+	assertDenied := func(t *testing.T, rig *refusalRig, rid, state string, w *httptest.ResponseRecorder) {
+		t.Helper()
+		assertGenericRefusalPage(t, w, rid)
+		res := rig.results.exactlyOne(t)
+		assert.EqualValues(t, "authorization_denied", res.Reason)
+		assert.Equal(t, rid, res.RequestID)
+		assert.EqualValues(t, "login", res.Surface)
+		assert.Empty(t, res.UserID, "no identity is established on an authorization error")
+		assert.Empty(t, res.EmailHash, "no identity is established on an authorization error")
+		assert.False(t, rig.hasPending(state), "the pending state is consumed on the error callback")
+		assert.Empty(t, rig.usersSnapshot(), "store untouched")
+		assert.Zero(t, rig.sessionCount())
+	}
+
+	t.Run("error param with error_description on a live state", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+		const rid = "req-denied-direct"
+		authURL := rig.mustLogin(rid)
+		state := authURL.Query().Get("state")
+		require.NotEmpty(t, state)
+		rig.results.reset()
+
+		q := url.Values{}
+		q.Set("error", "access_denied")
+		q.Set("error_description", refusalIdPErrorMsg)
+		q.Set("state", state)
+		w := rig.callback(rid, refusalCallbackURI+"?"+q.Encode())
+		assertDenied(t, rig, rid, state, w)
+	})
+
+	t.Run("fake AuthAccessDenied knob", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{AuthAccessDenied: true}, nil)
+		const rid = "req-denied-knob"
+		authURL := rig.mustLogin(rid)
+		state := authURL.Query().Get("state")
+		rig.results.reset()
+
+		cb := rig.authorizeGET(authURL)
+		require.Equal(t, "access_denied", cb.Query().Get("error"))
+		require.Equal(t, state, cb.Query().Get("state"))
+		w := rig.callback(rid, cb.String())
+		assertDenied(t, rig, rid, state, w)
+	})
+
+	t.Run("user declines consent on the fake's form", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+		const rid = "req-denied-consent"
+		authURL := rig.mustLogin(rid)
+		state := authURL.Query().Get("state")
+		rig.results.reset()
+
+		cb := rig.authorizeForm(authURL, "deny")
+		require.Equal(t, "access_denied", cb.Query().Get("error"))
+		require.Equal(t, state, cb.Query().Get("state"))
+		w := rig.callback(rid, cb.String())
+		assertDenied(t, rig, rid, state, w)
+	})
+
+	// Any other RFC 6749 §4.1.2.1 code on a valid state is the same refusal.
+	for i, code := range []string{"invalid_request", "unauthorized_client", "unsupported_response_type",
+		"invalid_scope", "server_error", "temporarily_unavailable"} {
+		i, code := i, code
+		t.Run("rfc6749 error="+code, func(t *testing.T) {
+			rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+			rid := fmt.Sprintf("req-denied-rfc-%d", i)
+			authURL := rig.mustLogin(rid)
+			state := authURL.Query().Get("state")
+			rig.results.reset()
+
+			q := url.Values{}
+			q.Set("error", code)
+			q.Set("error_description", refusalIdPErrorMsg)
+			q.Set("state", state)
+			w := rig.callback(rid, refusalCallbackURI+"?"+q.Encode())
+			assertDenied(t, rig, rid, state, w)
+		})
+	}
+}
+
+// The pending state is consumed BEFORE the response is classified: an error
+// (or anything else) arriving without a live state is state_invalid, and a
+// state consumed by an error callback cannot be replayed with a code.
+func TestHandleCallback_Refusal_StateConsumedBeforeClassification(t *testing.T) {
+	assertStateInvalid := func(t *testing.T, rig *refusalRig, rid string, w *httptest.ResponseRecorder) {
+		t.Helper()
+		assertGenericRefusalPage(t, w, rid)
+		res := rig.results.exactlyOne(t)
+		assert.EqualValues(t, "state_invalid", res.Reason)
+		assert.Equal(t, rid, res.RequestID)
+		assert.EqualValues(t, "login", res.Surface)
+		assert.Empty(t, res.UserID)
+		assert.Empty(t, res.EmailHash)
+		assert.Empty(t, rig.usersSnapshot(), "store untouched")
+	}
+
+	t.Run("error with an unknown state is state_invalid, not authorization_denied", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+		const rid = "req-state-unknown-error"
+		q := url.Values{}
+		q.Set("error", "access_denied")
+		q.Set("error_description", refusalIdPErrorMsg)
+		q.Set("state", "never-issued-state")
+		w := rig.callback(rid, refusalCallbackURI+"?"+q.Encode())
+		assertStateInvalid(t, rig, rid, w)
+	})
+
+	t.Run("error without any state is state_invalid (today: 400 missing code)", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+		const rid = "req-state-missing-error"
+		w := rig.callback(rid, refusalCallbackURI+"?error=access_denied")
+		assertStateInvalid(t, rig, rid, w)
+	})
+
+	t.Run("code without any state is state_invalid (today: 400 missing state)", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+		const rid = "req-state-missing-code"
+		w := rig.callback(rid, refusalCallbackURI+"?code=some-code")
+		assertStateInvalid(t, rig, rid, w)
+	})
+
+	t.Run("code with an unknown state is state_invalid (today: 400 JSON)", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+		const rid = "req-state-unknown-code"
+		w := rig.callback(rid, refusalCallbackURI+"?code=some-code&state=never-issued-state")
+		assertStateInvalid(t, rig, rid, w)
+	})
+
+	t.Run("a state consumed by an error callback cannot be replayed with a valid code", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+		const rid1 = "req-replay-1"
+		const rid2 = "req-replay-2"
+
+		// A real authorization for that state, so the code is genuinely valid.
+		authURL := rig.mustLogin(rid1)
+		state := authURL.Query().Get("state")
+		cb := rig.authorizeForm(authURL, "approve")
+		require.NotEmpty(t, cb.Query().Get("code"))
+		require.Equal(t, state, cb.Query().Get("state"))
+		rig.results.reset()
+
+		// The error arrives first and consumes the state.
+		q := url.Values{}
+		q.Set("error", "access_denied")
+		q.Set("state", state)
+		w1 := rig.callback(rid1, refusalCallbackURI+"?"+q.Encode())
+		assertGenericRefusalPage(t, w1, rid1)
+		assert.EqualValues(t, "authorization_denied", rig.results.exactlyOne(t).Reason)
+		assert.False(t, rig.hasPending(state))
+		rig.results.reset()
+
+		// The valid code on the consumed state is a replay.
+		w2 := rig.callback(rid2, cb.String())
+		assertStateInvalid(t, rig, rid2, w2)
+	})
+
+	t.Run("live state with neither code nor error is refused with the generic page", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+		const rid = "req-state-bare"
+		authURL := rig.mustLogin(rid)
+		state := authURL.Query().Get("state")
+		rig.results.reset()
+
+		w := rig.callback(rid, refusalCallbackURI+"?state="+state)
+		assertGenericRefusalPage(t, w, rid)
+		res := rig.results.exactlyOne(t)
+		assert.Contains(t, refusal403Reasons, string(res.Reason), "the reason must be one of the closed 403 vocabulary")
+		assert.Equal(t, rid, res.RequestID)
+		assert.False(t, rig.hasPending(state), "the state is consumed")
+		assert.Empty(t, rig.usersSnapshot(), "store untouched")
+	})
+}
+
+// ---------------------------------------------------------------------------
+// One generic page for every refusal reason (FR-024, US2.8)
+// ---------------------------------------------------------------------------
+
+func TestHandleCallback_Refusal_OneGenericPageForEveryReason(t *testing.T) {
+	type refusalCase struct {
+		name   string
+		reason string
+		mode   oauthserver.ErrorMode
+		mutate func(*config.ServerEditionOAuthConfig)
+		// seed pre-creates a record; returns its id when the attempt is
+		// expected to reach the store and find it (FR-013 identity rule).
+		seed func(t *testing.T, store *users.UserStore) string
+		// wantEmailHash: verified email known, store not consulted.
+		wantEmailHash bool
+		// drive: nil = approve flow; otherwise a custom driver.
+		drive func(t *testing.T, rig *refusalRig, rid string) *httptest.ResponseRecorder
+	}
+
+	cases := []refusalCase{
+		{
+			name:   "state_invalid",
+			reason: "state_invalid",
+			drive: func(t *testing.T, rig *refusalRig, rid string) *httptest.ResponseRecorder {
+				return rig.callback(rid, refusalCallbackURI+"?code=x&state=bogus")
+			},
+		},
+		{
+			name:   "authorization_denied",
+			reason: "authorization_denied",
+			drive: func(t *testing.T, rig *refusalRig, rid string) *httptest.ResponseRecorder {
+				authURL := rig.mustLogin(rid)
+				rig.results.reset()
+				return rig.callback(rid, rig.authorizeForm(authURL, "deny").String())
+			},
+		},
+		{name: "id_token_invalid (bad signature)", reason: "id_token_invalid", mode: oauthserver.ErrorMode{IDTokenBadSignature: true}},
+		{name: "id_token_invalid (alg none)", reason: "id_token_invalid", mode: oauthserver.ErrorMode{IDTokenAlgNone: true}},
+		{name: "id_token_invalid (HS256)", reason: "id_token_invalid", mode: oauthserver.ErrorMode{IDTokenHS256: true}},
+		{name: "nonce_mismatch (nonce absent)", reason: "nonce_mismatch", mode: oauthserver.ErrorMode{IDTokenNoNonce: true}},
+		{name: "audience_mismatch", reason: "audience_mismatch", mode: oauthserver.ErrorMode{IDTokenWrongAudience: true}},
+		{name: "audience_mismatch (multi-aud without azp)", reason: "audience_mismatch", mode: oauthserver.ErrorMode{IDTokenMultiAudNoAzp: true}},
+		{name: "issuer_mismatch", reason: "issuer_mismatch", mode: oauthserver.ErrorMode{IDTokenWrongIssuer: true}},
+		{name: "token_expired", reason: "token_expired", mode: oauthserver.ErrorMode{IDTokenExpired: true}},
+		{name: "email_unverified", reason: "email_unverified", mode: oauthserver.ErrorMode{EmailVerifiedFalse: true}},
+		{
+			name:   "domain_not_allowed",
+			reason: "domain_not_allowed",
+			mutate: func(c *config.ServerEditionOAuthConfig) { c.AllowedDomains = []string{"other.example"} },
+			// The email came from a verified ID token; the store was not consulted.
+			wantEmailHash: true,
+		},
+		{
+			name:          "userinfo_subject_mismatch",
+			reason:        "userinfo_subject_mismatch",
+			mode:          oauthserver.ErrorMode{UserinfoSubMismatch: true},
+			wantEmailHash: true,
+		},
+		{
+			name:   "subject_mismatch",
+			reason: "subject_mismatch",
+			seed: func(t *testing.T, store *users.UserStore) string {
+				u := users.NewUser(refusalUser, "Alice Example", "oidc", "someone-else-sub")
+				require.NoError(t, store.CreateUser(u))
+				return u.ID
+			},
+		},
+		{
+			name:   "user_disabled",
+			reason: "user_disabled",
+			seed: func(t *testing.T, store *users.UserStore) string {
+				u := users.NewUser(refusalUser, "Alice Example", "oidc", refusalSub)
+				u.Disabled = true
+				require.NoError(t, store.CreateUser(u))
+				return u.ID
+			},
+		},
+	}
+
+	var (
+		baselineMu   sync.Mutex
+		baselineBody string
+		baselineName string
+	)
+
+	for i, tc := range cases {
+		i, tc := i, tc
+		t.Run(tc.name, func(t *testing.T) {
+			rig := newOIDCRefusalRig(t, tc.mode, tc.mutate)
+			// Index-based so the request id never contains a reason string
+			// (the page must not carry the reason, and the rid is on the page).
+			rid := fmt.Sprintf("req-generic-%02d", i)
+
+			var wantUserID string
+			if tc.seed != nil {
+				wantUserID = tc.seed(t, rig.store)
+			}
+			before := rig.usersSnapshot()
+
+			var w *httptest.ResponseRecorder
+			if tc.drive != nil {
+				w = tc.drive(t, rig, rid)
+			} else {
+				w = rig.approveFlow(rid)
+			}
+
+			body := assertGenericRefusalPage(t, w, rid)
+
+			// One page for every reason: byte-identical modulo the request id.
+			baselineMu.Lock()
+			if baselineBody == "" {
+				baselineBody, baselineName = body, tc.name
+			} else {
+				assert.Equal(t, baselineBody, body, "the refusal page for %s must be identical to the one for %s", tc.name, baselineName)
+			}
+			baselineMu.Unlock()
+
+			// The typed result, once, keyed by the request id.
+			res := rig.results.exactlyOne(t)
+			assert.EqualValues(t, tc.reason, res.Reason)
+			assert.Equal(t, rid, res.RequestID)
+			assert.EqualValues(t, "login", res.Surface)
+
+			// FR-013 identity rule is stage-dependent.
+			assert.Equal(t, wantUserID, res.UserID, "UserID only when the attempt reached the store and a record exists")
+			if tc.wantEmailHash {
+				assert.Equal(t, emailHashOf(refusalUser), res.EmailHash, "verified email, store not consulted → email_hash")
+			} else {
+				assert.Empty(t, res.EmailHash, "no email_hash before a verified email is known or once the store was consulted")
+			}
+
+			// The store is untouched: nothing created, nothing updated.
+			assert.Equal(t, before, rig.usersSnapshot(), "user store must be untouched on a refusal")
+			assert.Zero(t, rig.sessionCount(), "no session on a refusal")
+		})
+	}
+}
+
+// ---------------------------------------------------------------------------
+// The 503 class: discovery_failed / provider_error / internal_error (FR-024,
+// US2.9). Readiness is a server-level route (httpapi /readyz) and is asserted
+// there by the harness; at the handler level the proxy-side invariant is that
+// the handler survives the outage and the next login retries.
+// ---------------------------------------------------------------------------
+
+func TestHandleLogin_Unavailable_DiscoveryFailedRenders503(t *testing.T) {
+	// A discovery document advertising a plain-http, non-loopback
+	// token_endpoint is rejected as discovery_failed before any redirect to
+	// the IdP (FR-020): no pending state, nothing sent anywhere.
+	rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{DiscoveryHTTPTokenEndpoint: true}, nil)
+	const rid = "req-disc-rejected"
+
+	w, loc := rig.login(rid)
+	assert.Nil(t, loc, "no redirect to the IdP on a rejected discovery document")
+	assertUnavailablePage(t, w, rid)
+	res := rig.results.exactlyOne(t)
+	assert.EqualValues(t, "discovery_failed", res.Reason)
+	assert.Equal(t, rid, res.RequestID)
+	assert.EqualValues(t, "login", res.Surface)
+	assert.Empty(t, res.UserID)
+	assert.Empty(t, res.EmailHash)
+	assert.Zero(t, rig.pendingLen(), "a refused login allocates no pending state")
+	assert.Empty(t, rig.usersSnapshot())
+
+	// The next login retries: a rejected document is never cached.
+	rig.fake.Server.SetErrorMode(oauthserver.ErrorMode{})
+	rig.results.reset()
+	rig.mustLogin("req-disc-recovered")
+	assert.Empty(t, rig.results.all(), "a login that reaches the IdP redirect has no terminal result yet")
+}
+
+func TestHandleLogin_Unavailable_IdPUnreachableRenders503(t *testing.T) {
+	// The issuer is a loopback origin nobody listens on.
+	dead := httptest.NewServer(http.NotFoundHandler())
+	deadURL := dead.URL
+	dead.Close()
+
+	rig := newRefusalRig(t, &config.ServerEditionOAuthConfig{
+		Provider:            "oidc",
+		ClientID:            "client-id",
+		ClientSecret:        "client-secret",
+		IssuerURL:           deadURL,
+		AllowInsecureIssuer: true,
+		Scopes:              []string{"openid", "profile", "email"},
+		GroupsClaim:         "groups",
+		EmailVerifiedPolicy: "refuse_false",
+	})
+	const rid = "req-idp-unreachable"
+
+	w, loc := rig.login(rid)
+	assert.Nil(t, loc)
+	assertUnavailablePage(t, w, rid)
+	res := rig.results.exactlyOne(t)
+	assert.EqualValues(t, "provider_error", res.Reason)
+	assert.Equal(t, rid, res.RequestID)
+	assert.Empty(t, res.UserID)
+	assert.Empty(t, res.EmailHash)
+	assert.Zero(t, rig.pendingLen())
+	assert.Empty(t, rig.usersSnapshot())
+
+	// The handler is still usable: a second attempt is a fresh, independent
+	// terminal result (no stuck lock, no cached failure turned into a panic).
+	rig.results.reset()
+	w2, _ := rig.login("req-idp-unreachable-2")
+	assertUnavailablePage(t, w2, "req-idp-unreachable-2")
+	assert.EqualValues(t, "provider_error", rig.results.exactlyOne(t).Reason)
+}
+
+func TestHandleCallback_Unavailable_ProviderErrorRenders503(t *testing.T) {
+	t.Run("token endpoint 500 during the exchange, then recovery", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+		const rid = "req-token-500"
+
+		authURL := rig.mustLogin(rid)
+		cb := rig.authorizeForm(authURL, "approve")
+		rig.results.reset()
+
+		// The outage begins between the authorization and the exchange.
+		rig.fake.Server.SetErrorMode(oauthserver.ErrorMode{TokenServerError: true})
+		w := rig.callback(rid, cb.String())
+		assertUnavailablePage(t, w, rid)
+		res := rig.results.exactlyOne(t)
+		assert.EqualValues(t, "provider_error", res.Reason)
+		assert.Equal(t, rid, res.RequestID)
+		assert.Empty(t, res.UserID)
+		assert.Empty(t, res.EmailHash, "provider_error from the token exchange precedes any verified identity")
+		assert.Empty(t, rig.usersSnapshot(), "store untouched")
+		assert.Zero(t, rig.sessionCount())
+
+		// The next login retries once the IdP is back.
+		rig.fake.Server.SetErrorMode(oauthserver.ErrorMode{})
+		rig.results.reset()
+		w2 := rig.approveFlow("req-token-recovered")
+		assert.Equal(t, http.StatusFound, w2.Code, "login must succeed after the outage; body=%s", w2.Body.String())
+		ok := rig.results.exactlyOne(t)
+		assert.EqualValues(t, "ok", ok.Reason)
+		assert.NotEmpty(t, ok.UserID)
+	})
+
+	t.Run("token endpoint answers 302 (non-redirecting back channel)", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{TokenEndpointRedirect: true}, nil)
+		const rid = "req-token-302"
+		w := rig.approveFlow(rid)
+		assertUnavailablePage(t, w, rid)
+		res := rig.results.exactlyOne(t)
+		assert.EqualValues(t, "provider_error", res.Reason)
+		assert.Equal(t, rid, res.RequestID)
+		assert.Empty(t, rig.usersSnapshot())
+	})
+
+	t.Run("userinfo unavailable after a verified ID token carries the email hash", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{UserinfoUnavailable: true}, nil)
+		const rid = "req-userinfo-503"
+		w := rig.approveFlow(rid)
+		assertUnavailablePage(t, w, rid)
+		res := rig.results.exactlyOne(t)
+		assert.EqualValues(t, "provider_error", res.Reason)
+		assert.Equal(t, rid, res.RequestID)
+		assert.Empty(t, res.UserID, "the record is never looked up on the userinfo path")
+		assert.Equal(t, emailHashOf(refusalUser), res.EmailHash, "the ID token was verified before userinfo was consulted")
+		assert.Empty(t, rig.usersSnapshot(), "store untouched — a userinfo hiccup never logs a user in with []")
+	})
+}
+
+// ---------------------------------------------------------------------------
+// internal_error — fault injection through the T044 seams, one sub-test per
+// terminal branch (user store, JWT signer, session store).
+// ---------------------------------------------------------------------------
+
+// failingLoginStore satisfies the loginStore seam and fails every upsert
+// without touching the real store.
+type failingLoginStore struct{}
+
+func (failingLoginStore) UpdateUserLogin(context.Context, users.LoginClaims) (users.LoginOutcome, error) {
+	return users.LoginOutcome{}, errors.New("injected: user store unavailable")
+}
+
+func (failingLoginStore) GetUserByEmail(string) (*users.User, error) {
+	return nil, nil
+}
+
+// failingSessionCreator satisfies the sessionCreator seam.
+type failingSessionCreator struct{}
+
+func (failingSessionCreator) CreateSession(string, *http.Request) (*users.Session, error) {
+	return nil, errors.New("injected: session store unavailable")
+}
+
+func TestHandleCallback_Unavailable_InternalErrorRenders503(t *testing.T) {
+	assertInternal := func(t *testing.T, rig *refusalRig, rid string, w *httptest.ResponseRecorder) LoginResult {
+		t.Helper()
+		assertUnavailablePage(t, w, rid)
+		res := rig.results.exactlyOne(t)
+		assert.EqualValues(t, "internal_error", res.Reason)
+		assert.Equal(t, rid, res.RequestID)
+		assert.EqualValues(t, "login", res.Surface)
+		assert.Zero(t, rig.sessionCount(), "no session survives an internal error")
+		return res
+	}
+
+	t.Run("failing loginStore: no user record created before the upsert commits", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+		rig.handler.loginStore = failingLoginStore{}
+		const rid = "req-internal-store"
+
+		w := rig.approveFlow(rid)
+		res := assertInternal(t, rig, rid, w)
+		assert.Empty(t, res.UserID, "no record exists when the upsert failed")
+		assert.Empty(t, res.EmailHash, "the store was already consulted (and failed); FR-013 reserves email_hash for reasons where the store was not yet consulted (cross-review round 8, chunk 2 P2)")
+
+		u, err := rig.store.GetUserByEmail(refusalUser)
+		require.NoError(t, err)
+		assert.Nil(t, u, "the handler must write only through the loginStore seam — no record before the upsert commits")
+		assert.Empty(t, rig.usersSnapshot())
+	})
+
+	t.Run("failing bearerSigner: record exists, no session, no cookie", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+		rig.handler.bearerSigner = func([]byte, string, string, string, string, string, time.Duration) (string, error) {
+			return "", errors.New("injected: signer unavailable")
+		}
+		const rid = "req-internal-signer"
+
+		w := rig.approveFlow(rid)
+		res := assertInternal(t, rig, rid, w)
+
+		u, err := rig.store.GetUserByEmail(refusalUser)
+		require.NoError(t, err)
+		require.NotNil(t, u, "the upsert committed before the signer ran")
+		assert.Equal(t, u.ID, res.UserID, "the attempt reached the store and a record exists → UserID")
+		assert.Empty(t, res.EmailHash)
+	})
+
+	t.Run("failing sessionCreator: record exists, no session, no cookie", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+		rig.handler.sessionCreator = failingSessionCreator{}
+		const rid = "req-internal-session"
+
+		w := rig.approveFlow(rid)
+		res := assertInternal(t, rig, rid, w)
+
+		u, err := rig.store.GetUserByEmail(refusalUser)
+		require.NoError(t, err)
+		require.NotNil(t, u, "the upsert committed before the session was created")
+		assert.Equal(t, u.ID, res.UserID)
+		assert.Empty(t, res.EmailHash)
+	})
+
+	// The bearer-token-bearing write is a second, separate persist
+	// (sessionCreator.CreateSession already durably wrote a bearer-less row);
+	// when it fails, that row must not survive as an orphan until its TTL
+	// (cross-review round 3, internal/serveredition/auth/oauth_handler.go).
+	t.Run("failing sessionPersist: the bearer-less row is cleaned up, not orphaned", func(t *testing.T) {
+		rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+		var capturedID string
+		rig.handler.sessionPersist = func(s *users.Session) error {
+			capturedID = s.ID
+			return errors.New("injected: session persistence unavailable")
+		}
+		const rid = "req-internal-session-persist"
+
+		w := rig.approveFlow(rid)
+		res := assertInternal(t, rig, rid, w)
+
+		u, err := rig.store.GetUserByEmail(refusalUser)
+		require.NoError(t, err)
+		require.NotNil(t, u, "the upsert committed before the session was created")
+		assert.Equal(t, u.ID, res.UserID)
+
+		require.NotEmpty(t, capturedID)
+		orphan, err := rig.store.GetSession(capturedID)
+		require.NoError(t, err)
+		assert.Nil(t, orphan, "the bearer-less row from sessionCreator must be deleted, not left until TTL")
+	})
+}
+
+// ---------------------------------------------------------------------------
+// Role derived live from the CURRENT admin_emails (T044; #1169's remaining
+// horizon). The bearerSigner seam captures the role the handler minted.
+// ---------------------------------------------------------------------------
+
+func TestHandleCallback_RoleDerivedFromLiveAdminEmails(t *testing.T) {
+	rig := newOIDCRefusalRig(t, oauthserver.ErrorMode{}, nil)
+
+	var (
+		rolesMu sync.Mutex
+		roles   []string
+	)
+	rig.handler.bearerSigner = func(hmacKey []byte, userID, email, displayName, role, provider string, ttl time.Duration) (string, error) {
+		rolesMu.Lock()
+		roles = append(roles, role)
+		rolesMu.Unlock()
+		return GenerateBearerToken(hmacKey, userID, email, displayName, role, provider, ttl)
+	}
+
+	// Boot block: alice is not an administrator.
+	w1 := rig.approveFlow("req-role-user")
+	require.Equal(t, http.StatusFound, w1.Code, "login must succeed; body=%s", w1.Body.String())
+	assert.EqualValues(t, "ok", rig.results.exactlyOne(t).Reason)
+
+	// Hot reload: a NEW block (not a mutation of the boot pointer) promotes her.
+	boot := rig.live.get()
+	promoted := refusalServerEditionConfig(boot.OAuth)
+	promoted.AdminEmails = []string{refusalUser}
+	rig.live.swap(promoted)
+	rig.results.reset()
+
+	w2 := rig.approveFlow("req-role-admin")
+	require.Equal(t, http.StatusFound, w2.Code, "login must succeed; body=%s", w2.Body.String())
+	assert.EqualValues(t, "ok", rig.results.exactlyOne(t).Reason)
+
+	// And a demotion takes effect on the very next login.
+	rig.live.swap(boot)
+	rig.results.reset()
+	w3 := rig.approveFlow("req-role-demoted")
+	require.Equal(t, http.StatusFound, w3.Code)
+
+	rolesMu.Lock()
+	defer rolesMu.Unlock()
+	assert.Equal(t, []string{"user", "admin", "user"}, roles, "the role is derived from the live admin_emails at each login")
+}
+
+// ---------------------------------------------------------------------------
+// pendingStates is bounded at 10,000 entries (FR-021): insert 10,001, the
+// first is gone, and the login that used it fails state_invalid.
+// ---------------------------------------------------------------------------
+
+func TestHandleLogin_PendingStatesCappedAtTenThousand(t *testing.T) {
+	// The legacy mock keeps HandleLogin network-free so 10,001 calls are cheap.
+	idp := newLegacyMockIdP(t, "google", refusalUser, "Alice Example", refusalSub)
+	registerLegacyMock(t, "google", idp)
+	rig := newRefusalRig(t, &config.ServerEditionOAuthConfig{
+		Provider:     "google",
+		ClientID:     "client-id",
+		ClientSecret: "client-secret",
+	})
+
+	var firstState string
+	for i := 0; i <= pendingStatesCap; i++ { // 10,001 inserts
+		loc := rig.mustLogin(fmt.Sprintf("req-cap-%d", i))
+		if i == 0 {
+			firstState = loc.Query().Get("state")
+			require.NotEmpty(t, firstState)
+		}
+	}
+
+	assert.Equal(t, pendingStatesCap, rig.pendingLen(), "the map never exceeds the cap")
+	assert.False(t, rig.hasPending(firstState), "the oldest state is evicted on the 10,001st insert")
+
+	rig.results.reset()
+	const rid = "req-cap-evicted-login"
+	w := rig.callback(rid, refusalCallbackURI+"?code=some-code&state="+firstState)
+	assertGenericRefusalPage(t, w, rid)
+	res := rig.results.exactlyOne(t)
+	assert.EqualValues(t, "state_invalid", res.Reason)
+	assert.Equal(t, rid, res.RequestID)
+	assert.Empty(t, rig.usersSnapshot(), "store untouched")
+	assert.Empty(t, idp.paths(), "an evicted state never reaches the IdP")
+}
+
+// ---------------------------------------------------------------------------
+// Legacy providers unchanged (US2.10): no nonce, no JWKS, client_secret_post,
+// stored groups []. Registered through the widened T042 factory signature.
+// ---------------------------------------------------------------------------
+
+// legacyMockIdP records every request the handler makes to a legacy provider.
+type legacyMockIdP struct {
+	srv *httptest.Server
+
+	mu              sync.Mutex
+	seenPaths       []string
+	tokenForm       url.Values
+	tokenAuthHeader string
+}
+
+func newLegacyMockIdP(t *testing.T, provider, email, name, sub string) *legacyMockIdP {
+	t.Helper()
+	m := &legacyMockIdP{}
+	mux := http.NewServeMux()
+
+	record := func(r *http.Request) {
+		m.mu.Lock()
+		m.seenPaths = append(m.seenPaths, r.URL.Path)
+		m.mu.Unlock()
+	}
+
+	mux.HandleFunc("/token", func(w http.ResponseWriter, r *http.Request) {
+		record(r)
+		require.NoError(t, r.ParseForm())
+		m.mu.Lock()
+		m.tokenForm = r.PostForm
+		m.tokenAuthHeader = r.Header.Get("Authorization")
+		m.mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"access_token": "mock-access-token",
+			"token_type":   "Bearer",
+			"expires_in":   3600,
+		})
+	})
+
+	switch provider {
+	case "github":
+		mux.HandleFunc("/user", func(w http.ResponseWriter, r *http.Request) {
+			record(r)
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"id": 4242, "login": "alice", "name": name, "email": email, "avatar_url": "https://example.com/a.png",
+			})
+		})
+		mux.HandleFunc("/user/emails", func(w http.ResponseWriter, r *http.Request) {
+			record(r)
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode([]map[string]any{{"email": email, "primary": true, "verified": true}})
+		})
+	default:
+		mux.HandleFunc("/userinfo", func(w http.ResponseWriter, r *http.Request) {
+			record(r)
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"sub": sub, "email": email, "name": name, "picture": "https://example.com/a.png",
+			})
+		})
+	}
+
+	// Anything else — a JWKS or discovery fetch in particular — is recorded
+	// and refused.
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		record(r)
+		http.NotFound(w, r)
+	})
+
+	m.srv = httptest.NewServer(mux)
+	t.Cleanup(m.srv.Close)
+	return m
+}
+
+func (m *legacyMockIdP) paths() []string {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	out := make([]string, len(m.seenPaths))
+	copy(out, m.seenPaths)
+	return out
+}
+
+func (m *legacyMockIdP) token() (url.Values, string) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.tokenForm, m.tokenAuthHeader
+}
+
+// registerLegacyMock swaps a legacy factory for one pointing at the mock,
+// keeping the provider's own shape (GitHub: no OIDC/PKCE, emails endpoint).
+func registerLegacyMock(t *testing.T, name string, idp *legacyMockIdP) {
+	t.Helper()
+	original, had := providerRegistry[name]
+	require.True(t, had, "legacy provider %q must exist in the registry", name)
+
+	providerRegistry[name] = func(_ *config.ServerEditionOAuthConfig) *OAuthProvider {
+		p := &OAuthProvider{
+			Name:         name,
+			AuthURL:      idp.srv.URL + "/authorize",
+			TokenURL:     idp.srv.URL + "/token",
+			UserInfoURL:  idp.srv.URL + "/userinfo",
+			Scopes:       []string{"openid", "email", "profile"},
+			SupportsOIDC: true,
+			SupportsPKCE: true,
+		}
+		if name == "github" {
+			p.UserInfoURL = idp.srv.URL + "/user"
+			p.EmailsURL = idp.srv.URL + "/user/emails"
+			p.Scopes = []string{"user:email", "read:user"}
+			p.SupportsOIDC = false
+			p.SupportsPKCE = false
+		}
+		return p
+	}
+	t.Cleanup(func() { providerRegistry[name] = original })
+}
+
+func TestLegacyProviders_FrontDoorUnchanged(t *testing.T) {
+	for _, provider := range []string{"google", "github", "microsoft"} {
+		provider := provider
+		t.Run(provider, func(t *testing.T) {
+			idp := newLegacyMockIdP(t, provider, refusalUser, "Alice Example", refusalSub)
+			registerLegacyMock(t, provider, idp)
+
+			oauthCfg := &config.ServerEditionOAuthConfig{
+				Provider:     provider,
+				ClientID:     "client-id",
+				ClientSecret: "legacy-client-secret",
+			}
+			if provider == "microsoft" {
+				oauthCfg.TenantID = "common"
+			}
+			rig := newRefusalRig(t, oauthCfg)
+			rid := "req-legacy-" + provider
+
+			// No nonce on the authorization request (no OIDC verification step).
+			authURL := rig.mustLogin(rid)
+			assert.Empty(t, authURL.Query().Get("nonce"), "legacy providers send no nonce")
+			assert.Equal(t, "client-id", authURL.Query().Get("client_id"))
+			state := authURL.Query().Get("state")
+			require.NotEmpty(t, state)
+			assert.Empty(t, idp.paths(), "login makes no discovery or JWKS request for a legacy provider")
+
+			// The provider's callback, as the browser would deliver it.
+			w := rig.callback(rid, refusalCallbackURI+"?code=legacy-code&state="+state)
+			require.Equal(t, http.StatusFound, w.Code, "legacy login must succeed; body=%s", w.Body.String())
+			assert.Equal(t, "/ui/", w.Header().Get("Location"))
+			require.NotEmpty(t, w.Result().Cookies(), "a session cookie is set")
+
+			// client_secret_post, never Basic; no JWKS/discovery on the back channel.
+			form, authHeader := idp.token()
+			assert.Equal(t, "legacy-client-secret", form.Get("client_secret"), "client_secret_post carries the secret in the form")
+			assert.Equal(t, "legacy-code", form.Get("code"))
+			assert.Empty(t, authHeader, "legacy providers never use client_secret_basic")
+			for _, p := range idp.paths() {
+				assert.Contains(t, []string{"/token", "/userinfo", "/user", "/user/emails"}, p, "no JWKS or discovery request for a legacy provider")
+			}
+
+			// Stored groups are [] (never nil) and the login is `ok` with the record id.
+			u, err := rig.store.GetUserByEmail(refusalUser)
+			require.NoError(t, err)
+			require.NotNil(t, u)
+			assert.Equal(t, provider, u.Provider)
+			assert.NotEmpty(t, u.ProviderSubjectID)
+			assert.NotNil(t, u.Groups, "legacy providers store [] — an explicit empty list, not an upgraded-record nil")
+			assert.Empty(t, u.Groups)
+			assert.False(t, u.GroupsUpdatedAt.IsZero(), "the login write stamps groups_updated_at")
+
+			res := rig.results.exactlyOne(t)
+			assert.EqualValues(t, "ok", res.Reason)
+			assert.Equal(t, rid, res.RequestID)
+			assert.Equal(t, u.ID, res.UserID)
+		})
+	}
+}
diff --git a/internal/serveredition/auth/oauth_handler_subject_test.go b/internal/serveredition/auth/oauth_handler_subject_test.go
new file mode 100644
index 000000000..dab235f1e
--- /dev/null
+++ b/internal/serveredition/auth/oauth_handler_subject_test.go
@@ -0,0 +1,781 @@
+//go:build server
+
+package auth
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.etcd.io/bbolt"
+	"go.uber.org/zap"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/serveredition/users"
+)
+
+// Spec 107 T038 — subject binding (FR-023) and the administrator-opened rebind
+// window (`subject_rebind_armed_at`), driven through HandleLogin → HandleCallback
+// against a legacy-shaped fake IdP whose `sub` changes between logins, and
+// through users.(*UserStore).UpdateUserLogin directly for the concurrency
+// fixture.
+//
+// Compile-red until T044 (LoginResult/LoginRefusal/LoginResultObserver on the
+// handler, NewOAuthHandler taking a ServerEditionConfigProvider,
+// users.LoginClaims/LoginOutcome/UpdateUserLogin/ErrSubjectMismatch/
+// ErrUserDisabled, User.SubjectRebindArmedAt/Groups/GroupsUpdatedAt) and T045
+// (the enable/disable handlers that arm and clear the flag — asserted in
+// internal/serveredition/api/admin_handlers_rebind_test.go).
+//
+// Assertions on the closed reason vocabulary compare the wire value
+// (`string(res.Reason)`) rather than a constant name, so T044 is free to name
+// the constants; the values are fixed by FR-013.
+
+const subjectTestHMACKey = "test-hmac-key-for-jwt-signing-32b"
+
+// subjectIdP is a legacy-shaped (token + userinfo) fake provider whose claims
+// can be changed between logins, and whose userinfo endpoint can be made to
+// fail so a login attempt terminates as provider_error after the state was
+// consumed but before the user store is consulted.
+type subjectIdP struct {
+	srv *httptest.Server
+
+	mu           sync.Mutex
+	email        string
+	name         string
+	sub          string
+	picture      string
+	userinfoFail bool
+}
+
+func newSubjectIdP(t *testing.T, email, name, sub string) *subjectIdP {
+	t.Helper()
+	idp := &subjectIdP{email: email, name: name, sub: sub}
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/token", func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"access_token": "subject-access-token",
+			"token_type":   "Bearer",
+			"expires_in":   3600,
+		})
+	})
+	mux.HandleFunc("/userinfo", func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Authorization") != "Bearer subject-access-token" {
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+		idp.mu.Lock()
+		defer idp.mu.Unlock()
+		if idp.userinfoFail {
+			http.Error(w, "upstream boom", http.StatusInternalServerError)
+			return
+		}
+		claims := map[string]any{
+			"sub":   idp.sub,
+			"email": idp.email,
+			"name":  idp.name,
+		}
+		if idp.picture != "" {
+			claims["picture"] = idp.picture
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(claims)
+	})
+
+	idp.srv = httptest.NewServer(mux)
+	t.Cleanup(idp.srv.Close)
+	return idp
+}
+
+func (p *subjectIdP) setSubject(sub string) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	p.sub = sub
+}
+
+func (p *subjectIdP) setUserinfoFail(fail bool) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	p.userinfoFail = fail
+}
+
+// liveServerEditionConfig is a swappable ServerEditionConfigProvider: the
+// handler must read the CURRENT pointer on every login, not the one it was
+// constructed with (T044 "role derived live", issue #1169's remaining horizon).
+type liveServerEditionConfig struct {
+	mu  sync.Mutex
+	cfg *config.ServerEditionConfig
+}
+
+func (l *liveServerEditionConfig) provider() ServerEditionConfigProvider {
+	return func() *config.ServerEditionConfig {
+		l.mu.Lock()
+		defer l.mu.Unlock()
+		return l.cfg
+	}
+}
+
+func (l *liveServerEditionConfig) swap(cfg *config.ServerEditionConfig) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	l.cfg = cfg
+}
+
+func subjectTestConfig(adminEmails ...string) *config.ServerEditionConfig {
+	return &config.ServerEditionConfig{
+		Enabled:     true,
+		AdminEmails: adminEmails,
+		OAuth: &config.ServerEditionOAuthConfig{
+			Provider:     "google",
+			ClientID:     "test-client-id",
+			ClientSecret: "test-client-secret",
+		},
+		SessionTTL:     config.Duration(time.Hour),
+		BearerTokenTTL: config.Duration(time.Hour),
+	}
+}
+
+// subjectRig owns the BBolt file so a test can close and reopen it — the
+// "restart between enable and login" fixture of FR-023.
+type subjectRig struct {
+	t       *testing.T
+	dbPath  string
+	db      *bbolt.DB
+	store   *users.UserStore
+	live    *liveServerEditionConfig
+	handler *OAuthHandler
+
+	resultsMu sync.Mutex
+	results   []LoginResult
+}
+
+func newSubjectRig(t *testing.T, idp *subjectIdP, cfg *config.ServerEditionConfig) *subjectRig {
+	t.Helper()
+	registerMockProvider(t, idp.srv)
+
+	rig := &subjectRig{
+		t:      t,
+		dbPath: filepath.Join(t.TempDir(), "subject.db"),
+		live:   &liveServerEditionConfig{cfg: cfg},
+	}
+	rig.open()
+	t.Cleanup(func() { _ = rig.db.Close() })
+	return rig
+}
+
+// open (re)opens the store and builds a fresh handler over it, installing a
+// LoginResultObserver that records every terminal LoginResult.
+func (rig *subjectRig) open() {
+	rig.t.Helper()
+	db, err := bbolt.Open(rig.dbPath, 0600, &bbolt.Options{Timeout: time.Second})
+	require.NoError(rig.t, err)
+	rig.db = db
+
+	rig.store = users.NewUserStore(db)
+	require.NoError(rig.t, rig.store.EnsureBuckets())
+
+	sessionMgr := NewSessionManager(rig.store, time.Hour, false)
+	rig.handler = NewOAuthHandler(rig.store, sessionMgr, rig.live.provider(), []byte(subjectTestHMACKey), zap.NewNop().Sugar())
+	rig.handler.LoginResultObserver = func(res LoginResult) {
+		rig.resultsMu.Lock()
+		defer rig.resultsMu.Unlock()
+		rig.results = append(rig.results, res)
+	}
+}
+
+// restart closes the BBolt file and reopens it under a new store and handler,
+// exactly what a process restart does to the persisted rebind window.
+func (rig *subjectRig) restart() {
+	rig.t.Helper()
+	require.NoError(rig.t, rig.db.Close())
+	rig.open()
+}
+
+// lastResult returns the single LoginResult reported since the previous call
+// and fails when the handler reported zero or more than one for the attempt.
+func (rig *subjectRig) lastResult() LoginResult {
+	rig.t.Helper()
+	rig.resultsMu.Lock()
+	defer rig.resultsMu.Unlock()
+	require.Len(rig.t, rig.results, 1, "exactly one terminal LoginResult per attempt, got %d", len(rig.results))
+	res := rig.results[0]
+	rig.results = nil
+	return res
+}
+
+// login drives GET /auth/login → the callback with the state the handler
+// minted, returning the callback response. The code is irrelevant: the fake
+// token endpoint accepts anything.
+func (rig *subjectRig) login() *http.Response {
+	rig.t.Helper()
+
+	loginReq := httptest.NewRequest(http.MethodGet, "/api/v1/auth/login?redirect_uri=/dashboard", nil)
+	loginReq.Host = "localhost:8080"
+	loginW := httptest.NewRecorder()
+	rig.handler.HandleLogin(loginW, loginReq)
+	require.Equal(rig.t, http.StatusFound, loginW.Code, "login must redirect to the IdP")
+
+	authURL, err := url.Parse(loginW.Header().Get("Location"))
+	require.NoError(rig.t, err)
+	state := authURL.Query().Get("state")
+	require.NotEmpty(rig.t, state)
+
+	cbReq := httptest.NewRequest(http.MethodGet,
+		fmt.Sprintf("/api/v1/auth/callback?code=any-code&state=%s", url.QueryEscape(state)), nil)
+	cbReq.Host = "localhost:8080"
+	cbW := httptest.NewRecorder()
+	rig.handler.HandleCallback(cbW, cbReq)
+
+	resp := cbW.Result()
+	rig.t.Cleanup(func() { _ = resp.Body.Close() })
+	return resp
+}
+
+func (rig *subjectRig) userByEmail(email string) *users.User {
+	rig.t.Helper()
+	u, err := rig.store.GetUserByEmail(email)
+	require.NoError(rig.t, err)
+	require.NotNil(rig.t, u, "user %s must exist", email)
+	return u
+}
+
+// arm sets subject_rebind_armed_at directly on the stored record — the
+// enable-handler half is covered by admin_handlers_rebind_test.go.
+func (rig *subjectRig) arm(email string) time.Time {
+	rig.t.Helper()
+	u := rig.userByEmail(email)
+	armedAt := time.Now().UTC().Truncate(time.Millisecond)
+	u.SubjectRebindArmedAt = &armedAt
+	require.NoError(rig.t, rig.store.UpdateUser(u))
+	return armedAt
+}
+
+func sessionCookie(resp *http.Response) *http.Cookie {
+	for _, c := range resp.Cookies() {
+		if c.Name == SessionCookieName {
+			return c
+		}
+	}
+	return nil
+}
+
+// roleOf reads the role from the bearer JWT stored on the session the callback
+// created — the value every later /api/v1 request will carry.
+func (rig *subjectRig) roleOf(resp *http.Response) string {
+	rig.t.Helper()
+	c := sessionCookie(resp)
+	require.NotNil(rig.t, c, "successful login must set the session cookie")
+	sess, err := rig.store.GetSession(c.Value)
+	require.NoError(rig.t, err)
+	require.NotNil(rig.t, sess)
+	claims, err := ValidateBearerToken(sess.BearerToken, []byte(subjectTestHMACKey))
+	require.NoError(rig.t, err)
+	return claims.Role
+}
+
+func flagsOf(res LoginResult) []string {
+	out := []string{}
+	for _, f := range res.Flags {
+		out = append(out, string(f))
+	}
+	return out
+}
+
+func seedUser(t *testing.T, store *users.UserStore, email, provider, sub string) *users.User {
+	t.Helper()
+	u := users.NewUser(email, "Alice Seed", provider, sub)
+	// Push the seed's timestamps into the past so "refreshed on login" is
+	// observable without sleeping.
+	u.CreatedAt = u.CreatedAt.Add(-time.Hour)
+	u.LastLoginAt = u.LastLoginAt.Add(-time.Hour)
+	require.NoError(t, store.CreateUser(u))
+	return u
+}
+
+// --- FR-023: same provider + email, different sub → subject_mismatch ---------
+
+func TestSubjectBinding_SameProviderDifferentSubjectIsRefused(t *testing.T) {
+	idp := newSubjectIdP(t, "alice@example.com", "Alice", "sub-B")
+	rig := newSubjectRig(t, idp, subjectTestConfig())
+	seeded := seedUser(t, rig.store, "alice@example.com", "google", "sub-A")
+	before := rig.userByEmail("alice@example.com")
+
+	resp := rig.login()
+
+	assert.Equal(t, http.StatusForbidden, resp.StatusCode, "subject mismatch renders the generic 403 page")
+	assert.Nil(t, sessionCookie(resp), "no session on a refused login")
+
+	res := rig.lastResult()
+	assert.Equal(t, "subject_mismatch", string(res.Reason))
+	assert.Equal(t, seeded.ID, res.UserID, "the attempt reached the store and a record exists → user_id is carried")
+	assert.Empty(t, res.EmailHash, "user_id and email_hash never appear together")
+	assert.NotContains(t, flagsOf(res), "provider_rebound")
+
+	after := rig.userByEmail("alice@example.com")
+	assert.Equal(t, before, after, "a refused login writes nothing: subject, provider and last_login stay as they were")
+	assert.Equal(t, "sub-A", after.ProviderSubjectID)
+	assert.Nil(t, after.SubjectRebindArmedAt)
+
+	all, err := rig.store.ListUsers()
+	require.NoError(t, err)
+	assert.Len(t, all, 1, "no second record for the colliding email")
+}
+
+// --- FR-023: configured-provider change → the first login re-binds -----------
+
+func TestSubjectBinding_ProviderChangeRebindsOnFirstLogin(t *testing.T) {
+	idp := newSubjectIdP(t, "alice@example.com", "Alice", "g-1")
+	rig := newSubjectRig(t, idp, subjectTestConfig())
+	// The record was bound while `github` was the configured provider; the
+	// operator has since switched the configuration to `google` (the fake).
+	seeded := seedUser(t, rig.store, "alice@example.com", "github", "gh-1")
+
+	resp := rig.login()
+
+	assert.Equal(t, http.StatusFound, resp.StatusCode)
+	assert.Equal(t, "/dashboard", resp.Header.Get("Location"))
+	require.NotNil(t, sessionCookie(resp))
+
+	res := rig.lastResult()
+	assert.Equal(t, "ok", string(res.Reason))
+	assert.Equal(t, seeded.ID, res.UserID)
+	assert.Contains(t, flagsOf(res), "provider_rebound")
+
+	after := rig.userByEmail("alice@example.com")
+	assert.Equal(t, seeded.ID, after.ID, "same record, re-bound — never a second user")
+	assert.Equal(t, "google", after.Provider, "Provider is refreshed to the configured provider")
+	assert.Equal(t, "g-1", after.ProviderSubjectID, "ProviderSubjectID is refreshed to the new provider's sub")
+	assert.Nil(t, after.SubjectRebindArmedAt, "a provider change needs no armed window and leaves none behind")
+	assert.True(t, after.LastLoginAt.After(seeded.LastLoginAt))
+
+	// The binding now stands: the same email from the new provider with yet
+	// another subject is a plain mismatch.
+	idp.setSubject("g-2")
+	resp = rig.login()
+	assert.Equal(t, http.StatusForbidden, resp.StatusCode)
+	assert.Equal(t, "subject_mismatch", string(rig.lastResult().Reason))
+	assert.Equal(t, "g-1", rig.userByEmail("alice@example.com").ProviderSubjectID)
+}
+
+// --- FR-023: Provider / ProviderSubjectID refreshed on every login ------------
+//
+// Today ProviderSubjectID is only written when the IdP also sent an avatar URL
+// (oauth_handler.go upsertUser, critic C4) and Provider is never written. The
+// fake here sends no `picture`, so the old guard would leave the empty subject
+// empty.
+func TestSubjectBinding_SubjectRefreshedWithoutAvatar(t *testing.T) {
+	idp := newSubjectIdP(t, "alice@example.com", "Alice", "sub-A")
+	rig := newSubjectRig(t, idp, subjectTestConfig())
+
+	// A record with an empty subject (bound before the IdP exposed one).
+	// CreateUser refuses an empty subject, so it is written straight into the
+	// buckets the way an upgraded record would be found.
+	seeded := users.NewUser("alice@example.com", "Alice Seed", "google", "placeholder")
+	seeded.ProviderSubjectID = ""
+	seeded.LastLoginAt = seeded.LastLoginAt.Add(-time.Hour)
+	raw, err := json.Marshal(seeded)
+	require.NoError(t, err)
+	require.NoError(t, rig.db.Update(func(tx *bbolt.Tx) error {
+		if err := tx.Bucket([]byte(users.BucketUsers)).Put([]byte(seeded.ID), raw); err != nil {
+			return err
+		}
+		return tx.Bucket([]byte(users.BucketUsersByEmail)).Put([]byte(seeded.Email), []byte(seeded.ID))
+	}))
+
+	resp := rig.login()
+	require.Equal(t, http.StatusFound, resp.StatusCode)
+	res := rig.lastResult()
+	assert.Equal(t, "ok", string(res.Reason))
+	assert.NotContains(t, flagsOf(res), "provider_rebound", "binding an empty subject is a bind, not a rebind")
+
+	after := rig.userByEmail("alice@example.com")
+	assert.Equal(t, seeded.ID, after.ID)
+	assert.Equal(t, "sub-A", after.ProviderSubjectID, "subject bound on login even though no avatar URL was sent")
+	assert.Equal(t, "google", after.Provider)
+	assert.Equal(t, "Alice", after.DisplayName)
+	assert.True(t, after.LastLoginAt.After(seeded.LastLoginAt))
+
+	// Second login, same subject: plain bind, last_login moves again.
+	time.Sleep(5 * time.Millisecond)
+	resp = rig.login()
+	require.Equal(t, http.StatusFound, resp.StatusCode)
+	assert.Equal(t, "ok", string(rig.lastResult().Reason))
+	again := rig.userByEmail("alice@example.com")
+	assert.Equal(t, "sub-A", again.ProviderSubjectID)
+	assert.True(t, again.LastLoginAt.After(after.LastLoginAt))
+}
+
+// --- FR-023: the armed window is consumed by the first successful login -------
+
+func TestSubjectRebind_ArmedWindowIsSingleUse(t *testing.T) {
+	idp := newSubjectIdP(t, "alice@example.com", "Alice", "sub-B")
+	rig := newSubjectRig(t, idp, subjectTestConfig())
+	seeded := seedUser(t, rig.store, "alice@example.com", "google", "sub-A")
+	rig.arm("alice@example.com")
+
+	resp := rig.login()
+	require.Equal(t, http.StatusFound, resp.StatusCode, "the first successful login inside the window rebinds")
+	res := rig.lastResult()
+	assert.Equal(t, "ok", string(res.Reason))
+	assert.Equal(t, seeded.ID, res.UserID)
+	assert.Contains(t, flagsOf(res), "provider_rebound")
+
+	after := rig.userByEmail("alice@example.com")
+	assert.Equal(t, "sub-B", after.ProviderSubjectID)
+	assert.Equal(t, "google", after.Provider)
+	assert.Nil(t, after.SubjectRebindArmedAt, "the flag is cleared in the same write as the rebind")
+
+	// Window closed: the next different subject is refused and nothing moves.
+	idp.setSubject("sub-C")
+	resp = rig.login()
+	assert.Equal(t, http.StatusForbidden, resp.StatusCode)
+	assert.Equal(t, "subject_mismatch", string(rig.lastResult().Reason))
+	closed := rig.userByEmail("alice@example.com")
+	assert.Equal(t, "sub-B", closed.ProviderSubjectID)
+	assert.Nil(t, closed.SubjectRebindArmedAt)
+
+	// The winner keeps logging in.
+	idp.setSubject("sub-B")
+	resp = rig.login()
+	assert.Equal(t, http.StatusFound, resp.StatusCode)
+	assert.Equal(t, "ok", string(rig.lastResult().Reason))
+}
+
+func TestSubjectRebind_ArmedWindowSurvivesRestart(t *testing.T) {
+	idp := newSubjectIdP(t, "alice@example.com", "Alice", "sub-B")
+	rig := newSubjectRig(t, idp, subjectTestConfig())
+	seeded := seedUser(t, rig.store, "alice@example.com", "google", "sub-A")
+	armedAt := rig.arm("alice@example.com")
+
+	rig.restart()
+
+	persisted := rig.userByEmail("alice@example.com")
+	require.NotNil(t, persisted.SubjectRebindArmedAt, "the window is persisted state, not inferred")
+	assert.True(t, persisted.SubjectRebindArmedAt.Equal(armedAt))
+
+	resp := rig.login()
+	require.Equal(t, http.StatusFound, resp.StatusCode)
+	res := rig.lastResult()
+	assert.Equal(t, "ok", string(res.Reason))
+	assert.Equal(t, seeded.ID, res.UserID)
+	assert.Contains(t, flagsOf(res), "provider_rebound")
+
+	after := rig.userByEmail("alice@example.com")
+	assert.Equal(t, "sub-B", after.ProviderSubjectID)
+	assert.Nil(t, after.SubjectRebindArmedAt)
+}
+
+func TestSubjectRebind_FailedAttemptDoesNotConsumeTheWindow(t *testing.T) {
+	idp := newSubjectIdP(t, "alice@example.com", "Alice", "sub-B")
+	rig := newSubjectRig(t, idp, subjectTestConfig())
+	seedUser(t, rig.store, "alice@example.com", "google", "sub-A")
+	armedAt := rig.arm("alice@example.com")
+
+	// First attempt fails before the store is consulted (userinfo down →
+	// provider_error, the 503 class of FR-024).
+	idp.setUserinfoFail(true)
+	resp := rig.login()
+	assert.Equal(t, http.StatusServiceUnavailable, resp.StatusCode)
+	assert.Nil(t, sessionCookie(resp))
+	res := rig.lastResult()
+	assert.Equal(t, "provider_error", string(res.Reason))
+	assert.Empty(t, res.UserID, "the store was never consulted on this path")
+
+	still := rig.userByEmail("alice@example.com")
+	require.NotNil(t, still.SubjectRebindArmedAt, "a failed attempt leaves the window open")
+	assert.True(t, still.SubjectRebindArmedAt.Equal(armedAt))
+	assert.Equal(t, "sub-A", still.ProviderSubjectID)
+
+	// Then the real login consumes it.
+	idp.setUserinfoFail(false)
+	resp = rig.login()
+	require.Equal(t, http.StatusFound, resp.StatusCode)
+	res = rig.lastResult()
+	assert.Equal(t, "ok", string(res.Reason))
+	assert.Contains(t, flagsOf(res), "provider_rebound")
+
+	after := rig.userByEmail("alice@example.com")
+	assert.Equal(t, "sub-B", after.ProviderSubjectID)
+	assert.Nil(t, after.SubjectRebindArmedAt)
+}
+
+// --- FR-023: two concurrent logins, two subjects → exactly one rebinds --------
+//
+// Driven through the store contract directly: UpdateUserLogin is
+// transaction-owned, so the second writer re-reads the record inside its own
+// db.Update, sees the flag already consumed, and refuses. A pre-mutated *User
+// handed to UpdateUser cannot do this (both callbacks would observe the armed
+// flag and rebind to different subjects).
+func TestUpdateUserLogin_ConcurrentRebindExactlyOneWins(t *testing.T) {
+	const iterations = 10
+
+	dbPath := filepath.Join(t.TempDir(), "concurrent.db")
+	db, err := bbolt.Open(dbPath, 0600, &bbolt.Options{Timeout: time.Second})
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = db.Close() })
+	store := users.NewUserStore(db)
+	require.NoError(t, store.EnsureBuckets())
+
+	seeded := seedUser(t, store, "alice@example.com", "google", "sub-A")
+
+	for i := 0; i < iterations; i++ {
+		// Re-arm and reset to the seed binding for every round.
+		u, err := store.GetUserByEmail("alice@example.com")
+		require.NoError(t, err)
+		require.NotNil(t, u)
+		u.ProviderSubjectID = "sub-A"
+		armedAt := time.Now().UTC()
+		u.SubjectRebindArmedAt = &armedAt
+		require.NoError(t, store.UpdateUser(u))
+
+		subjects := [2]string{fmt.Sprintf("sub-B-%d", i), fmt.Sprintf("sub-C-%d", i)}
+		var (
+			outcomes [2]users.LoginOutcome
+			errs     [2]error
+			wg       sync.WaitGroup
+			barrier  = make(chan struct{})
+		)
+		for k := 0; k < 2; k++ {
+			wg.Add(1)
+			go func(k int) {
+				defer wg.Done()
+				<-barrier // both calls start only after the flag is armed
+				outcomes[k], errs[k] = store.UpdateUserLogin(context.Background(), users.LoginClaims{
+					Email:       "alice@example.com",
+					Provider:    "google",
+					Subject:     subjects[k],
+					Name:        "Alice",
+					Groups:      []string{},
+					GroupsKnown: true,
+				})
+			}(k)
+		}
+		close(barrier)
+		wg.Wait()
+
+		winners := 0
+		var winnerSubject string
+		for k := 0; k < 2; k++ {
+			if errs[k] == nil {
+				winners++
+				winnerSubject = subjects[k]
+				assert.True(t, outcomes[k].Rebound, "round %d: the winner re-bound", i)
+				assert.True(t, outcomes[k].RebindConsumed, "round %d: the winner consumed the window", i)
+				assert.False(t, outcomes[k].Created)
+				require.NotNil(t, outcomes[k].User)
+				assert.Equal(t, seeded.ID, outcomes[k].User.ID)
+				assert.Equal(t, subjects[k], outcomes[k].User.ProviderSubjectID)
+				assert.Nil(t, outcomes[k].User.SubjectRebindArmedAt)
+			} else {
+				assert.True(t, errors.Is(errs[k], users.ErrSubjectMismatch),
+					"round %d: the loser is a subject mismatch, got %v", i, errs[k])
+			}
+		}
+		require.Equal(t, 1, winners, "round %d: exactly one of two concurrent logins rebinds (errors: %v, %v)", i, errs[0], errs[1])
+
+		stored, err := store.GetUserByEmail("alice@example.com")
+		require.NoError(t, err)
+		require.NotNil(t, stored)
+		assert.Equal(t, winnerSubject, stored.ProviderSubjectID, "round %d: the stored subject is the winner's", i)
+		assert.Nil(t, stored.SubjectRebindArmedAt, "round %d: the window is closed", i)
+		assert.Equal(t, "google", stored.Provider)
+	}
+}
+
+// --- users.(*UserStore).UpdateUserLogin outcomes -----------------------------
+
+func TestUpdateUserLogin_Outcomes(t *testing.T) {
+	newStore := func(t *testing.T) *users.UserStore {
+		t.Helper()
+		db, err := bbolt.Open(filepath.Join(t.TempDir(), "outcomes.db"), 0600, &bbolt.Options{Timeout: time.Second})
+		require.NoError(t, err)
+		t.Cleanup(func() { _ = db.Close() })
+		store := users.NewUserStore(db)
+		require.NoError(t, store.EnsureBuckets())
+		return store
+	}
+	claims := func(provider, sub string, groups ...string) users.LoginClaims {
+		return users.LoginClaims{
+			Email:       "Alice@Example.com", // normalised by the store
+			Provider:    provider,
+			Subject:     sub,
+			Name:        "Alice",
+			AvatarURL:   "",
+			Groups:      groups,
+			GroupsKnown: true,
+		}
+	}
+	ctx := context.Background()
+
+	t.Run("first login creates the record bound to (provider, sub)", func(t *testing.T) {
+		store := newStore(t)
+		out, err := store.UpdateUserLogin(ctx, claims("google", "sub-A", "eng"))
+		require.NoError(t, err)
+		assert.True(t, out.Created)
+		assert.False(t, out.Rebound)
+		assert.False(t, out.RebindConsumed)
+		require.NotNil(t, out.User)
+		assert.Equal(t, "alice@example.com", out.User.Email)
+		assert.Equal(t, "google", out.User.Provider)
+		assert.Equal(t, "sub-A", out.User.ProviderSubjectID)
+		assert.Equal(t, []string{"eng"}, out.User.Groups)
+		assert.False(t, out.User.GroupsUpdatedAt.IsZero())
+		assert.Nil(t, out.User.SubjectRebindArmedAt)
+
+		stored, err := store.GetUserByEmail("alice@example.com")
+		require.NoError(t, err)
+		require.NotNil(t, stored)
+		assert.Equal(t, out.User.ID, stored.ID)
+	})
+
+	t.Run("same subject binds and refreshes last_login and groups wholesale", func(t *testing.T) {
+		store := newStore(t)
+		seeded := seedUser(t, store, "alice@example.com", "google", "sub-A")
+		out, err := store.UpdateUserLogin(ctx, claims("google", "sub-A", "ops"))
+		require.NoError(t, err)
+		assert.False(t, out.Created)
+		assert.False(t, out.Rebound)
+		assert.False(t, out.RebindConsumed)
+		assert.Equal(t, seeded.ID, out.User.ID)
+		assert.True(t, out.User.LastLoginAt.After(seeded.LastLoginAt))
+		assert.Equal(t, []string{"ops"}, out.User.Groups)
+
+		out, err = store.UpdateUserLogin(ctx, claims("google", "sub-A"))
+		require.NoError(t, err)
+		assert.Equal(t, []string{}, out.User.Groups, "an empty list replaces the previous one wholesale")
+	})
+
+	t.Run("provider change rebinds without an armed window", func(t *testing.T) {
+		store := newStore(t)
+		seeded := seedUser(t, store, "alice@example.com", "github", "gh-1")
+		out, err := store.UpdateUserLogin(ctx, claims("google", "g-1"))
+		require.NoError(t, err)
+		assert.True(t, out.Rebound)
+		assert.False(t, out.RebindConsumed, "no window existed to consume")
+		assert.Equal(t, seeded.ID, out.User.ID)
+		assert.Equal(t, "google", out.User.Provider)
+		assert.Equal(t, "g-1", out.User.ProviderSubjectID)
+	})
+
+	t.Run("different subject without a window is refused and writes nothing", func(t *testing.T) {
+		store := newStore(t)
+		seedUser(t, store, "alice@example.com", "google", "sub-A")
+		before, err := store.GetUserByEmail("alice@example.com")
+		require.NoError(t, err)
+
+		_, err = store.UpdateUserLogin(ctx, claims("google", "sub-B", "eng"))
+		require.Error(t, err)
+		assert.True(t, errors.Is(err, users.ErrSubjectMismatch), "got %v", err)
+
+		after, err := store.GetUserByEmail("alice@example.com")
+		require.NoError(t, err)
+		assert.Equal(t, before, after, "nothing written on a mismatch — not even groups or last_login")
+	})
+
+	t.Run("different subject with the window armed rebinds and clears it", func(t *testing.T) {
+		store := newStore(t)
+		seeded := seedUser(t, store, "alice@example.com", "google", "sub-A")
+		armedAt := time.Now().UTC()
+		seeded.SubjectRebindArmedAt = &armedAt
+		require.NoError(t, store.UpdateUser(seeded))
+
+		out, err := store.UpdateUserLogin(ctx, claims("google", "sub-B"))
+		require.NoError(t, err)
+		assert.True(t, out.Rebound)
+		assert.True(t, out.RebindConsumed)
+		assert.Equal(t, "sub-B", out.User.ProviderSubjectID)
+		assert.Nil(t, out.User.SubjectRebindArmedAt)
+
+		stored, err := store.GetUserByEmail("alice@example.com")
+		require.NoError(t, err)
+		assert.Nil(t, stored.SubjectRebindArmedAt)
+		assert.Equal(t, "sub-B", stored.ProviderSubjectID)
+	})
+
+	// FR-023: "the first successful login" while armed "carries provider_rebound
+	// in the line's flags" — unconditionally, not only when the presented
+	// subject differs from the stored one. A same-subject login while armed
+	// still consumes (and must still flag) the administrator-opened window, or
+	// its consumption leaves no audit trace at all (RebindConsumed is not
+	// logged anywhere; provider_rebound is the only signal, cross-review round 3).
+	t.Run("same subject with the window armed still consumes and flags it", func(t *testing.T) {
+		store := newStore(t)
+		seeded := seedUser(t, store, "alice@example.com", "google", "sub-A")
+		armedAt := time.Now().UTC()
+		seeded.SubjectRebindArmedAt = &armedAt
+		require.NoError(t, store.UpdateUser(seeded))
+
+		out, err := store.UpdateUserLogin(ctx, claims("google", "sub-A"))
+		require.NoError(t, err)
+		assert.True(t, out.Rebound, "the window's consumption is itself the reportable event")
+		assert.True(t, out.RebindConsumed)
+		assert.Equal(t, "sub-A", out.User.ProviderSubjectID)
+		assert.Nil(t, out.User.SubjectRebindArmedAt)
+
+		stored, err := store.GetUserByEmail("alice@example.com")
+		require.NoError(t, err)
+		assert.Nil(t, stored.SubjectRebindArmedAt)
+	})
+
+	t.Run("disabled record is refused untouched", func(t *testing.T) {
+		store := newStore(t)
+		seeded := seedUser(t, store, "alice@example.com", "google", "sub-A")
+		seeded.Disabled = true
+		require.NoError(t, store.UpdateUser(seeded))
+		before, err := store.GetUserByEmail("alice@example.com")
+		require.NoError(t, err)
+
+		_, err = store.UpdateUserLogin(ctx, claims("google", "sub-A"))
+		require.Error(t, err)
+		assert.True(t, errors.Is(err, users.ErrUserDisabled), "got %v", err)
+
+		after, err := store.GetUserByEmail("alice@example.com")
+		require.NoError(t, err)
+		assert.Equal(t, before, after)
+	})
+}
+
+// --- T044: the login role is derived from the CURRENT admin_emails ----------
+//
+// Two distinct config pointers, swapped after the handler was built: a handler
+// that captured the boot pointer answers with the stale role.
+func TestLoginRole_DerivedFromLiveAdminEmails(t *testing.T) {
+	idp := newSubjectIdP(t, "alice@example.com", "Alice", "sub-A")
+	boot := subjectTestConfig() // nobody is an admin
+	rig := newSubjectRig(t, idp, boot)
+
+	resp := rig.login()
+	require.Equal(t, http.StatusFound, resp.StatusCode)
+	assert.Equal(t, "ok", string(rig.lastResult().Reason))
+	assert.Equal(t, "user", rig.roleOf(resp))
+
+	// Hot-reload: promote alice on a NEW config value.
+	rig.live.swap(subjectTestConfig("alice@example.com"))
+	resp = rig.login()
+	require.Equal(t, http.StatusFound, resp.StatusCode)
+	assert.Equal(t, "ok", string(rig.lastResult().Reason))
+	assert.Equal(t, "admin", rig.roleOf(resp), "the role comes from the current admin_emails, not the boot pointer")
+
+	// Hot-reload: demote again.
+	rig.live.swap(subjectTestConfig())
+	resp = rig.login()
+	require.Equal(t, http.StatusFound, resp.StatusCode)
+	assert.Equal(t, "ok", string(rig.lastResult().Reason))
+	assert.Equal(t, "user", rig.roleOf(resp), "a demotion takes effect on the very next login")
+}
diff --git a/internal/serveredition/auth/oauth_handler_test.go b/internal/serveredition/auth/oauth_handler_test.go
index 497e8a42a..6c958fea0 100644
--- a/internal/serveredition/auth/oauth_handler_test.go
+++ b/internal/serveredition/auth/oauth_handler_test.go
@@ -3,8 +3,10 @@
 package auth
 
 import (
+	"context"
 	"encoding/json"
 	"fmt"
+	"io"
 	"net/http"
 	"net/http/httptest"
 	"net/url"
@@ -46,7 +48,7 @@ func setupTestOAuthHandler(t *testing.T, oauthCfg *config.ServerEditionOAuthConf
 	logger := zap.NewNop().Sugar()
 	hmacKey := []byte("test-hmac-key-for-jwt-signing-32b")
 
-	handler := NewOAuthHandler(store, sessionMgr, teamsCfg, hmacKey, logger)
+	handler := NewOAuthHandler(store, sessionMgr, StaticServerEditionConfig(teamsCfg), hmacKey, logger)
 	return handler, store
 }
 
@@ -99,7 +101,7 @@ func registerMockProvider(t *testing.T, mockServer *httptest.Server) {
 
 	originalFactory := providerRegistry["google"]
 
-	providerRegistry["google"] = func(_ string) *OAuthProvider {
+	providerRegistry["google"] = func(_ *config.ServerEditionOAuthConfig) *OAuthProvider {
 		return &OAuthProvider{
 			Name:         "google",
 			AuthURL:      mockServer.URL + "/authorize",
@@ -175,7 +177,7 @@ func TestHandleLogin_StoreIDPTokensTrueStillNeverRequestsOfflineAccess(t *testin
 		ClientID:     "test-client-id",
 		ClientSecret: "test-client-secret",
 	})
-	handler.config.StoreIDPTokens = true
+	handler.config().StoreIDPTokens = true
 
 	req := httptest.NewRequest(http.MethodGet, "/api/v1/auth/login", nil)
 	w := httptest.NewRecorder()
@@ -318,12 +320,13 @@ func TestHandleCallback_InvalidState(t *testing.T) {
 	resp := w.Result()
 	defer resp.Body.Close()
 
-	assert.Equal(t, http.StatusBadRequest, resp.StatusCode)
-
-	var errResp map[string]interface{}
-	err := json.NewDecoder(resp.Body).Decode(&errResp)
+	// Spec 107 FR-024: every refusal (here state_invalid) renders the one
+	// generic 403 page; the reason reaches the log only.
+	assert.Equal(t, http.StatusForbidden, resp.StatusCode)
+	body, err := io.ReadAll(resp.Body)
 	require.NoError(t, err)
-	assert.Contains(t, errResp["message"], "invalid or expired state")
+	assert.Contains(t, string(body), "Sign-in was not permitted")
+	assert.NotContains(t, string(body), "state_invalid")
 }
 
 func TestHandleCallback_MissingCode(t *testing.T) {
@@ -345,12 +348,39 @@ func TestHandleCallback_MissingCode(t *testing.T) {
 	resp := w.Result()
 	defer resp.Body.Close()
 
-	assert.Equal(t, http.StatusBadRequest, resp.StatusCode)
+	// Spec 107 FR-024: an unknown state is state_invalid on the generic 403
+	// page, never a distinct 400 that discloses which parameter was missing.
+	assert.Equal(t, http.StatusForbidden, resp.StatusCode)
+	body, err := io.ReadAll(resp.Body)
+	require.NoError(t, err)
+	assert.Contains(t, string(body), "Sign-in was not permitted")
+}
 
-	var errResp map[string]interface{}
-	err := json.NewDecoder(resp.Body).Decode(&errResp)
+// A broken provider config (h.providerErr set at construction, restart-pinned
+// for the handler's lifetime) must not let the callback bypass the
+// state-first contract the HandleCallback doc comment promises: an unknown
+// state is state_invalid regardless of provider availability, not a 503 that
+// tells an unauthenticated caller OAuth is misconfigured before their state
+// is even looked at (cross-review round 7, chunk 2 P3).
+func TestHandleCallback_BrokenProviderStillStateFirst(t *testing.T) {
+	handler, _ := setupTestOAuthHandler(t, &config.ServerEditionOAuthConfig{
+		Provider: "not-a-real-provider",
+	})
+	require.Error(t, handler.providerErr, "the bad provider name must have failed construction")
+
+	req := httptest.NewRequest(http.MethodGet,
+		"/api/v1/auth/callback?code=whatever&state=unknown-state", nil)
+	w := httptest.NewRecorder()
+
+	handler.HandleCallback(w, req)
+
+	resp := w.Result()
+	defer resp.Body.Close()
+
+	assert.Equal(t, http.StatusForbidden, resp.StatusCode, "state_invalid, not the 503 unavailable page")
+	body, err := io.ReadAll(resp.Body)
 	require.NoError(t, err)
-	assert.Contains(t, errResp["message"], "missing code")
+	assert.Contains(t, string(body), "Sign-in was not permitted")
 }
 
 func TestHandleCallback_DomainNotAllowed(t *testing.T) {
@@ -384,12 +414,13 @@ func TestHandleCallback_DomainNotAllowed(t *testing.T) {
 	resp := w.Result()
 	defer resp.Body.Close()
 
+	// Spec 107 FR-024: domain_not_allowed renders the generic 403 page; the
+	// reason is never disclosed to the caller.
 	assert.Equal(t, http.StatusForbidden, resp.StatusCode)
-
-	var errResp map[string]interface{}
-	err := json.NewDecoder(resp.Body).Decode(&errResp)
+	body, err := io.ReadAll(resp.Body)
 	require.NoError(t, err)
-	assert.Contains(t, errResp["message"], "domain not allowed")
+	assert.Contains(t, string(body), "Sign-in was not permitted")
+	assert.NotContains(t, string(body), "domain")
 }
 
 func TestHandleCallback_ExistingUser(t *testing.T) {
@@ -633,37 +664,76 @@ func TestIsDomainAllowed(t *testing.T) {
 	}
 }
 
-func TestBuildCallbackURL(t *testing.T) {
+// TestCallbackURL pins the Spec 107 FR-025/FR-027 callback resolution: Host
+// and the listener scheme by default; X-Forwarded-Proto/-Host only from a
+// trusted proxy; public_url wins over everything.
+func TestCallbackURL(t *testing.T) {
+	oauthCfg := &config.ServerEditionOAuthConfig{Provider: "google", ClientID: "test-client-id", ClientSecret: "test-client-secret"}
 	tests := []struct {
-		name     string
-		host     string
-		tls      bool
-		xProto   string
-		expected string
+		name      string
+		host      string
+		xProto    string
+		trusted   []string
+		publicURL string
+		expected  string
 	}{
-		{
-			name:     "http localhost",
-			host:     "localhost:8080",
-			expected: "http://localhost:8080/api/v1/auth/callback",
-		},
-		{
-			name:     "with X-Forwarded-Proto",
-			host:     "app.example.com",
-			xProto:   "https",
-			expected: "https://app.example.com/api/v1/auth/callback",
-		},
+		{name: "http localhost", host: "localhost:8080", expected: "http://localhost:8080/api/v1/auth/callback"},
+		{name: "untrusted X-Forwarded-Proto is ignored", host: "app.example.com", xProto: "https", expected: "http://app.example.com/api/v1/auth/callback"},
+		{name: "trusted X-Forwarded-Proto is honoured", host: "app.example.com", xProto: "https", trusted: []string{"192.0.2.1"}, expected: "https://app.example.com/api/v1/auth/callback"},
+		{name: "public_url wins", host: "evil.example", xProto: "http", trusted: []string{"192.0.2.1"}, publicURL: "https://sso.example.com", expected: "https://sso.example.com/api/v1/auth/callback"},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
+			handler, _ := setupTestOAuthHandler(t, oauthCfg)
+			handler.publicURL = tt.publicURL
+			handler.SetTrustedProxiesProvider(func() []string { return tt.trusted })
+
 			req := httptest.NewRequest(http.MethodGet, "/api/v1/auth/callback", nil)
 			req.Host = tt.host
+			req.RemoteAddr = "192.0.2.1:4444"
 			if tt.xProto != "" {
 				req.Header.Set("X-Forwarded-Proto", tt.xProto)
 			}
 
-			result := buildCallbackURL(req)
-			assert.Equal(t, tt.expected, result)
+			assert.Equal(t, tt.expected, handler.CallbackURL(req))
 		})
 	}
 }
+
+// Spec 107 cross-review round 6, chunk 3 P2: NewOAuthHandler must resolve a
+// `${env:...}` server_edition.oauth.client_secret/client_id reference into
+// its own private, never-persisted h.oauthCfg clone — config.LoadFromFile
+// deliberately stops short of resolving it into the Config object that is
+// round-tripped back to disk by SaveConfig on every later PATCH/apply, so
+// this handler-construction step is the only place the actual secret is
+// produced for the token endpoint. Proved by driving a real authorization
+// code exchange through mockOAuthProviderServer's /token endpoint, which
+// only succeeds if the handler sent the resolved value, not the literal
+// "${env:...}" text.
+func TestNewOAuthHandler_ResolvesEnvSecretRefForTokenExchange(t *testing.T) {
+	t.Setenv("MCPPROXY_TEST_HANDLER_OIDC_SECRET", "resolved-secret-value")
+
+	provider := mockOAuthProviderServer(t, "alice@example.com", "Alice", "alice-sub")
+	defer provider.Close()
+
+	oauthCfg := &config.ServerEditionOAuthConfig{
+		Provider:     "google",
+		ClientID:     "${env:MCPPROXY_TEST_HANDLER_OIDC_SECRET}", // exercise both fields
+		ClientSecret: "${env:MCPPROXY_TEST_HANDLER_OIDC_SECRET}",
+	}
+	handler, _ := setupTestOAuthHandler(t, oauthCfg)
+	require.NoError(t, handler.providerErr, "the handler must resolve the reference, not fail construction")
+	require.NotNil(t, handler.oauthCfg)
+	assert.Equal(t, "resolved-secret-value", handler.oauthCfg.ClientSecret,
+		"the handler's own clone must carry the resolved value")
+	assert.Equal(t, "resolved-secret-value", handler.oauthCfg.ClientID)
+
+	handler.provider.TokenURL = provider.URL + "/token"
+	handler.provider.UserInfoURL = provider.URL + "/userinfo"
+
+	tokenResp, err := handler.provider.ExchangeCode(context.Background(), "test-code", "http://localhost/callback",
+		handler.oauthCfg.ClientID, handler.oauthCfg.ClientSecret, "")
+	require.NoError(t, err, "the token exchange must succeed with the resolved secret")
+	assert.Equal(t, "mock-access-token", tokenResp.AccessToken)
+}
diff --git a/internal/serveredition/auth/oauth_providers.go b/internal/serveredition/auth/oauth_providers.go
index 8451969d2..fc2a4672c 100644
--- a/internal/serveredition/auth/oauth_providers.go
+++ b/internal/serveredition/auth/oauth_providers.go
@@ -13,9 +13,17 @@ import (
 	"strconv"
 	"strings"
 	"time"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
 )
 
 // OAuthProvider defines the OAuth endpoints and behavior for an identity provider.
+//
+// The three legacy providers (google, github, microsoft) are static endpoint
+// sets. The generic `oidc` provider (Spec 107 FR-020) carries its state in
+// the unexported oidc field: endpoints come from lazy discovery and the ID
+// token is verified against the issuer's JWKS, so AuthURL/TokenURL/
+// UserInfoURL stay empty for it.
 type OAuthProvider struct {
 	Name         string
 	AuthURL      string
@@ -25,8 +33,14 @@ type OAuthProvider struct {
 	Scopes       []string
 	SupportsOIDC bool // If true, ID token contains user info
 	SupportsPKCE bool
+
+	oidc *oidcProvider // non-nil for the generic `oidc` provider only
 }
 
+// IsGenericOIDC reports whether the provider is the discovery-based `oidc`
+// provider with a verified ID token (as opposed to a legacy provider).
+func (p *OAuthProvider) IsGenericOIDC() bool { return p != nil && p.oidc != nil }
+
 // TokenResponse represents the OAuth token exchange response.
 type TokenResponse struct {
 	AccessToken  string `json:"access_token"`
@@ -43,13 +57,56 @@ type OAuthUserInfo struct {
 	DisplayName string
 	SubjectID   string // Provider-unique user identifier
 	AvatarURL   string
+
+	// Groups is the verified groups claim of an `oidc` login (Spec 107
+	// FR-008); nil for the legacy providers, which store [].
+	Groups []string
+	// EmailVerified is the `email_verified` claim; nil when absent.
+	EmailVerified *bool
 }
 
-// providerRegistry holds the built-in provider configurations.
-var providerRegistry = map[string]func(tenantID string) *OAuthProvider{
-	"google":    newGoogleProvider,
-	"github":    newGitHubProvider,
-	"microsoft": newMicrosoftProvider,
+// providerRegistry holds the built-in provider factories, keyed by the
+// `server_edition.oauth.provider` value. A factory takes the whole OAuth
+// block (Spec 107 FR-020); the legacy factories read nothing but TenantID.
+// Tests swap an entry to point a provider at a mock; the handler resolves the
+// provider ONCE at construction, so a swap must precede NewOAuthHandler.
+var providerRegistry = map[string]func(*config.ServerEditionOAuthConfig) *OAuthProvider{
+	"google":    func(*config.ServerEditionOAuthConfig) *OAuthProvider { return newGoogleProvider("") },
+	"github":    func(*config.ServerEditionOAuthConfig) *OAuthProvider { return newGitHubProvider("") },
+	"microsoft": func(c *config.ServerEditionOAuthConfig) *OAuthProvider { return newMicrosoftProvider(c.TenantID) },
+	"oidc":      newGenericOIDCProvider,
+}
+
+// newGenericOIDCProvider builds the discovery-based provider. No network I/O
+// happens here: discovery is lazy on the first login.
+func newGenericOIDCProvider(c *config.ServerEditionOAuthConfig) *OAuthProvider {
+	cfg := *c
+	cfg.Scopes = append([]string(nil), c.Scopes...)
+	cfg.AllowedDomains = append([]string(nil), c.AllowedDomains...)
+	if len(cfg.Scopes) == 0 {
+		cfg.Scopes = []string{"openid", "profile", "email"}
+	} else if !containsExactOIDC(cfg.Scopes, "openid") {
+		// FR-020 requires "openid" on every oidc authorization request. This
+		// factory must not assume its input already passed through
+		// config.ServerEditionConfig.ApplyDefaults() — the OAuthHandler is
+		// constructed from the LIVE, non-defaulted block whenever a
+		// ConfigProvider is wired (internal/serveredition/setup.go's
+		// serverEditionConfig provider prefers live.ServerEdition over the
+		// defaulted clone), so an explicit `scopes` list missing "openid"
+		// would otherwise reach the authorization request unchanged and a
+		// compliant IdP would return no ID token.
+		cfg.Scopes = append(append([]string(nil), cfg.Scopes...), "openid")
+	}
+	if cfg.GroupsClaim == "" {
+		cfg.GroupsClaim = "groups"
+	}
+	return &OAuthProvider{
+		Name:         "oidc",
+		Scopes:       cfg.Scopes,
+		SupportsOIDC: true,
+		SupportsPKCE: true,
+		oidc:         newOIDCProvider(&cfg),
+	}
 }
 
 func newGoogleProvider(_ string) *OAuthProvider {
@@ -94,12 +151,23 @@ func newMicrosoftProvider(tenantID string) *OAuthProvider {
 
 // GetProvider returns a provider configuration by name.
 // For Microsoft, tenantID specifies the Azure AD tenant; empty defaults to "common".
+// The generic `oidc` provider needs the whole OAuth block: use
+// GetProviderFromConfig.
 func GetProvider(name string, tenantID string) (*OAuthProvider, error) {
-	factory, ok := providerRegistry[strings.ToLower(name)]
+	return GetProviderFromConfig(&config.ServerEditionOAuthConfig{Provider: name, TenantID: tenantID})
+}
+
+// GetProviderFromConfig resolves the provider named by cfg.Provider through
+// the registry. Construction never touches the network.
+func GetProviderFromConfig(cfg *config.ServerEditionOAuthConfig) (*OAuthProvider, error) {
+	if cfg == nil {
+		return nil, fmt.Errorf("OAuth not configured")
+	}
+	factory, ok := providerRegistry[strings.ToLower(cfg.Provider)]
 	if !ok {
-		return nil, fmt.Errorf("unknown OAuth provider: %q (supported: google, github, microsoft)", name)
+		return nil, fmt.Errorf("unknown OAuth provider: %q (supported: google, github, microsoft, oidc)", cfg.Provider)
 	}
-	return factory(tenantID), nil
+	return factory(cfg), nil
 }
 
 // BuildAuthURL constructs the authorization URL with the required query
@@ -414,6 +482,21 @@ func parseIDToken(idToken string) (*OAuthUserInfo, error) {
 	}, nil
 }
 
+// containsExactOIDC reports whether list contains want by exact string
+// match. OAuth/OIDC scope values are case-sensitive (RFC 6749 §3.3), so an
+// operator-configured lookalike of a different case must not be treated as
+// satisfying the FR-020 requirement that "openid" be present on every oidc
+// authorization request (cross-review round 6, chunk 1 P2). Mirrors
+// config.containsExact (unexported in another package).
+func containsExactOIDC(list []string, want string) bool {
+	for _, v := range list {
+		if v == want {
+			return true
+		}
+	}
+	return false
+}
+
 // base64URLDecode decodes a base64url-encoded string with optional padding.
 func base64URLDecode(s string) ([]byte, error) {
 	// Add padding if needed
diff --git a/internal/serveredition/auth/oauth_providers_test.go b/internal/serveredition/auth/oauth_providers_test.go
index 31896424c..ad4a88649 100644
--- a/internal/serveredition/auth/oauth_providers_test.go
+++ b/internal/serveredition/auth/oauth_providers_test.go
@@ -14,6 +14,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -69,6 +70,33 @@ func TestGetProvider_Microsoft(t *testing.T) {
 	})
 }
 
+func TestNewGenericOIDCProvider_ForcesOpenIDScope(t *testing.T) {
+	// FR-020 requires "openid" on every oidc authorization request. An
+	// operator who sets `scopes: ["profile", "email"]` explicitly (no
+	// "openid") must still get it added — the OAuthHandler resolves the
+	// provider from the live, non-defaulted config.ServerEditionConfig
+	// (internal/serveredition/setup.go's serverEditionConfig provider
+	// prefers ConfigProvider()'s live block over the ApplyDefaults'd
+	// clone), so newGenericOIDCProvider itself must not assume its input
+	// has already been through ApplyDefaults.
+	cfg := &config.ServerEditionOAuthConfig{
+		Provider:  "oidc",
+		IssuerURL: "https://idp.example.com",
+		Scopes:    []string{"profile", "email"},
+	}
+	p := newGenericOIDCProvider(cfg)
+	assert.Contains(t, p.Scopes, "openid", "explicit scopes without openid must still get it injected")
+}
+
+func TestNewGenericOIDCProvider_EmptyScopesDefaultsIncludeOpenID(t *testing.T) {
+	cfg := &config.ServerEditionOAuthConfig{
+		Provider:  "oidc",
+		IssuerURL: "https://idp.example.com",
+	}
+	p := newGenericOIDCProvider(cfg)
+	assert.Contains(t, p.Scopes, "openid")
+}
+
 func TestGetProvider_Invalid(t *testing.T) {
 	_, err := GetProvider("unknown", "")
 	require.Error(t, err)
diff --git a/internal/serveredition/auth/oidc_discovery_issuer_test.go b/internal/serveredition/auth/oidc_discovery_issuer_test.go
new file mode 100644
index 000000000..807bbba45
--- /dev/null
+++ b/internal/serveredition/auth/oidc_discovery_issuer_test.go
@@ -0,0 +1,58 @@
+//go:build server
+
+package auth
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+)
+
+// A discovery document whose issuer does not byte-for-byte equal the
+// configured issuer_url must refuse the login as discovery_failed AND name
+// both values in the operator-facing check text — spec.md's Edge Cases
+// section promises "the log line names both values (they are not secrets)
+// with the fix", and docs/development/server-edition-multiuser-auth.md and
+// docs/configuration/config-file.md both describe the same behaviour, but the
+// code only ever said "discovery issuer does not equal issuer_url" with
+// neither value (cross-review round 7, chunk 3 P3).
+func TestOIDCDiscovery_IssuerMismatchNamesBothValues(t *testing.T) {
+	var issuerURL string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/.well-known/openid-configuration" {
+			http.NotFound(w, r)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{
+			"issuer": "` + issuerURL + `/wrong-path",
+			"authorization_endpoint": "` + issuerURL + `/authorize",
+			"token_endpoint": "` + issuerURL + `/token",
+			"jwks_uri": "` + issuerURL + `/jwks",
+			"token_endpoint_auth_methods_supported": ["client_secret_basic"],
+			"id_token_signing_alg_values_supported": ["RS256"]
+		}`))
+	}))
+	defer srv.Close()
+	issuerURL = srv.URL
+
+	prov := newOIDCProvider(&config.ServerEditionOAuthConfig{
+		IssuerURL:           issuerURL,
+		AllowInsecureIssuer: true,
+	})
+
+	_, err := prov.discover(context.Background())
+	require.Error(t, err)
+
+	var oe *oidcError
+	require.ErrorAs(t, err, &oe)
+	assert.Equal(t, LoginDiscoveryFailed, oe.reason)
+	assert.Contains(t, oe.check, issuerURL+"/wrong-path", "names the discovered issuer")
+	assert.Contains(t, oe.check, issuerURL, "names the configured issuer_url")
+}
diff --git a/internal/serveredition/auth/oidc_jwks.go b/internal/serveredition/auth/oidc_jwks.go
new file mode 100644
index 000000000..17e4bf510
--- /dev/null
+++ b/internal/serveredition/auth/oidc_jwks.go
@@ -0,0 +1,142 @@
+//go:build server
+
+package auth
+
+// Stdlib JWK Set parsing for the generic `oidc` provider (Spec 107 FR-020,
+// research D3): RSA (`n`,`e`) and EC (`crv`,`x`,`y`) public keys only, keyed
+// by `kid`. Anything else — symmetric `oct`, `OKP`, an unknown curve, a
+// malformed coordinate, a point off its curve — is refused per entry, and a
+// refused or kid-less entry is skipped so one exotic key cannot take a whole
+// set with it. The algorithm is decided by the verifier's allowed-alg list,
+// never by a JWK's `alg`/`use`.
+
+import (
+	"crypto"
+	"crypto/ecdh"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rsa"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"math/big"
+)
+
+// jwk is the subset of RFC 7517/7518 a signing key needs.
+type jwk struct {
+	Kty string `json:"kty"`
+	Kid string `json:"kid"`
+	Use string `json:"use"`
+	Alg string `json:"alg"`
+	N   string `json:"n"`
+	E   string `json:"e"`
+	Crv string `json:"crv"`
+	X   string `json:"x"`
+	Y   string `json:"y"`
+}
+
+// parseJWKS decodes a JWK Set document into kid → public key. The document
+// must be a JSON object with a `keys` array; entries that are not usable
+// signing keys or carry no kid are skipped. A duplicate kid keeps the last
+// entry (deterministic, never an error).
+func parseJWKS(data []byte) (map[string]crypto.PublicKey, error) {
+	var doc struct {
+		Keys *[]json.RawMessage `json:"keys"`
+	}
+	if err := json.Unmarshal(data, &doc); err != nil {
+		return nil, fmt.Errorf("jwks: decoding document: %w", err)
+	}
+	if doc.Keys == nil {
+		return nil, fmt.Errorf("jwks: document has no keys array")
+	}
+	keys := make(map[string]crypto.PublicKey, len(*doc.Keys))
+	for _, raw := range *doc.Keys {
+		var k jwk
+		if err := json.Unmarshal(raw, &k); err != nil {
+			return nil, fmt.Errorf("jwks: decoding key entry: %w", err)
+		}
+		if k.Kid == "" {
+			continue
+		}
+		pub, err := jwkToPublicKey(k)
+		if err != nil {
+			continue
+		}
+		keys[k.Kid] = pub
+	}
+	return keys, nil
+}
+
+// jwkToPublicKey converts one JWK into an *rsa.PublicKey or *ecdsa.PublicKey.
+func jwkToPublicKey(k jwk) (crypto.PublicKey, error) {
+	switch k.Kty {
+	case "RSA":
+		return rsaFromJWK(k)
+	case "EC":
+		return ecFromJWK(k)
+	default:
+		return nil, fmt.Errorf("jwk: unsupported kty %q", k.Kty)
+	}
+}
+
+func rsaFromJWK(k jwk) (crypto.PublicKey, error) {
+	if k.N == "" || k.E == "" {
+		return nil, fmt.Errorf("jwk: RSA key needs n and e")
+	}
+	nBytes, err := base64.RawURLEncoding.DecodeString(k.N)
+	if err != nil {
+		return nil, fmt.Errorf("jwk: RSA n: %w", err)
+	}
+	eBytes, err := base64.RawURLEncoding.DecodeString(k.E)
+	if err != nil {
+		return nil, fmt.Errorf("jwk: RSA e: %w", err)
+	}
+	if len(eBytes) == 0 || len(eBytes) > 4 {
+		return nil, fmt.Errorf("jwk: RSA e has %d bytes", len(eBytes))
+	}
+	n := new(big.Int).SetBytes(nBytes)
+	e := new(big.Int).SetBytes(eBytes)
+	if n.Sign() <= 0 || n.BitLen() < 512 || e.Int64() < 3 {
+		return nil, fmt.Errorf("jwk: RSA modulus or exponent out of range")
+	}
+	return &rsa.PublicKey{N: n, E: int(e.Int64())}, nil
+}
+
+func ecFromJWK(k jwk) (crypto.PublicKey, error) {
+	var (
+		curve elliptic.Curve
+		check ecdh.Curve
+	)
+	switch k.Crv {
+	case "P-256":
+		curve, check = elliptic.P256(), ecdh.P256()
+	case "P-384":
+		curve, check = elliptic.P384(), ecdh.P384()
+	case "P-521":
+		curve, check = elliptic.P521(), ecdh.P521()
+	default:
+		return nil, fmt.Errorf("jwk: unsupported EC curve %q", k.Crv)
+	}
+	if k.X == "" || k.Y == "" {
+		return nil, fmt.Errorf("jwk: EC key needs x and y")
+	}
+	xBytes, err := base64.RawURLEncoding.DecodeString(k.X)
+	if err != nil {
+		return nil, fmt.Errorf("jwk: EC x: %w", err)
+	}
+	yBytes, err := base64.RawURLEncoding.DecodeString(k.Y)
+	if err != nil {
+		return nil, fmt.Errorf("jwk: EC y: %w", err)
+	}
+	size := (curve.Params().BitSize + 7) / 8
+	if len(xBytes) != size || len(yBytes) != size {
+		return nil, fmt.Errorf("jwk: EC coordinates must be %d bytes for %s", size, k.Crv)
+	}
+	// crypto/ecdh refuses the identity and any point off the curve; it is the
+	// non-deprecated on-curve check.
+	uncompressed := append(append([]byte{4}, xBytes...), yBytes...)
+	if _, err := check.NewPublicKey(uncompressed); err != nil {
+		return nil, fmt.Errorf("jwk: EC point is not on %s: %w", k.Crv, err)
+	}
+	return &ecdsa.PublicKey{Curve: curve, X: new(big.Int).SetBytes(xBytes), Y: new(big.Int).SetBytes(yBytes)}, nil
+}
diff --git a/internal/serveredition/auth/oidc_jwks_test.go b/internal/serveredition/auth/oidc_jwks_test.go
new file mode 100644
index 000000000..ff2b54a07
--- /dev/null
+++ b/internal/serveredition/auth/oidc_jwks_test.go
@@ -0,0 +1,349 @@
+//go:build server
+
+package auth
+
+// Spec 107 T036 (PR-B): stdlib JWK → public key (research D3, FR-020).
+//
+// Contract exercised here, implemented by T043 in oidc_jwks.go (≤150 lines):
+//
+//	type jwk struct{ Kty, Kid, Use, Alg, N, E, Crv, X, Y string } // json tags: kty,kid,use,alg,n,e,crv,x,y
+//	func jwkToPublicKey(k jwk) (crypto.PublicKey, error)           // RSA (n,e) and EC (crv,x,y) only
+//	func parseJWKS(data []byte) (map[string]crypto.PublicKey, error) // {"keys":[...]} → kid → key
+//
+// jwkToPublicKey refuses (returns an error and a nil key) every key it cannot
+// turn into an *rsa.PublicKey or an *ecdsa.PublicKey: unknown/absent kty,
+// malformed or absent n/e/x/y, unknown crv, an EC point off its curve.
+// parseJWKS refuses a document that is not a JSON object carrying a keys array
+// and otherwise skips — never fails on — individual entries jwkToPublicKey
+// refuses or that carry no kid, so one exotic key in a real IdP's set cannot
+// take every other key with it; a skipped kid is simply absent from the map,
+// which the provider then treats as an unknown kid (one refetch, then refuse).
+
+import (
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/rsa"
+	"encoding/base64"
+	"encoding/json"
+	"math/big"
+	"sync"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/tests/oauthserver"
+)
+
+var (
+	jwksFixtureOnce sync.Once
+	jwksFixtureRSA  *rsa.PrivateKey
+	jwksFixtureEC   map[string]*ecdsa.PrivateKey // by crv name
+)
+
+// jwksFixtureKeys generates the test key material once per package run.
+func jwksFixtureKeys(t *testing.T) (*rsa.PrivateKey, map[string]*ecdsa.PrivateKey) {
+	t.Helper()
+	jwksFixtureOnce.Do(func() {
+		k, err := rsa.GenerateKey(rand.Reader, 2048)
+		if err != nil {
+			panic(err)
+		}
+		jwksFixtureRSA = k
+		jwksFixtureEC = map[string]*ecdsa.PrivateKey{}
+		for name, curve := range map[string]elliptic.Curve{"P-256": elliptic.P256(), "P-384": elliptic.P384(), "P-521": elliptic.P521()} {
+			ek, err := ecdsa.GenerateKey(curve, rand.Reader)
+			if err != nil {
+				panic(err)
+			}
+			jwksFixtureEC[name] = ek
+		}
+	})
+	return jwksFixtureRSA, jwksFixtureEC
+}
+
+func b64url(b []byte) string { return base64.RawURLEncoding.EncodeToString(b) }
+
+// rsaJWK encodes a public RSA key the way RFC 7518 §6.3 and every real IdP do.
+func rsaJWK(kid string, pub *rsa.PublicKey) jwk {
+	return jwk{
+		Kty: "RSA", Kid: kid, Use: "sig", Alg: "RS256",
+		N: b64url(pub.N.Bytes()),
+		E: b64url(big.NewInt(int64(pub.E)).Bytes()),
+	}
+}
+
+// ecJWK encodes a public EC key with fixed-width coordinates (RFC 7518 §6.2.1).
+func ecJWK(kid, crv string, pub *ecdsa.PublicKey) jwk {
+	size := (pub.Curve.Params().BitSize + 7) / 8
+	return jwk{
+		Kty: "EC", Kid: kid, Use: "sig", Crv: crv,
+		X: b64url(pub.X.FillBytes(make([]byte, size))),
+		Y: b64url(pub.Y.FillBytes(make([]byte, size))),
+	}
+}
+
+func jwksDoc(t *testing.T, keys ...jwk) []byte {
+	t.Helper()
+	data, err := json.Marshal(map[string]any{"keys": keys})
+	require.NoError(t, err)
+	return data
+}
+
+func TestJWKToPublicKey_RSA(t *testing.T) {
+	priv, _ := jwksFixtureKeys(t)
+
+	key, err := jwkToPublicKey(rsaJWK("k1", &priv.PublicKey))
+	require.NoError(t, err)
+
+	pub, ok := key.(*rsa.PublicKey)
+	require.True(t, ok, "RSA JWK must become *rsa.PublicKey, got %T", key)
+	assert.True(t, pub.Equal(&priv.PublicKey), "parsed key must equal the source public key")
+	assert.Equal(t, 65537, pub.E)
+}
+
+func TestJWKToPublicKey_RSA_AlgAndUseAreNotRequired(t *testing.T) {
+	// Entra publishes keys without "alg"; Keycloak publishes "use": "enc" keys
+	// beside signing keys. Neither field gates the conversion — the algorithm
+	// is decided by the verifier's allowed-alg intersection (research D3).
+	priv, _ := jwksFixtureKeys(t)
+	k := rsaJWK("k1", &priv.PublicKey)
+	k.Alg, k.Use = "", ""
+
+	key, err := jwkToPublicKey(k)
+	require.NoError(t, err)
+	require.IsType(t, &rsa.PublicKey{}, key)
+}
+
+func TestJWKToPublicKey_EC(t *testing.T) {
+	_, ecKeys := jwksFixtureKeys(t)
+
+	for crv, priv := range ecKeys {
+		t.Run(crv, func(t *testing.T) {
+			key, err := jwkToPublicKey(ecJWK("e1", crv, &priv.PublicKey))
+			require.NoError(t, err)
+
+			pub, ok := key.(*ecdsa.PublicKey)
+			require.True(t, ok, "EC JWK must become *ecdsa.PublicKey, got %T", key)
+			assert.True(t, pub.Equal(&priv.PublicKey), "parsed key must equal the source public key")
+			assert.Equal(t, priv.Curve.Params().Name, pub.Curve.Params().Name)
+		})
+	}
+}
+
+func TestJWKToPublicKey_UnknownKtyRefused(t *testing.T) {
+	priv, ecKeys := jwksFixtureKeys(t)
+
+	cases := map[string]jwk{
+		"oct symmetric":     {Kty: "oct", Kid: "s1", Alg: "HS256", N: b64url([]byte("secret"))},
+		"OKP":               {Kty: "OKP", Kid: "o1", Crv: "Ed25519", X: b64url(make([]byte, 32))},
+		"empty kty":         {Kid: "k1", N: rsaJWK("k1", &priv.PublicKey).N, E: "AQAB"},
+		"lower-case rsa":    {Kty: "rsa", Kid: "k1", N: rsaJWK("k1", &priv.PublicKey).N, E: "AQAB"},
+		"lower-case ec":     func() jwk { k := ecJWK("e1", "P-256", &ecKeys["P-256"].PublicKey); k.Kty = "ec"; return k }(),
+		"kty with EC body":  func() jwk { k := ecJWK("e1", "P-256", &ecKeys["P-256"].PublicKey); k.Kty = "RSA"; return k }(),
+		"kty with RSA body": func() jwk { k := rsaJWK("k1", &priv.PublicKey); k.Kty = "EC"; return k }(),
+	}
+	for name, k := range cases {
+		t.Run(name, func(t *testing.T) {
+			key, err := jwkToPublicKey(k)
+			require.Error(t, err)
+			assert.Nil(t, key, "a refused JWK must not yield a key")
+		})
+	}
+}
+
+func TestJWKToPublicKey_MalformedRSARefused(t *testing.T) {
+	priv, _ := jwksFixtureKeys(t)
+	good := rsaJWK("k1", &priv.PublicKey)
+
+	mutate := func(f func(k *jwk)) jwk { k := good; f(&k); return k }
+	cases := map[string]jwk{
+		"n absent":                 mutate(func(k *jwk) { k.N = "" }),
+		"e absent":                 mutate(func(k *jwk) { k.E = "" }),
+		"n not base64url":          mutate(func(k *jwk) { k.N = "!!not-base64!!" }),
+		"e not base64url":          mutate(func(k *jwk) { k.E = "!!" }),
+		"n with std-base64 chars":  mutate(func(k *jwk) { k.N = "ab+/cd" }),
+		"e with padding":           mutate(func(k *jwk) { k.E = "AQAB=" }),
+		"e zero":                   mutate(func(k *jwk) { k.E = b64url([]byte{0}) }),
+		"e one":                    mutate(func(k *jwk) { k.E = b64url([]byte{1}) }),
+		"e overflows int":          mutate(func(k *jwk) { k.E = b64url([]byte{1, 0, 0, 0, 0, 0, 0, 0, 1}) }),
+		"n zero":                   mutate(func(k *jwk) { k.N = b64url([]byte{0}) }),
+		"n and e both empty bytes": mutate(func(k *jwk) { k.N = b64url(nil); k.E = b64url(nil) }),
+	}
+	for name, k := range cases {
+		t.Run(name, func(t *testing.T) {
+			key, err := jwkToPublicKey(k)
+			require.Error(t, err)
+			assert.Nil(t, key, "a refused JWK must not yield a key")
+		})
+	}
+}
+
+func TestJWKToPublicKey_MalformedECRefused(t *testing.T) {
+	_, ecKeys := jwksFixtureKeys(t)
+	p256 := ecKeys["P-256"]
+	good := ecJWK("e1", "P-256", &p256.PublicKey)
+
+	mutate := func(f func(k *jwk)) jwk { k := good; f(&k); return k }
+
+	// A point that is not on P-256: keep x, flip one bit of y.
+	offCurveY := p256.Y.FillBytes(make([]byte, 32))
+	offCurveY[31] ^= 0x01
+
+	cases := map[string]jwk{
+		"crv absent":            mutate(func(k *jwk) { k.Crv = "" }),
+		"crv unknown":           mutate(func(k *jwk) { k.Crv = "secp256k1" }),
+		"crv mismatch for size": mutate(func(k *jwk) { k.Crv = "P-384" }),
+		"x absent":              mutate(func(k *jwk) { k.X = "" }),
+		"y absent":              mutate(func(k *jwk) { k.Y = "" }),
+		"x not base64url":       mutate(func(k *jwk) { k.X = "!!" }),
+		"y not base64url":       mutate(func(k *jwk) { k.Y = "!!" }),
+		"point off curve":       mutate(func(k *jwk) { k.Y = b64url(offCurveY) }),
+		"x,y zero":              mutate(func(k *jwk) { k.X = b64url(make([]byte, 32)); k.Y = b64url(make([]byte, 32)) }),
+	}
+	for name, k := range cases {
+		t.Run(name, func(t *testing.T) {
+			key, err := jwkToPublicKey(k)
+			require.Error(t, err)
+			assert.Nil(t, key, "a refused JWK must not yield a key")
+		})
+	}
+}
+
+func TestParseJWKS_MapsByKid(t *testing.T) {
+	priv, ecKeys := jwksFixtureKeys(t)
+
+	keys, err := parseJWKS(jwksDoc(t,
+		rsaJWK("rsa-1", &priv.PublicKey),
+		ecJWK("ec-1", "P-256", &ecKeys["P-256"].PublicKey),
+	))
+	require.NoError(t, err)
+	require.Len(t, keys, 2)
+
+	rsaPub, ok := keys["rsa-1"].(*rsa.PublicKey)
+	require.True(t, ok, "rsa-1 must be *rsa.PublicKey, got %T", keys["rsa-1"])
+	assert.True(t, rsaPub.Equal(&priv.PublicKey))
+
+	ecPub, ok := keys["ec-1"].(*ecdsa.PublicKey)
+	require.True(t, ok, "ec-1 must be *ecdsa.PublicKey, got %T", keys["ec-1"])
+	assert.True(t, ecPub.Equal(&ecKeys["P-256"].PublicKey))
+}
+
+func TestParseJWKS_SkipsRefusedEntriesKeepsTheRest(t *testing.T) {
+	priv, ecKeys := jwksFixtureKeys(t)
+	badRSA := rsaJWK("rsa-bad", &priv.PublicKey)
+	badRSA.E = "!!"
+
+	keys, err := parseJWKS(jwksDoc(t,
+		jwk{Kty: "oct", Kid: "sym", N: b64url([]byte("secret"))}, // unknown kty
+		badRSA,                                  // malformed e
+		jwk{Kty: "RSA", N: badRSA.N, E: "AQAB"}, // no kid → unaddressable
+		rsaJWK("rsa-good", &priv.PublicKey),
+		ecJWK("ec-good", "P-256", &ecKeys["P-256"].PublicKey),
+	))
+	require.NoError(t, err, "one refused entry must not take the whole set with it")
+
+	assert.Len(t, keys, 2)
+	assert.Contains(t, keys, "rsa-good")
+	assert.Contains(t, keys, "ec-good")
+	assert.NotContains(t, keys, "sym")
+	assert.NotContains(t, keys, "rsa-bad")
+	assert.NotContains(t, keys, "")
+}
+
+func TestParseJWKS_EmptySet(t *testing.T) {
+	keys, err := parseJWKS([]byte(`{"keys":[]}`))
+	require.NoError(t, err)
+	assert.Empty(t, keys)
+	assert.NotNil(t, keys, "an empty set is an empty map, not nil")
+}
+
+func TestParseJWKS_MalformedDocumentRefused(t *testing.T) {
+	cases := map[string]string{
+		"not json":            `{"keys":[`,
+		"empty body":          ``,
+		"json null":           `null`,
+		"array not object":    `[{"kty":"RSA"}]`,
+		"keys missing":        `{"kid":"x"}`,
+		"keys is object":      `{"keys":{"kty":"RSA"}}`,
+		"keys is string":      `{"keys":"RSA"}`,
+		"key entry is string": `{"keys":["RSA"]}`,
+	}
+	for name, doc := range cases {
+		t.Run(name, func(t *testing.T) {
+			keys, err := parseJWKS([]byte(doc))
+			require.Error(t, err)
+			assert.Nil(t, keys)
+		})
+	}
+}
+
+func TestParseJWKS_IgnoresUnknownFields(t *testing.T) {
+	// Real sets carry x5c, x5t, x5t#S256, issuer, cloud_instance_name, … .
+	priv, _ := jwksFixtureKeys(t)
+	k := rsaJWK("rsa-1", &priv.PublicKey)
+	doc := `{"keys":[{"kty":"RSA","kid":"rsa-1","use":"sig","alg":"RS256","n":"` + k.N + `","e":"` + k.E + `",` +
+		`"x5c":["MIIC"],"x5t":"abc","x5t#S256":"def","issuer":"https://login.example.com","cloud_instance_name":"x"}],` +
+		`"extra":{"nested":true}}`
+
+	keys, err := parseJWKS([]byte(doc))
+	require.NoError(t, err)
+	require.Contains(t, keys, "rsa-1")
+	assert.True(t, keys["rsa-1"].(*rsa.PublicKey).Equal(&priv.PublicKey))
+}
+
+func TestParseJWKS_DuplicateKidLastWins(t *testing.T) {
+	// Not a real-IdP shape, but the cache is a map: the behaviour must be
+	// deterministic rather than an error that would refuse every login.
+	priv, ecKeys := jwksFixtureKeys(t)
+
+	keys, err := parseJWKS(jwksDoc(t,
+		rsaJWK("dup", &priv.PublicKey),
+		ecJWK("dup", "P-256", &ecKeys["P-256"].PublicKey),
+	))
+	require.NoError(t, err)
+	require.Len(t, keys, 1)
+	require.IsType(t, &ecdsa.PublicKey{}, keys["dup"])
+}
+
+func TestParseJWKS_AgainstFakeIdPKeyRing(t *testing.T) {
+	// The exact document tests/oauthserver serves on /jwks.json (T033):
+	// RSA keys from the rotating ring plus the EC key the
+	// IDTokenKeyAlgMismatch knob publishes. Every kid must resolve to the
+	// ring's own public key, both before and after a rotation.
+	ring, err := oauthserver.NewKeyRing()
+	require.NoError(t, err)
+	ecKid, err := ring.AddECKey()
+	require.NoError(t, err)
+	rotatedKid, err := ring.RotateKey()
+	require.NoError(t, err)
+
+	doc, err := json.Marshal(ring.GetJWKS())
+	require.NoError(t, err)
+
+	keys, err := parseJWKS(doc)
+	require.NoError(t, err)
+	require.Len(t, keys, 3, "key-1, the rotated key and the EC key")
+
+	for _, kid := range []string{"key-1", rotatedKid} {
+		priv, ok := ring.GetKey(kid)
+		require.True(t, ok)
+		got, ok := keys[kid].(*rsa.PublicKey)
+		require.True(t, ok, "%s must be *rsa.PublicKey, got %T", kid, keys[kid])
+		assert.True(t, got.Equal(&priv.PublicKey), "kid %s", kid)
+	}
+
+	gotEC, ok := keys[ecKid].(*ecdsa.PublicKey)
+	require.True(t, ok, "%s must be *ecdsa.PublicKey, got %T", ecKid, keys[ecKid])
+	_, ecPriv := ring.GetECKey()
+	assert.True(t, gotEC.Equal(&ecPriv.PublicKey))
+}
+
+// Compile-time pin of the contract T043 must satisfy (research D3 /
+// data-model §7: jwksCache is map[kid]crypto.PublicKey).
+var (
+	_ func(jwk) (crypto.PublicKey, error)               = jwkToPublicKey
+	_ func([]byte) (map[string]crypto.PublicKey, error) = parseJWKS
+)
diff --git a/internal/serveredition/auth/oidc_provider.go b/internal/serveredition/auth/oidc_provider.go
new file mode 100644
index 000000000..c31741d65
--- /dev/null
+++ b/internal/serveredition/auth/oidc_provider.go
@@ -0,0 +1,625 @@
+//go:build server
+
+package auth
+
+// The generic `oidc` provider (Spec 107 FR-020..FR-022, research D3/D4):
+// OpenID Connect Discovery, a JWKS cache, the token exchange with the client
+// authentication method discovery advertises, and a VERIFIED ID token —
+// signature by kid, allowed algorithms, exp/nbf/iat with 60 s skew, exact
+// iss, aud/azp, nonce — before any claim is read. Groups come from the token,
+// or from userinfo only when the token lacks the claim and userinfo's `sub`
+// equals the verified token's `sub`.
+//
+// Every back-channel request (discovery, JWKS, token, userinfo) goes through
+// one client that never follows redirects and times out after 10 s; any 3xx
+// is provider_error. Discovery is lazy — nothing is fetched at construction
+// — so boot and readiness never depend on the IdP.
+
+import (
+	"context"
+	"crypto"
+	"crypto/subtle"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"slices"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+)
+
+const (
+	oidcBackChannelTimeout = 10 * time.Second
+	oidcClockSkew          = 60 * time.Second
+	oidcCacheTTLMin        = 5 * time.Minute
+	oidcCacheTTLMax        = 24 * time.Hour
+	oidcCacheTTLDefault    = time.Hour
+	oidcMaxBodyBytes       = 1 << 20
+
+	clientAuthBasic = "client_secret_basic"
+	clientAuthPost  = "client_secret_post"
+)
+
+// oidcAllowedAlgs is the closed set an ID token may be signed with (FR-021):
+// asymmetric only, never `none`, never HS*.
+var oidcAllowedAlgs = []string{"RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512"}
+
+// oidcError is a classified back-channel or verification failure: the closed
+// reason the handler reports, the name of the check that failed (logged, never
+// a claim value) and the underlying cause.
+type oidcError struct {
+	reason LoginRefusal
+	check  string
+	err    error
+}
+
+func (e *oidcError) Error() string {
+	if e.err != nil {
+		return fmt.Sprintf("%s: %s: %v", e.reason, e.check, e.err)
+	}
+	return fmt.Sprintf("%s: %s", e.reason, e.check)
+}
+
+func (e *oidcError) Unwrap() error { return e.err }
+
+func newOIDCError(reason LoginRefusal, check string, err error) *oidcError {
+	return &oidcError{reason: reason, check: check, err: err}
+}
+
+// discoveryDoc is the subset of OpenID Provider Metadata the login needs.
+type discoveryDoc struct {
+	Issuer                            string   `json:"issuer"`
+	AuthorizationEndpoint             string   `json:"authorization_endpoint"`
+	TokenEndpoint                     string   `json:"token_endpoint"`
+	JWKSURI                           string   `json:"jwks_uri"`
+	UserinfoEndpoint                  string   `json:"userinfo_endpoint"`
+	TokenEndpointAuthMethodsSupported []string `json:"token_endpoint_auth_methods_supported"`
+	IDTokenSigningAlgValuesSupported  []string `json:"id_token_signing_alg_values_supported"`
+
+	clientAuth  string   // clientAuthBasic | clientAuthPost, chosen once
+	allowedAlgs []string // intersection with oidcAllowedAlgs
+	fetchedAt   time.Time
+	expiresAt   time.Time
+}
+
+// oidcProvider holds the per-issuer state: the configuration it was built
+// from, the non-redirecting client and the discovery/JWKS caches.
+type oidcProvider struct {
+	cfg    *config.ServerEditionOAuthConfig
+	client *http.Client
+	now    func() time.Time
+
+	mu          sync.Mutex
+	disc        *discoveryDoc
+	jwks        map[string]crypto.PublicKey
+	jwksExpires time.Time
+}
+
+func newOIDCProvider(cfg *config.ServerEditionOAuthConfig) *oidcProvider {
+	return &oidcProvider{
+		cfg: cfg,
+		// Transport stays nil (http.DefaultTransport) on purpose: tests observe
+		// the back channel by swapping the default transport.
+		client: &http.Client{
+			Timeout: oidcBackChannelTimeout,
+			CheckRedirect: func(*http.Request, []*http.Request) error {
+				return http.ErrUseLastResponse
+			},
+		},
+		now: time.Now,
+	}
+}
+
+// idTokenClaims are the verified claims the handler consumes.
+type idTokenClaims struct {
+	Subject       string
+	Email         string
+	EmailVerified *bool
+	Name          string
+	Picture       string
+	raw           map[string]any
+}
+
+// --- back channel ------------------------------------------------------------
+
+// get performs one non-redirecting GET and returns the body of a 200 with the
+// response's cache TTL; any transport failure, 3xx or non-200 is
+// provider_error.
+func (p *oidcProvider) get(ctx context.Context, what, endpoint, bearer string) ([]byte, time.Duration, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
+	if err != nil {
+		return nil, 0, newOIDCError(LoginProviderError, what+" request", err)
+	}
+	req.Header.Set("Accept", "application/json")
+	if bearer != "" {
+		req.Header.Set("Authorization", "Bearer "+bearer)
+	}
+	resp, err := p.client.Do(req)
+	if err != nil {
+		return nil, 0, newOIDCError(LoginProviderError, what+" request failed", redactURLError(err))
+	}
+	defer resp.Body.Close()
+	body, err := io.ReadAll(io.LimitReader(resp.Body, oidcMaxBodyBytes))
+	if err != nil {
+		return nil, 0, newOIDCError(LoginProviderError, what+" response read", err)
+	}
+	if resp.StatusCode/100 == 3 {
+		return nil, 0, newOIDCError(LoginProviderError, what+" endpoint answered a redirect", fmt.Errorf("status %d", resp.StatusCode))
+	}
+	if resp.StatusCode != http.StatusOK {
+		return nil, 0, newOIDCError(LoginProviderError, what+" endpoint status", fmt.Errorf("status %d", resp.StatusCode))
+	}
+	return body, cacheTTL(resp.Header.Get("Cache-Control")), nil
+}
+
+// redactURLError strips the URL (which may carry query values) from a
+// transport error so the log line names only the failure class.
+func redactURLError(err error) error {
+	var ue *url.Error
+	if errors.As(err, &ue) && ue.Err != nil {
+		return fmt.Errorf("%s: %w", ue.Op, ue.Err)
+	}
+	return err
+}
+
+// cacheTTL derives a cache lifetime from Cache-Control max-age, clamped to
+// [5 min, 24 h]; a missing or unparsable directive yields the default.
+func cacheTTL(cacheControl string) time.Duration {
+	ttl := oidcCacheTTLDefault
+	for _, directive := range strings.Split(cacheControl, ",") {
+		directive = strings.TrimSpace(strings.ToLower(directive))
+		if strings.HasPrefix(directive, "max-age=") {
+			if secs, err := strconv.Atoi(strings.TrimPrefix(directive, "max-age=")); err == nil {
+				ttl = time.Duration(secs) * time.Second
+			}
+		}
+	}
+	return min(max(ttl, oidcCacheTTLMin), oidcCacheTTLMax)
+}
+
+// --- discovery -----------------------------------------------------------
+
+// discover returns the cached discovery document, fetching and validating it
+// when absent or expired. A rejected document is never cached.
+func (p *oidcProvider) discover(ctx context.Context) (*discoveryDoc, error) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	if p.disc != nil && p.now().Before(p.disc.expiresAt) {
+		return p.disc, nil
+	}
+	doc, err := p.fetchDiscovery(ctx)
+	if err != nil {
+		return nil, err
+	}
+	p.disc = doc
+	return doc, nil
+}
+
+func (p *oidcProvider) fetchDiscovery(ctx context.Context) (*discoveryDoc, error) {
+	endpoint := strings.TrimSuffix(p.cfg.IssuerURL, "/") + "/.well-known/openid-configuration"
+	body, ttl, err := p.get(ctx, "discovery", endpoint, "")
+	if err != nil {
+		return nil, err
+	}
+	var doc discoveryDoc
+	if err := json.Unmarshal(body, &doc); err != nil {
+		return nil, newOIDCError(LoginDiscoveryFailed, "discovery document is not JSON", err)
+	}
+	if doc.Issuer != p.cfg.IssuerURL {
+		// Spec 107 (Edge Cases, "Issuer with a path or trailing slash"): the
+		// log line must name both values (they are not secrets) so the
+		// operator can see the mismatch, e.g. a trailing slash, without
+		// re-fetching the document themselves (cross-review round 7, chunk 3
+		// P3 — docs already promised this; the code did not deliver it).
+		return nil, newOIDCError(LoginDiscoveryFailed, fmt.Sprintf(
+			"discovery issuer %q does not equal issuer_url %q", doc.Issuer, p.cfg.IssuerURL), nil)
+	}
+	for name, ep := range map[string]string{
+		"authorization_endpoint": doc.AuthorizationEndpoint,
+		"token_endpoint":         doc.TokenEndpoint,
+		"jwks_uri":               doc.JWKSURI,
+	} {
+		if ep == "" {
+			return nil, newOIDCError(LoginDiscoveryFailed, "discovery document lacks "+name, nil)
+		}
+		if !config.IsAllowedOIDCEndpoint(ep, p.cfg.AllowInsecureIssuer) {
+			return nil, newOIDCError(LoginDiscoveryFailed, "discovery "+name+" is not an absolute https URL", nil)
+		}
+	}
+	if doc.UserinfoEndpoint != "" && !config.IsAllowedOIDCEndpoint(doc.UserinfoEndpoint, p.cfg.AllowInsecureIssuer) {
+		return nil, newOIDCError(LoginDiscoveryFailed, "discovery userinfo_endpoint is not an absolute https URL", nil)
+	}
+	switch {
+	case doc.TokenEndpointAuthMethodsSupported == nil, slices.Contains(doc.TokenEndpointAuthMethodsSupported, clientAuthBasic):
+		doc.clientAuth = clientAuthBasic // the OIDC Discovery §3 default when absent
+	case slices.Contains(doc.TokenEndpointAuthMethodsSupported, clientAuthPost):
+		doc.clientAuth = clientAuthPost
+	default:
+		return nil, newOIDCError(LoginDiscoveryFailed, "token_endpoint_auth_methods_supported offers neither client_secret_basic nor client_secret_post", nil)
+	}
+	advertised := doc.IDTokenSigningAlgValuesSupported
+	if advertised == nil {
+		advertised = []string{"RS256"} // mandatory-to-implement (OIDC Discovery §3)
+	}
+	for _, alg := range oidcAllowedAlgs {
+		if slices.Contains(advertised, alg) {
+			doc.allowedAlgs = append(doc.allowedAlgs, alg)
+		}
+	}
+	if len(doc.allowedAlgs) == 0 {
+		return nil, newOIDCError(LoginDiscoveryFailed, "id_token_signing_alg_values_supported has no allowed asymmetric algorithm", nil)
+	}
+	doc.fetchedAt = p.now()
+	doc.expiresAt = doc.fetchedAt.Add(ttl)
+	return &doc, nil
+}
+
+// --- authorization URL and token exchange --------------------------------------
+
+// authorizationURL builds the authorization request with state, nonce and
+// PKCE S256 against the discovered authorization_endpoint.
+func (p *oidcProvider) authorizationURL(ctx context.Context, callbackURL, state, nonce, codeChallenge string) (string, error) {
+	doc, err := p.discover(ctx)
+	if err != nil {
+		return "", err
+	}
+	// Parse and merge into the endpoint's own query rather than blindly
+	// appending "?" + params.Encode(): an authorization_endpoint that already
+	// carries a query component (e.g. a tenant/realm selector) would otherwise
+	// produce "?tenant=acme?client_id=..." — a single malformed query string
+	// the IdP cannot parse, so client_id/state/nonce/PKCE never arrive
+	// (cross-review round 2, chunk 1 P2).
+	u, err := url.Parse(doc.AuthorizationEndpoint)
+	if err != nil {
+		return "", newOIDCError(LoginDiscoveryFailed, "authorization_endpoint is not a valid URL", err)
+	}
+	q := u.Query()
+	q.Set("client_id", p.cfg.ClientID)
+	q.Set("redirect_uri", callbackURL)
+	q.Set("response_type", "code")
+	q.Set("scope", strings.Join(p.cfg.Scopes, " "))
+	q.Set("state", state)
+	q.Set("nonce", nonce)
+	q.Set("code_challenge", codeChallenge)
+	q.Set("code_challenge_method", "S256")
+	u.RawQuery = q.Encode()
+	return u.String(), nil
+}
+
+// exchangeCode redeems the authorization code once, with the client
+// authentication method discovery advertised.
+func (p *oidcProvider) exchangeCode(ctx context.Context, code, callbackURL, codeVerifier string) (*TokenResponse, error) {
+	doc, err := p.discover(ctx)
+	if err != nil {
+		return nil, err
+	}
+	form := url.Values{
+		"grant_type":    {"authorization_code"},
+		"code":          {code},
+		"redirect_uri":  {callbackURL},
+		"code_verifier": {codeVerifier},
+	}
+	if doc.clientAuth == clientAuthPost {
+		form.Set("client_id", p.cfg.ClientID)
+		form.Set("client_secret", p.cfg.ClientSecret)
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, doc.TokenEndpoint, strings.NewReader(form.Encode()))
+	if err != nil {
+		return nil, newOIDCError(LoginProviderError, "token request", err)
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.Header.Set("Accept", "application/json")
+	if doc.clientAuth == clientAuthBasic {
+		// RFC 6749 §2.3.1: credentials are form-encoded before Basic.
+		req.SetBasicAuth(url.QueryEscape(p.cfg.ClientID), url.QueryEscape(p.cfg.ClientSecret))
+	}
+	resp, err := p.client.Do(req)
+	if err != nil {
+		return nil, newOIDCError(LoginProviderError, "token request failed", redactURLError(err))
+	}
+	defer resp.Body.Close()
+	body, err := io.ReadAll(io.LimitReader(resp.Body, oidcMaxBodyBytes))
+	if err != nil {
+		return nil, newOIDCError(LoginProviderError, "token response read", err)
+	}
+	if resp.StatusCode/100 == 3 {
+		return nil, newOIDCError(LoginProviderError, "token endpoint answered a redirect", fmt.Errorf("status %d", resp.StatusCode))
+	}
+	if resp.StatusCode != http.StatusOK {
+		// Only a known RFC 6749 §5.2 error code is surfaced — never the raw
+		// field, which is IdP-controlled and could carry log-injection
+		// content (control characters, multi-line text) or echo request
+		// inputs (cross-review round 1, chunk 1 P2).
+		var oauthErr struct {
+			Error string `json:"error"`
+		}
+		_ = json.Unmarshal(body, &oauthErr)
+		return nil, newOIDCError(LoginProviderError, "token endpoint status", fmt.Errorf("status %d error %q", resp.StatusCode, sanitizeOAuthErrorCode(oauthErr.Error)))
+	}
+	var tok TokenResponse
+	if err := json.Unmarshal(body, &tok); err != nil {
+		return nil, newOIDCError(LoginProviderError, "token response is not JSON", err)
+	}
+	if tok.IDToken == "" {
+		return nil, newOIDCError(LoginIDTokenInvalid, "token response carries no id_token", nil)
+	}
+	return &tok, nil
+}
+
+// oauthErrorCodes is the closed RFC 6749 §5.2 token-endpoint error vocabulary.
+// sanitizeOAuthErrorCode clamps anything else to "unknown" so an IdP-controlled
+// `error` field can never reach the log or the wire verbatim (cross-review
+// round 1, chunk 1 P2: the raw field could carry control characters or echo
+// request inputs).
+var oauthErrorCodes = map[string]bool{
+	"invalid_request":        true,
+	"invalid_client":         true,
+	"invalid_grant":          true,
+	"unauthorized_client":    true,
+	"unsupported_grant_type": true,
+	"invalid_scope":          true,
+}
+
+func sanitizeOAuthErrorCode(code string) string {
+	if oauthErrorCodes[code] {
+		return code
+	}
+	return "unknown"
+}
+
+// --- JWKS -----------------------------------------------------------------
+
+// keyForKid resolves a signing key from the JWKS cache, fetching the set at
+// most once per call: when the cache is cold or expired, or once more when
+// the kid is unknown to a warm cache. An unknown kid after that is refused.
+func (p *oidcProvider) keyForKid(ctx context.Context, doc *discoveryDoc, kid string) (crypto.PublicKey, error) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	if p.jwks != nil && p.now().Before(p.jwksExpires) {
+		if key, ok := p.jwks[kid]; ok {
+			return key, nil
+		}
+	}
+	body, ttl, err := p.get(ctx, "jwks", doc.JWKSURI, "")
+	if err != nil {
+		return nil, err
+	}
+	keys, err := parseJWKS(body)
+	if err != nil {
+		return nil, newOIDCError(LoginProviderError, "jwks document", err)
+	}
+	p.jwks, p.jwksExpires = keys, p.now().Add(ttl)
+	if key, ok := keys[kid]; ok {
+		return key, nil
+	}
+	return nil, newOIDCError(LoginIDTokenInvalid, "id_token kid is not in the JWKS after one refetch", nil)
+}
+
+// --- ID token verification ---------------------------------------------------
+
+// verifyIDToken turns the raw id_token into verified claims (Definitions:
+// verified ID token). Order: signing method ∈ allowed algs → key by kid →
+// signature → exp/nbf/iat (60 s skew) → exact iss → aud/azp → nonce.
+func (p *oidcProvider) verifyIDToken(ctx context.Context, raw, nonce string) (*idTokenClaims, error) {
+	doc, err := p.discover(ctx)
+	if err != nil {
+		return nil, err
+	}
+	claims := jwt.MapClaims{}
+	parser := jwt.NewParser(jwt.WithValidMethods(doc.allowedAlgs), jwt.WithoutClaimsValidation())
+	_, err = parser.ParseWithClaims(raw, claims, func(tok *jwt.Token) (any, error) {
+		kid, _ := tok.Header["kid"].(string)
+		if kid == "" {
+			return nil, errors.New("id_token header has no kid")
+		}
+		return p.keyForKid(ctx, doc, kid)
+	})
+	if err != nil {
+		var oerr *oidcError
+		if errors.As(err, &oerr) {
+			return nil, oerr
+		}
+		return nil, newOIDCError(LoginIDTokenInvalid, "id_token signature or signing method", err)
+	}
+
+	validator := jwt.NewValidator(jwt.WithLeeway(oidcClockSkew), jwt.WithIssuedAt(), jwt.WithExpirationRequired())
+	if err := validator.Validate(claims); err != nil {
+		if errors.Is(err, jwt.ErrTokenExpired) {
+			return nil, newOIDCError(LoginTokenExpired, "id_token exp", err)
+		}
+		return nil, newOIDCError(LoginIDTokenInvalid, "id_token exp/nbf/iat", err)
+	}
+	// jwt.WithIssuedAt() validates iat only when present; it does not make
+	// the claim mandatory (there is no WithIssuedAtRequired in v5). `iat` is
+	// a REQUIRED ID Token claim per OIDC Core §2, so its absence must be
+	// refused explicitly (cross-review round 1, chunk 1 P2).
+	if _, hasIat := claims["iat"]; !hasIat {
+		return nil, newOIDCError(LoginIDTokenInvalid, "id_token has no iat", nil)
+	}
+
+	if iss, _ := claims["iss"].(string); iss != p.cfg.IssuerURL {
+		return nil, newOIDCError(LoginIssuerMismatch, "id_token iss does not equal issuer_url", nil)
+	}
+	auds, audOK := audienceList(claims["aud"])
+	if !audOK {
+		return nil, newOIDCError(LoginAudienceMismatch, "id_token aud contains a non-string entry", nil)
+	}
+	if !slices.Contains(auds, p.cfg.ClientID) {
+		return nil, newOIDCError(LoginAudienceMismatch, "id_token aud does not contain client_id", nil)
+	}
+	azpClaim, azpPresent := claims["azp"]
+	azp, azpIsString := azpClaim.(string)
+	// A present-but-non-string azp (e.g. a number or object) must never be
+	// treated as absent: OIDC defines azp as a string that, when present,
+	// must identify this client, so a malformed value is refused outright
+	// rather than silently falling through the "no azp" branches below
+	// (cross-review round 8, chunk 1 P2).
+	if azpPresent && azpClaim != nil && !azpIsString {
+		return nil, newOIDCError(LoginAudienceMismatch, "id_token azp is not a string", nil)
+	}
+	hasAzp := azpIsString
+	if len(auds) > 1 && !hasAzp {
+		return nil, newOIDCError(LoginAudienceMismatch, "id_token has multiple aud values and no azp", nil)
+	}
+	if hasAzp && azp != p.cfg.ClientID {
+		return nil, newOIDCError(LoginAudienceMismatch, "id_token azp does not equal client_id", nil)
+	}
+	gotNonce, _ := claims["nonce"].(string)
+	if nonce == "" || gotNonce == "" || subtle.ConstantTimeCompare([]byte(gotNonce), []byte(nonce)) != 1 {
+		return nil, newOIDCError(LoginNonceMismatch, "id_token nonce does not equal the nonce bound to the state", nil)
+	}
+
+	out := &idTokenClaims{raw: claims}
+	out.Subject, _ = claims["sub"].(string)
+	if out.Subject == "" {
+		return nil, newOIDCError(LoginIDTokenInvalid, "id_token has no sub", nil)
+	}
+	out.Email, _ = claims["email"].(string)
+	out.Name, _ = claims["name"].(string)
+	out.Picture, _ = claims["picture"].(string)
+	// A present-but-non-boolean email_verified (e.g. the string "false", or
+	// 0) must not be silently treated the same as an absent claim: refuse_false
+	// only refuses an explicit false, so nil (absent) would let a malformed
+	// value's login through even when the claim's clear intent is "not
+	// verified" (cross-review round 7, chunk 1 P2). Reject it as a malformed
+	// token instead of guessing its meaning.
+	if raw, present := claims["email_verified"]; present && raw != nil {
+		v, ok := raw.(bool)
+		if !ok {
+			return nil, newOIDCError(LoginIDTokenInvalid, "id_token email_verified is present but not a boolean", nil)
+		}
+		out.EmailVerified = &v
+	}
+	return out, nil
+}
+
+// audienceList normalises the `aud` claim (string or array of strings). ok is
+// false when the claim is an array containing a non-string entry: silently
+// dropping such an entry would undercount the audience and could let a
+// malformed multi-aud token skip the azp check that array length is meant to
+// trigger (cross-review round 1, chunk 1 P2) — the token is refused instead.
+func audienceList(v any) (auds []string, ok bool) {
+	switch a := v.(type) {
+	case string:
+		return []string{a}, true
+	case []any:
+		out := make([]string, 0, len(a))
+		for _, item := range a {
+			s, isString := item.(string)
+			if !isString {
+				return nil, false
+			}
+			out = append(out, s)
+		}
+		return out, true
+	case []string:
+		return a, true
+	}
+	return nil, true
+}
+
+// --- groups -----------------------------------------------------------------
+
+// groupsFromClaims reads the configured groups claim: present reports the
+// key exists, ok reports it is a flat array of strings or a single string.
+func groupsFromClaims(claims map[string]any, name string) (groups []string, present, ok bool) {
+	v, present := claims[name]
+	if !present {
+		return nil, false, false
+	}
+	switch g := v.(type) {
+	case string:
+		return []string{g}, true, true
+	case []any:
+		out := make([]string, 0, len(g))
+		for _, item := range g {
+			s, isString := item.(string)
+			if !isString {
+				return nil, true, false
+			}
+			out = append(out, s)
+		}
+		return out, true, true
+	case []string:
+		return append([]string{}, g...), true, true
+	}
+	return nil, true, false
+}
+
+// hasOverageMarker reports an Entra "groups overage" claim reference
+// (`_claim_names` naming the groups claim) — the groups are not in the token.
+func hasOverageMarker(claims map[string]any, name string) bool {
+	names, ok := claims["_claim_names"].(map[string]any)
+	if !ok {
+		return false
+	}
+	_, ok = names[name]
+	return ok
+}
+
+// resolveGroups returns the verified groups for the login (FR-008): from the
+// ID token; from userinfo only when the token lacks the claim and userinfo's
+// sub equals the verified token's sub. missing reports the fail-closed
+// `groups_claim_missing` case (absent everywhere, malformed shape, overage
+// marker) in which groups is [].
+func (p *oidcProvider) resolveGroups(ctx context.Context, claims *idTokenClaims, accessToken string) (groups []string, missing bool, err error) {
+	name := p.cfg.GroupsClaim
+	if hasOverageMarker(claims.raw, name) {
+		return []string{}, true, nil
+	}
+	if g, present, ok := groupsFromClaims(claims.raw, name); present {
+		if ok {
+			return g, false, nil
+		}
+		return []string{}, true, nil
+	}
+
+	doc, err := p.discover(ctx)
+	if err != nil {
+		return nil, false, err
+	}
+	if doc.UserinfoEndpoint == "" {
+		return []string{}, true, nil
+	}
+	if accessToken == "" {
+		// The token endpoint is required to carry access_token (RFC 6749
+		// §5.1), but a hostile or misconfigured IdP could still omit it.
+		// Userinfo is advertised and required to resolve the missing groups
+		// claim, so an absent credential is a fetch that could not be
+		// attempted, not "claim absent": provider_error, never a silent
+		// groups=[] login (FR-008/FR-022, cross-review round 3).
+		return nil, false, newOIDCError(LoginProviderError, "no access_token to fetch userinfo", nil)
+	}
+	body, _, err := p.get(ctx, "userinfo", doc.UserinfoEndpoint, accessToken)
+	if err != nil {
+		return nil, false, err
+	}
+	var info map[string]any
+	if err := json.Unmarshal(body, &info); err != nil {
+		return nil, false, newOIDCError(LoginProviderError, "userinfo response is not JSON", err)
+	}
+	if info == nil {
+		// A JSON scalar (`null`, a number, a string, an array) decodes to a
+		// nil map without an Unmarshal error; that is not a JSON object and
+		// must fail closed as provider_error (FR-022), never be read as
+		// "sub absent" (cross-review round 1, chunk 1 P3).
+		return nil, false, newOIDCError(LoginProviderError, "userinfo response is not a JSON object", nil)
+	}
+	// No userinfo claim is read before its sub is compared with the verified
+	// token's sub (FR-022).
+	if sub, _ := info["sub"].(string); sub == "" || sub != claims.Subject {
+		return nil, false, newOIDCError(LoginUserinfoSubjectMismatch, "userinfo sub does not equal the id_token sub", nil)
+	}
+	if g, present, ok := groupsFromClaims(info, name); present && ok {
+		return g, false, nil
+	}
+	return []string{}, true, nil
+}
diff --git a/internal/serveredition/auth/oidc_verify_test.go b/internal/serveredition/auth/oidc_verify_test.go
new file mode 100644
index 000000000..5a8f5af95
--- /dev/null
+++ b/internal/serveredition/auth/oidc_verify_test.go
@@ -0,0 +1,872 @@
+//go:build server
+
+package auth
+
+// Spec 107 T037 (PR-B) — the generic `oidc` provider's verified ID token
+// (FR-021), claims (FR-022) and groups capture (FR-008 capture half), driven
+// end to end through HandleLogin → the in-process tests/oauthserver fake IdP
+// (headless form POST) → HandleCallback. Every case is driven through the
+// fake's ErrorMode knob of research D2 / T033 or its Options.UserClaims; the
+// one case with no knob (a wrong nonce) tampers with the nonce the handler
+// stored beside the state. No case is synthesised against a second fake.
+//
+// Compile-red until T043 (the provider: OAuthProvider.BuildAuthURL emits
+// `nonce`, ExchangeCode + verified ID token via the JWKS, groups from the token
+// or /userinfo after the `sub` comparison; OAuthUserInfo.Groups/EmailVerified)
+// AND T044 (the handler: NewOAuthHandler taking a ServerEditionConfigProvider,
+// oauthState.Nonce, LoginResult/LoginRefusal/LoginResultObserver, the generic
+// 403/503 pages, users.User.Groups/GroupsUpdatedAt written through
+// UpdateUserLogin), on top of T041 (config keys; users.User.Validate admits
+// `oidc`) and T042 (the provider is constructed once in NewOAuthHandler).
+//
+// Conventions shared with oauth_handler_subject_test.go (T038): the closed
+// reason is compared as its wire value (`string(res.Reason)`, FR-013), never
+// by constant name; flags likewise.
+//
+// Observation of the back channel (JWKS/userinfo request counts, the raw
+// id_token for "never logged", the one mid-flow re-knob) goes through
+// http.DefaultTransport, so the provider's non-redirecting 10 s client (T043)
+// must leave Transport nil — the stdlib default — exactly like today's
+// package-level httpClient in oauth_providers.go.
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.etcd.io/bbolt"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapcore"
+	"go.uber.org/zap/zaptest/observer"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/serveredition/users"
+	"github.com/smart-mcp-proxy/mcpproxy-go/tests/oauthserver"
+)
+
+const (
+	oidcVerifyEmail    = "alice@example.com"
+	oidcVerifyPassword = "pass"
+	oidcVerifySub      = "alice-sub-1"
+	oidcVerifyName     = "Alice Example"
+	oidcVerifyHost     = "127.0.0.1"
+	oidcVerifyCallback = "http://127.0.0.1/api/v1/auth/callback"
+	oidcVerifyHMACKey  = "test-hmac-key-for-jwt-signing-32b"
+	oidcVerifyGroups   = "groups"
+)
+
+// oidcVerifyClaims are alice's identity claims at the fake IdP (the id_token
+// and /userinfo carry the same set).
+func oidcVerifyClaims() map[string]any {
+	return map[string]any{
+		"sub":            oidcVerifySub,
+		"email":          oidcVerifyEmail,
+		"email_verified": true,
+		"name":           oidcVerifyName,
+		"groups":         []any{"eng", "sre"},
+	}
+}
+
+// startOIDCVerifyIdP starts the fake OpenID Provider with alice's claims.
+func startOIDCVerifyIdP(t *testing.T, claims map[string]any) *oauthserver.ServerResult {
+	t.Helper()
+	srv := oauthserver.Start(t, oauthserver.Options{
+		OIDC:               true,
+		ValidUsers:         map[string]string{oidcVerifyEmail: oidcVerifyPassword},
+		UserClaims:         map[string]map[string]any{oidcVerifyEmail: claims},
+		ClientRedirectURIs: []string{oidcVerifyCallback},
+		GroupsClaim:        oidcVerifyGroups,
+	})
+	t.Cleanup(func() { _ = srv.Shutdown() })
+	return srv
+}
+
+// oidcVerifyConfig is the `provider: oidc` block pointing at the fake, with
+// every PR-B key set explicitly (ApplyDefaults is a setup.go concern).
+func oidcVerifyConfig(idp *oauthserver.ServerResult) *config.ServerEditionConfig {
+	return &config.ServerEditionConfig{
+		Enabled:     true,
+		AdminEmails: []string{"admin@example.com"},
+		OAuth: &config.ServerEditionOAuthConfig{
+			Provider:            "oidc",
+			IssuerURL:           idp.IssuerURL,
+			AllowInsecureIssuer: true, // loopback http fake
+			ClientID:            idp.ClientID,
+			ClientSecret:        idp.ClientSecret,
+			Scopes:              []string{"openid", "profile", "email", "groups"},
+			GroupsClaim:         oidcVerifyGroups,
+			EmailVerifiedPolicy: "refuse_false",
+		},
+		SessionTTL:     config.Duration(time.Hour),
+		BearerTokenTTL: config.Duration(time.Hour),
+	}
+}
+
+// backChannelTap wraps http.DefaultTransport for one rig so the test can see
+// the provider's back-channel requests to the fake: count them, capture the
+// tokens the token endpoint returned (to assert they are never logged), fail
+// one of them at the transport level, or re-knob the fake between the token
+// exchange and the userinfo fetch of a single callback.
+type backChannelTap struct {
+	next http.RoundTripper
+	idp  *oauthserver.ServerResult
+
+	mu             sync.Mutex
+	discovery      int
+	jwks           int
+	token          int
+	userinfo       int
+	idTokens       []string // raw id_tokens the token endpoint returned
+	accessTokens   []string
+	failUserinfo   error                  // returned instead of forwarding /userinfo
+	beforeUserinfo *oauthserver.ErrorMode // SetErrorMode before forwarding /userinfo
+}
+
+func (tap *backChannelTap) RoundTrip(req *http.Request) (*http.Response, error) {
+	tap.mu.Lock()
+	var (
+		fail   error
+		reknob *oauthserver.ErrorMode
+	)
+	switch req.URL.Path {
+	case "/.well-known/openid-configuration":
+		tap.discovery++
+	case "/jwks.json":
+		tap.jwks++
+	case "/token":
+		tap.token++
+	case "/userinfo":
+		tap.userinfo++
+		fail = tap.failUserinfo
+		reknob = tap.beforeUserinfo
+	}
+	tap.mu.Unlock()
+
+	if fail != nil {
+		return nil, fail
+	}
+	if reknob != nil {
+		tap.idp.Server.SetErrorMode(*reknob)
+	}
+
+	resp, err := tap.next.RoundTrip(req)
+	if err != nil || req.URL.Path != "/token" || resp.StatusCode != http.StatusOK {
+		return resp, err
+	}
+
+	// Capture the tokens without disturbing the provider's read of the body.
+	body, readErr := io.ReadAll(resp.Body)
+	_ = resp.Body.Close()
+	if readErr != nil {
+		return nil, readErr
+	}
+	resp.Body = io.NopCloser(bytes.NewReader(body))
+	var tok struct {
+		IDToken     string `json:"id_token"`
+		AccessToken string `json:"access_token"`
+	}
+	if json.Unmarshal(body, &tok) == nil {
+		tap.mu.Lock()
+		if tok.IDToken != "" {
+			tap.idTokens = append(tap.idTokens, tok.IDToken)
+		}
+		if tok.AccessToken != "" {
+			tap.accessTokens = append(tap.accessTokens, tok.AccessToken)
+		}
+		tap.mu.Unlock()
+	}
+	return resp, nil
+}
+
+func (tap *backChannelTap) counts() (discovery, jwks, token, userinfo int) {
+	tap.mu.Lock()
+	defer tap.mu.Unlock()
+	return tap.discovery, tap.jwks, tap.token, tap.userinfo
+}
+
+func (tap *backChannelTap) resetCounts() {
+	tap.mu.Lock()
+	defer tap.mu.Unlock()
+	tap.discovery, tap.jwks, tap.token, tap.userinfo = 0, 0, 0, 0
+}
+
+func (tap *backChannelTap) tokens() []string {
+	tap.mu.Lock()
+	defer tap.mu.Unlock()
+	out := append([]string(nil), tap.idTokens...)
+	return append(out, tap.accessTokens...)
+}
+
+// oidcVerifyRig is one handler + one fresh store over the shared fake IdP,
+// with a LoginResultObserver recording every terminal result and an observed
+// zap core capturing what the handler logs.
+type oidcVerifyRig struct {
+	t       *testing.T
+	idp     *oauthserver.ServerResult
+	cfg     *config.ServerEditionConfig
+	store   *users.UserStore
+	handler *OAuthHandler
+	logs    *observer.ObservedLogs
+	tap     *backChannelTap
+	browser *http.Client // the user's browser towards the fake; never counted
+
+	resultsMu sync.Mutex
+	results   []LoginResult
+
+	lastNonce string // nonce of the most recent HandleLogin
+}
+
+// newOIDCVerifyRig builds a rig over idp. mode is installed on the fake for
+// the rig's lifetime and cleared on cleanup; mutate may adjust the config
+// before the handler is constructed.
+func newOIDCVerifyRig(t *testing.T, idp *oauthserver.ServerResult, mode oauthserver.ErrorMode, mutate func(*config.ServerEditionConfig)) *oidcVerifyRig {
+	t.Helper()
+
+	idp.Server.SetErrorMode(mode)
+	t.Cleanup(func() { idp.Server.SetErrorMode(oauthserver.ErrorMode{}) })
+
+	db, err := bbolt.Open(filepath.Join(t.TempDir(), "oidc-verify.db"), 0600, &bbolt.Options{Timeout: time.Second})
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = db.Close() })
+	store := users.NewUserStore(db)
+	require.NoError(t, store.EnsureBuckets())
+
+	cfg := oidcVerifyConfig(idp)
+	if mutate != nil {
+		mutate(cfg)
+	}
+
+	core, logs := observer.New(zapcore.DebugLevel)
+	sessionMgr := NewSessionManager(store, time.Hour, false)
+	handler := NewOAuthHandler(store, sessionMgr, StaticServerEditionConfig(cfg), []byte(oidcVerifyHMACKey), zap.New(core).Sugar())
+
+	rig := &oidcVerifyRig{t: t, idp: idp, cfg: cfg, store: store, handler: handler, logs: logs}
+	handler.LoginResultObserver = func(res LoginResult) {
+		rig.resultsMu.Lock()
+		defer rig.resultsMu.Unlock()
+		rig.results = append(rig.results, res)
+	}
+
+	// Observe the provider's back channel; the browser client bypasses the tap.
+	orig := http.DefaultTransport
+	rig.tap = &backChannelTap{next: orig, idp: idp}
+	http.DefaultTransport = rig.tap
+	t.Cleanup(func() { http.DefaultTransport = orig })
+	rig.browser = &http.Client{
+		Transport: orig,
+		Timeout:   5 * time.Second,
+		CheckRedirect: func(*http.Request, []*http.Request) error {
+			return http.ErrUseLastResponse
+		},
+	}
+	return rig
+}
+
+// login drives GET /api/v1/auth/login and returns the authorization URL the
+// handler redirected to (state, nonce, PKCE and redirect_uri included).
+func (rig *oidcVerifyRig) login() *url.URL {
+	rig.t.Helper()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/auth/login?redirect_uri=/ui/", nil)
+	req.Host = oidcVerifyHost
+	w := httptest.NewRecorder()
+	rig.handler.HandleLogin(w, req)
+	require.Equal(rig.t, http.StatusFound, w.Code, "login must redirect to the IdP; body: %s", w.Body.String())
+
+	authURL, err := url.Parse(w.Header().Get("Location"))
+	require.NoError(rig.t, err)
+	q := authURL.Query()
+	require.Equal(rig.t, rig.idp.AuthorizationEndpoint, authURL.Scheme+"://"+authURL.Host+authURL.Path, "the discovered authorization_endpoint")
+	require.NotEmpty(rig.t, q.Get("state"))
+	require.NotEmpty(rig.t, q.Get("nonce"), "an oidc login carries a per-login nonce (FR-021)")
+	require.Equal(rig.t, oidcVerifyCallback, q.Get("redirect_uri"))
+	require.Equal(rig.t, "S256", q.Get("code_challenge_method"))
+	rig.lastNonce = q.Get("nonce")
+	return authURL
+}
+
+// approve submits the fake's headless login form as alice and returns the
+// redirect back to the proxy's callback.
+func (rig *oidcVerifyRig) approve(authURL *url.URL) *url.URL {
+	rig.t.Helper()
+	form := authURL.Query()
+	form.Set("username", oidcVerifyEmail)
+	form.Set("password", oidcVerifyPassword)
+	form.Set("consent", "on")
+	form.Set("action", "approve")
+	resp, err := rig.browser.PostForm(rig.idp.AuthorizationEndpoint, form)
+	require.NoError(rig.t, err)
+	_, _ = io.Copy(io.Discard, resp.Body)
+	_ = resp.Body.Close()
+	require.Equal(rig.t, http.StatusFound, resp.StatusCode, "the fake must redirect back with a code")
+	loc, err := url.Parse(resp.Header.Get("Location"))
+	require.NoError(rig.t, err)
+	require.NotEmpty(rig.t, loc.Query().Get("code"))
+	return loc
+}
+
+// callback delivers the IdP's redirect to HandleCallback.
+func (rig *oidcVerifyRig) callback(loc *url.URL) *http.Response {
+	rig.t.Helper()
+	req := httptest.NewRequest(http.MethodGet, loc.String(), nil)
+	req.Host = oidcVerifyHost
+	w := httptest.NewRecorder()
+	rig.handler.HandleCallback(w, req)
+	resp := w.Result()
+	rig.t.Cleanup(func() { _ = resp.Body.Close() })
+	return resp
+}
+
+// attempt runs one full login attempt: login → approve → callback.
+func (rig *oidcVerifyRig) attempt() (*http.Response, LoginResult) {
+	rig.t.Helper()
+	resp := rig.callback(rig.approve(rig.login()))
+	return resp, rig.lastResult()
+}
+
+// lastResult returns the single LoginResult reported since the previous call.
+func (rig *oidcVerifyRig) lastResult() LoginResult {
+	rig.t.Helper()
+	rig.resultsMu.Lock()
+	defer rig.resultsMu.Unlock()
+	require.Len(rig.t, rig.results, 1, "exactly one terminal LoginResult per attempt, got %d", len(rig.results))
+	res := rig.results[0]
+	rig.results = nil
+	return res
+}
+
+func (rig *oidcVerifyRig) pendingState(state string) (*oauthState, bool) {
+	rig.handler.statesMu.Lock()
+	defer rig.handler.statesMu.Unlock()
+	s, ok := rig.handler.pendingStates[state]
+	return s, ok
+}
+
+// seedAlice stores a record for alice bound to (oidc, alice-sub-1) with a
+// known group list and timestamps in the past, so "untouched" is observable.
+func (rig *oidcVerifyRig) seedAlice(groups []string) *users.User {
+	rig.t.Helper()
+	u := users.NewUser(oidcVerifyEmail, oidcVerifyName, "oidc", oidcVerifySub)
+	past := time.Now().UTC().Add(-time.Hour).Truncate(time.Second)
+	u.CreatedAt = past
+	u.LastLoginAt = past
+	u.Groups = groups
+	u.GroupsUpdatedAt = past
+	require.NoError(rig.t, rig.store.CreateUser(u))
+	return rig.alice()
+}
+
+func (rig *oidcVerifyRig) alice() *users.User {
+	rig.t.Helper()
+	u, err := rig.store.GetUserByEmail(oidcVerifyEmail)
+	require.NoError(rig.t, err)
+	return u
+}
+
+func (rig *oidcVerifyRig) userCount() int {
+	rig.t.Helper()
+	all, err := rig.store.ListUsers()
+	require.NoError(rig.t, err)
+	return len(all)
+}
+
+// logText joins every observed entry at or above level: message plus the
+// structured context, so a claim value smuggled into a field is caught too.
+func (rig *oidcVerifyRig) logText(min zapcore.Level) string {
+	var b strings.Builder
+	for _, e := range rig.logs.All() {
+		if e.Level < min {
+			continue
+		}
+		b.WriteString(e.Message)
+		for k, v := range e.ContextMap() {
+			fmt.Fprintf(&b, " %s=%v", k, v)
+		}
+		b.WriteString("\n")
+	}
+	return b.String()
+}
+
+// assertLogNamesCheck: at least one WARN+ line carries the closed reason and
+// one of the words naming the failed check.
+func (rig *oidcVerifyRig) assertLogNamesCheck(reason string, checkWords ...string) {
+	rig.t.Helper()
+	text := strings.ToLower(rig.logText(zapcore.WarnLevel))
+	assert.Contains(rig.t, text, reason, "the refusal log line carries the closed reason")
+	named := false
+	for _, w := range checkWords {
+		if strings.Contains(text, strings.ToLower(w)) {
+			named = true
+			break
+		}
+	}
+	assert.True(rig.t, named, "the refusal log line names the failed check (one of %v); got:\n%s", checkWords, text)
+}
+
+// assertLogNeverCarriesClaims: no line at any level carries a claim value, a
+// token or the client secret.
+func (rig *oidcVerifyRig) assertLogNeverCarriesClaims() {
+	rig.t.Helper()
+	text := rig.logText(zapcore.DebugLevel)
+	forbidden := map[string]string{
+		"email":         oidcVerifyEmail,
+		"sub":           oidcVerifySub,
+		"name":          oidcVerifyName,
+		"nonce":         rig.lastNonce,
+		"client_secret": rig.idp.ClientSecret,
+	}
+	for what, v := range forbidden {
+		if v == "" {
+			continue
+		}
+		assert.NotContains(rig.t, text, v, "log must never carry the %s claim value", what)
+	}
+	for _, tok := range rig.tap.tokens() {
+		assert.NotContains(rig.t, text, tok, "log must never carry a token")
+	}
+}
+
+func oidcFlags(res LoginResult) []string {
+	out := []string{}
+	for _, f := range res.Flags {
+		out = append(out, string(f))
+	}
+	return out
+}
+
+// --- FR-021: the tamper matrix ------------------------------------------------
+//
+// Each case: one knob (or the nonce tampered in the pending state), one closed
+// reason, the generic 403, the user store untouched (alice pre-seeded so an
+// update would be visible), the state consumed, and a log line naming the
+// check but never a claim value. The control row proves the seed and the
+// flow are sound: without a knob the same attempt succeeds and rewrites the
+// record.
+
+func TestOIDCVerify_TamperMatrix(t *testing.T) {
+	idp := startOIDCVerifyIdP(t, oidcVerifyClaims())
+
+	cases := []struct {
+		name       string
+		mode       oauthserver.ErrorMode
+		wrongNonce bool
+		reason     string
+		checkWords []string
+	}{
+		{name: "control (no tamper)", reason: "ok"},
+		{name: "bad signature", mode: oauthserver.ErrorMode{IDTokenBadSignature: true}, reason: "id_token_invalid", checkWords: []string{"signature"}},
+		{name: "wrong iss", mode: oauthserver.ErrorMode{IDTokenWrongIssuer: true}, reason: "issuer_mismatch", checkWords: []string{"iss"}},
+		{name: "wrong aud", mode: oauthserver.ErrorMode{IDTokenWrongAudience: true}, reason: "audience_mismatch", checkWords: []string{"aud"}},
+		{name: "multi-aud without matching azp", mode: oauthserver.ErrorMode{IDTokenMultiAudNoAzp: true}, reason: "audience_mismatch", checkWords: []string{"azp", "aud"}},
+		// A present-but-non-string azp must never be silently treated as
+		// absent: with a single-audience token that would let the equality
+		// check be skipped entirely (cross-review round 8, chunk 1 P2).
+		{name: "azp present but non-string", mode: oauthserver.ErrorMode{IDTokenAzpNonString: true}, reason: "audience_mismatch", checkWords: []string{"azp"}},
+		{name: "expired", mode: oauthserver.ErrorMode{IDTokenExpired: true}, reason: "token_expired", checkWords: []string{"exp"}},
+		{name: "nbf in the future", mode: oauthserver.ErrorMode{IDTokenNbfFuture: true}, reason: "id_token_invalid", checkWords: []string{"nbf", "not valid yet", "not before"}},
+		{name: "wrong nonce", wrongNonce: true, reason: "nonce_mismatch", checkWords: []string{"nonce"}},
+		{name: "missing nonce", mode: oauthserver.ErrorMode{IDTokenNoNonce: true}, reason: "nonce_mismatch", checkWords: []string{"nonce"}},
+		{name: "alg none", mode: oauthserver.ErrorMode{IDTokenAlgNone: true}, reason: "id_token_invalid", checkWords: []string{"alg", "signing method", "none"}},
+		{name: "HS256", mode: oauthserver.ErrorMode{IDTokenHS256: true}, reason: "id_token_invalid", checkWords: []string{"alg", "signing method", "hs256"}},
+		{name: "unknown kid", mode: oauthserver.ErrorMode{IDTokenUnknownKid: true}, reason: "id_token_invalid", checkWords: []string{"kid", "key"}},
+		{name: "key-type/alg mismatch", mode: oauthserver.ErrorMode{IDTokenKeyAlgMismatch: true}, reason: "id_token_invalid", checkWords: []string{"alg", "kid", "key", "signing method"}},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			rig := newOIDCVerifyRig(t, idp, tc.mode, nil)
+			seeded := rig.seedAlice([]string{"ops"})
+
+			authURL := rig.login()
+			state := authURL.Query().Get("state")
+			if tc.wrongNonce {
+				// The only case without a knob: the handler stored the nonce
+				// beside the state; make the stored one disagree with the
+				// nonce the IdP will echo.
+				pending, ok := rig.pendingState(state)
+				require.True(t, ok)
+				require.Equal(t, rig.lastNonce, pending.Nonce, "the nonce sent to the IdP is the one stored beside the state")
+				pending.Nonce = "tampered-" + pending.Nonce
+			}
+			resp := rig.callback(rig.approve(authURL))
+			res := rig.lastResult()
+
+			assert.Equal(t, tc.reason, string(res.Reason))
+			_, stillPending := rig.pendingState(state)
+			assert.False(t, stillPending, "the state (and its nonce) is consumed on every callback")
+
+			if tc.reason == "ok" {
+				require.Equal(t, http.StatusFound, resp.StatusCode)
+				assert.Equal(t, "/ui/", resp.Header.Get("Location"))
+				after := rig.alice()
+				require.NotNil(t, after)
+				assert.Equal(t, seeded.ID, after.ID)
+				assert.Equal(t, seeded.ID, res.UserID)
+				assert.Equal(t, []string{"eng", "sre"}, after.Groups, "the control login rewrites the seed's groups from the verified token")
+				assert.True(t, after.LastLoginAt.After(seeded.LastLoginAt), "the control login advances last_login")
+				assert.Equal(t, 1, rig.userCount())
+				return
+			}
+
+			assert.Equal(t, http.StatusForbidden, resp.StatusCode, "every verification failure renders the one generic 403 page")
+			assert.Empty(t, resp.Cookies(), "no session cookie on a refused login")
+			assert.Empty(t, res.UserID, "the store is never consulted for an unverified token")
+			assert.Empty(t, res.EmailHash, "an unverified claim is never hashed")
+
+			after := rig.alice()
+			require.NotNil(t, after)
+			assert.Equal(t, seeded, after, "user store untouched: the seeded record is byte-for-byte what it was")
+			assert.Equal(t, 1, rig.userCount(), "no record created")
+
+			rig.assertLogNamesCheck(tc.reason, tc.checkWords...)
+			rig.assertLogNeverCarriesClaims()
+		})
+	}
+}
+
+// Unknown kid → exactly one JWKS refetch, then refuse. Caches are warmed by a
+// successful login first so the count is the refetch alone; the control shows
+// a warm cache serves a valid login with no JWKS fetch at all.
+func TestOIDCVerify_UnknownKidRefetchesJWKSOnce(t *testing.T) {
+	idp := startOIDCVerifyIdP(t, oidcVerifyClaims())
+	rig := newOIDCVerifyRig(t, idp, oauthserver.ErrorMode{}, nil)
+
+	// Warm: discovery + JWKS.
+	resp, res := rig.attempt()
+	require.Equal(t, http.StatusFound, resp.StatusCode)
+	require.Equal(t, "ok", string(res.Reason))
+	_, jwks, _, _ := rig.tap.counts()
+	require.GreaterOrEqual(t, jwks, 1, "the first verification fetched the JWKS")
+
+	// Control: warm caches, valid token → no JWKS fetch.
+	rig.tap.resetCounts()
+	resp, res = rig.attempt()
+	require.Equal(t, http.StatusFound, resp.StatusCode)
+	require.Equal(t, "ok", string(res.Reason))
+	discovery, jwks, _, _ := rig.tap.counts()
+	assert.Equal(t, 0, jwks, "a known kid is served from the cache")
+	assert.Equal(t, 0, discovery, "discovery is cached across logins (T036/T042)")
+
+	// Unknown kid: one refetch, then refuse.
+	idp.Server.SetErrorMode(oauthserver.ErrorMode{IDTokenUnknownKid: true})
+	rig.tap.resetCounts()
+	resp, res = rig.attempt()
+	assert.Equal(t, http.StatusForbidden, resp.StatusCode)
+	assert.Equal(t, "id_token_invalid", string(res.Reason))
+	_, jwks, _, _ = rig.tap.counts()
+	assert.Equal(t, 1, jwks, "exactly one JWKS refetch per unknown-kid attempt")
+
+	// The refetch did not poison the cache: the real kid still verifies.
+	idp.Server.SetErrorMode(oauthserver.ErrorMode{})
+	resp, res = rig.attempt()
+	assert.Equal(t, http.StatusFound, resp.StatusCode)
+	assert.Equal(t, "ok", string(res.Reason))
+}
+
+// --- FR-022 / US2.4: email_verified_policy × {true, false, absent} ------------
+
+func TestOIDCVerify_EmailVerifiedPolicy(t *testing.T) {
+	withTrue := startOIDCVerifyIdP(t, oidcVerifyClaims())
+
+	// "absent": the fake derives email_verified=true when the key is missing,
+	// so the claim is set to JSON null, which decodes to a nil *bool exactly
+	// like an absent claim (OAuthUserInfo.EmailVerified *bool, data-model §7).
+	absentClaims := oidcVerifyClaims()
+	absentClaims["email_verified"] = nil
+	withAbsent := startOIDCVerifyIdP(t, absentClaims)
+
+	type claimState struct {
+		name string
+		idp  *oauthserver.ServerResult
+		mode oauthserver.ErrorMode
+	}
+	states := []claimState{
+		{name: "true", idp: withTrue},
+		{name: "false", idp: withTrue, mode: oauthserver.ErrorMode{EmailVerifiedFalse: true}},
+		{name: "absent", idp: withAbsent},
+	}
+	// policy → claim state → login allowed?
+	expect := map[string]map[string]bool{
+		"refuse_false": {"true": true, "false": false, "absent": true},
+		"require_true": {"true": true, "false": false, "absent": false},
+		"ignore":       {"true": true, "false": true, "absent": true},
+	}
+
+	for _, policy := range []string{"refuse_false", "require_true", "ignore"} {
+		for _, st := range states {
+			allowed := expect[policy][st.name]
+			t.Run(fmt.Sprintf("%s/email_verified=%s", policy, st.name), func(t *testing.T) {
+				rig := newOIDCVerifyRig(t, st.idp, st.mode, func(c *config.ServerEditionConfig) {
+					c.OAuth.EmailVerifiedPolicy = policy
+				})
+
+				resp, res := rig.attempt()
+
+				if allowed {
+					assert.Equal(t, http.StatusFound, resp.StatusCode)
+					assert.Equal(t, "ok", string(res.Reason))
+					u := rig.alice()
+					require.NotNil(t, u, "the login created the record")
+					assert.Equal(t, u.ID, res.UserID)
+					assert.Equal(t, "oidc", u.Provider)
+					assert.Equal(t, oidcVerifySub, u.ProviderSubjectID)
+					return
+				}
+
+				assert.Equal(t, http.StatusForbidden, resp.StatusCode, "the generic 403 page")
+				assert.Equal(t, "email_unverified", string(res.Reason))
+				assert.Empty(t, res.UserID)
+				assert.Empty(t, res.EmailHash, "email_unverified carries neither user_id nor email_hash (FR-013)")
+				assert.Equal(t, 0, rig.userCount(), "user store untouched: no record created")
+				assert.Nil(t, rig.alice())
+				rig.assertLogNamesCheck("email_unverified", "email_verified")
+			})
+		}
+	}
+}
+
+// A present-but-non-boolean email_verified (e.g. a string) must never be
+// treated as absent: under the default refuse_false policy that would let a
+// malformed claim whose plain-text value is "false" log the user in anyway.
+// It is refused as id_token_invalid instead of being guessed (cross-review
+// round 7, chunk 1 P2).
+func TestOIDCVerify_EmailVerifiedMalformedType(t *testing.T) {
+	claims := oidcVerifyClaims()
+	claims["email_verified"] = "false" // string, not bool
+	idp := startOIDCVerifyIdP(t, claims)
+	rig := newOIDCVerifyRig(t, idp, oauthserver.ErrorMode{}, nil)
+
+	resp, res := rig.attempt()
+
+	assert.Equal(t, http.StatusForbidden, resp.StatusCode)
+	assert.Equal(t, "id_token_invalid", string(res.Reason))
+	assert.Equal(t, 0, rig.userCount(), "user store untouched: no record created")
+	assert.Nil(t, rig.alice())
+	rig.assertLogNamesCheck("id_token_invalid", "email_verified")
+}
+
+// --- FR-008 / FR-022 / US2.3: groups ------------------------------------------
+
+func TestOIDCVerify_GroupsFromToken(t *testing.T) {
+	idp := startOIDCVerifyIdP(t, oidcVerifyClaims())
+	rig := newOIDCVerifyRig(t, idp, oauthserver.ErrorMode{}, nil)
+
+	start := time.Now().UTC().Add(-time.Second)
+	resp, res := rig.attempt()
+	require.Equal(t, http.StatusFound, resp.StatusCode)
+	assert.Equal(t, "ok", string(res.Reason))
+	assert.NotContains(t, oidcFlags(res), "groups_claim_missing")
+
+	u := rig.alice()
+	require.NotNil(t, u)
+	assert.Equal(t, []string{"eng", "sre"}, u.Groups, "exactly the verified token's groups claim")
+	assert.False(t, u.GroupsUpdatedAt.IsZero())
+	assert.True(t, u.GroupsUpdatedAt.After(start))
+
+	_, _, _, userinfo := rig.tap.counts()
+	assert.Equal(t, 0, userinfo, "userinfo is not consulted when the token carries the claim")
+
+	// Wholesale replace on the next login: the claim now says something else.
+	// (The fake derives claims per login; change them through the knob-free
+	// route of re-seeding the record and asserting the token list wins.)
+	u.Groups = []string{"stale-a", "stale-b"}
+	require.NoError(t, rig.store.UpdateUser(u))
+	resp, res = rig.attempt()
+	require.Equal(t, http.StatusFound, resp.StatusCode)
+	assert.Equal(t, "ok", string(res.Reason))
+	assert.Equal(t, []string{"eng", "sre"}, rig.alice().Groups, "replaced wholesale, never merged")
+}
+
+// Groups come from /userinfo only when the token lacks the claim, and only
+// when userinfo's `sub` equals the verified token's `sub`. The fake has no
+// "groups only in userinfo" knob: a userinfo knob strips the claim from the
+// id_token, and the tap clears the knob right before the provider's userinfo
+// request so the endpoint answers with the real sub and groups.
+func TestOIDCVerify_GroupsFromUserinfoWhenTokenLacksClaim(t *testing.T) {
+	idp := startOIDCVerifyIdP(t, oidcVerifyClaims())
+	rig := newOIDCVerifyRig(t, idp, oauthserver.ErrorMode{UserinfoSubMismatch: true}, nil)
+	clean := oauthserver.ErrorMode{}
+	rig.tap.beforeUserinfo = &clean
+
+	resp, res := rig.attempt()
+	require.Equal(t, http.StatusFound, resp.StatusCode)
+	assert.Equal(t, "ok", string(res.Reason))
+	assert.NotContains(t, oidcFlags(res), "groups_claim_missing")
+
+	u := rig.alice()
+	require.NotNil(t, u)
+	assert.Equal(t, []string{"eng", "sre"}, u.Groups, "the userinfo groups, accepted because sub matched")
+	assert.False(t, u.GroupsUpdatedAt.IsZero())
+
+	_, _, _, userinfo := rig.tap.counts()
+	assert.Equal(t, 1, userinfo, "userinfo consulted exactly once")
+}
+
+func TestOIDCVerify_UserinfoSubjectMismatchRefuses(t *testing.T) {
+	idp := startOIDCVerifyIdP(t, oidcVerifyClaims())
+	rig := newOIDCVerifyRig(t, idp, oauthserver.ErrorMode{UserinfoSubMismatch: true}, nil)
+	seeded := rig.seedAlice([]string{"ops"})
+
+	resp, res := rig.attempt()
+
+	assert.Equal(t, http.StatusForbidden, resp.StatusCode, "the generic 403 page")
+	assert.Equal(t, "userinfo_subject_mismatch", string(res.Reason))
+	assert.Empty(t, res.UserID, "the record is never looked up on this path (FR-013)")
+	assert.Empty(t, resp.Cookies())
+
+	assert.Equal(t, seeded, rig.alice(), "user store untouched; stored groups untouched")
+	assert.Equal(t, 1, rig.userCount())
+	_, _, _, userinfo := rig.tap.counts()
+	assert.Equal(t, 1, userinfo, "no userinfo claim is read before the sub comparison, and no retry")
+	rig.assertLogNamesCheck("userinfo_subject_mismatch", "sub")
+}
+
+// A userinfo fetch that fails at the transport, redirect, status or decoding
+// level is provider_error → 503, login refused, store untouched, stored groups
+// not reset (an IdP hiccup never converts a grant into the default grant and
+// never logs a user in with []).
+func TestOIDCVerify_UserinfoFailureIsProviderError(t *testing.T) {
+	idp := startOIDCVerifyIdP(t, oidcVerifyClaims())
+
+	cases := []struct {
+		name          string
+		mode          oauthserver.ErrorMode
+		transportFail bool
+	}{
+		// UserinfoUnavailable only strips the claim from the id_token here; the
+		// request never reaches the fake — the tap fails it at the transport.
+		{name: "transport error", mode: oauthserver.ErrorMode{UserinfoUnavailable: true}, transportFail: true},
+		{name: "3xx to another origin", mode: oauthserver.ErrorMode{UserinfoRedirect: true}},
+		{name: "non-200", mode: oauthserver.ErrorMode{UserinfoUnavailable: true}},
+		{name: "non-JSON body", mode: oauthserver.ErrorMode{UserinfoNonJSON: true}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			rig := newOIDCVerifyRig(t, idp, tc.mode, nil)
+			if tc.transportFail {
+				rig.tap.failUserinfo = errors.New("injected transport failure")
+			}
+			seeded := rig.seedAlice([]string{"ops"})
+
+			resp, res := rig.attempt()
+
+			assert.Equal(t, http.StatusServiceUnavailable, resp.StatusCode, "unavailability is the one distinct class (US2.9)")
+			assert.Equal(t, "provider_error", string(res.Reason))
+			assert.Empty(t, res.UserID, "the record is never looked up on this path (FR-013)")
+			assert.Empty(t, resp.Cookies())
+
+			after := rig.alice()
+			require.NotNil(t, after)
+			assert.Equal(t, seeded, after, "user store untouched")
+			assert.Equal(t, []string{"ops"}, after.Groups, "stored groups untouched — never reset to []")
+			assert.Equal(t, 1, rig.userCount())
+
+			_, _, _, userinfo := rig.tap.counts()
+			assert.Equal(t, 1, userinfo, "userinfo attempted exactly once, no retry")
+			rig.assertLogNamesCheck("provider_error", "userinfo")
+			text := rig.logText(zapcore.DebugLevel)
+			assert.NotContains(t, text, rig.idp.ClientSecret, "never the client secret")
+			for _, tok := range rig.tap.tokens() {
+				assert.NotContains(t, text, tok, "never a token")
+			}
+		})
+	}
+}
+
+// Absent in both, a non-array/non-string shape, or an Entra overage marker →
+// stored groups [] (fail closed), login succeeds, `groups_claim_missing` on
+// the result's flags, and a warning naming the user id and the claim name —
+// never the token. A single string is a valid shape (US2.3: "a flat JSON
+// array of strings, or a single string") and is stored as one group.
+func TestOIDCVerify_GroupsClaimMissingFailsClosed(t *testing.T) {
+	withGroups := startOIDCVerifyIdP(t, oidcVerifyClaims())
+
+	objectClaims := oidcVerifyClaims()
+	objectClaims["groups"] = map[string]any{"value": "eng"} // neither array nor string
+	withObject := startOIDCVerifyIdP(t, objectClaims)
+
+	cases := []struct {
+		name            string
+		idp             *oauthserver.ServerResult
+		mode            oauthserver.ErrorMode
+		wantGroups      []string
+		wantMissing     bool
+		userinfoAtLeast int
+	}{
+		{name: "absent from the token and from userinfo", idp: withGroups, mode: oauthserver.ErrorMode{GroupsAbsentEverywhere: true}, wantGroups: []string{}, wantMissing: true, userinfoAtLeast: 1},
+		{name: "non-array non-string shape", idp: withObject, wantGroups: []string{}, wantMissing: true},
+		{name: "Entra overage marker", idp: withGroups, mode: oauthserver.ErrorMode{GroupsOverageMarker: true}, wantGroups: []string{}, wantMissing: true},
+		{name: "single string is one group", idp: withGroups, mode: oauthserver.ErrorMode{GroupsNonArray: true}, wantGroups: []string{"eng,sre"}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			rig := newOIDCVerifyRig(t, tc.idp, tc.mode, nil)
+
+			resp, res := rig.attempt()
+			require.Equal(t, http.StatusFound, resp.StatusCode, "the login succeeds")
+			assert.Equal(t, "ok", string(res.Reason))
+
+			u := rig.alice()
+			require.NotNil(t, u)
+			assert.Equal(t, u.ID, res.UserID)
+			assert.NotNil(t, u.Groups, "stored as [], never null")
+			assert.Equal(t, tc.wantGroups, u.Groups)
+			assert.False(t, u.GroupsUpdatedAt.IsZero(), "groups_updated_at is stamped even when the list is empty")
+
+			_, _, _, userinfo := rig.tap.counts()
+			assert.GreaterOrEqual(t, userinfo, tc.userinfoAtLeast, "the token lacked the claim, so userinfo was consulted")
+
+			if !tc.wantMissing {
+				assert.NotContains(t, oidcFlags(res), "groups_claim_missing")
+				return
+			}
+			assert.Contains(t, oidcFlags(res), "groups_claim_missing")
+
+			warn := rig.logText(zapcore.WarnLevel)
+			assert.Contains(t, warn, "groups_claim_missing", "a warning is logged")
+			assert.Contains(t, warn, oidcVerifyGroups, "the warning names the claim looked for")
+			assert.Contains(t, warn, u.ID, "the warning names the user id")
+			all := rig.logText(zapcore.DebugLevel)
+			for _, tok := range rig.tap.tokens() {
+				assert.NotContains(t, all, tok, "never the token")
+			}
+		})
+	}
+}
+
+// If the token endpoint answers without an access_token (RFC 6749 §5.1
+// requires it, but a misconfigured or hostile IdP could still omit it) and
+// the ID token lacks the groups claim, the provider cannot attempt the
+// userinfo fetch it is required to try (FR-008/FR-022). That is a fetch that
+// never happened for lack of a credential, not "claim absent" — treated the
+// same as any other userinfo failure class: provider_error, login refused,
+// store untouched (never a silent groups=[] login, cross-review round 3).
+func TestOIDCVerify_ResolveGroups_NoAccessTokenIsProviderError(t *testing.T) {
+	prov := newOIDCProvider(&config.ServerEditionOAuthConfig{GroupsClaim: "groups"})
+	prov.disc = &discoveryDoc{
+		UserinfoEndpoint: "https://idp.example/userinfo",
+		expiresAt:        time.Now().Add(time.Hour),
+	}
+	claims := &idTokenClaims{Subject: "alice", raw: map[string]any{}} // no "groups" claim
+
+	groups, missing, err := prov.resolveGroups(context.Background(), claims, "")
+
+	require.Error(t, err)
+	var oe *oidcError
+	require.ErrorAs(t, err, &oe)
+	assert.Equal(t, LoginProviderError, oe.reason)
+	assert.Nil(t, groups)
+	assert.False(t, missing, "not a fail-closed groups_claim_missing outcome")
+}
diff --git a/internal/serveredition/auth/session_store.go b/internal/serveredition/auth/session_store.go
index b01a2fb7f..1ea68dc0e 100644
--- a/internal/serveredition/auth/session_store.go
+++ b/internal/serveredition/auth/session_store.go
@@ -3,11 +3,10 @@
 package auth
 
 import (
-	"net"
 	"net/http"
-	"strings"
 	"time"
 
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/serveredition/users"
 )
 
@@ -16,34 +15,92 @@ const (
 	SessionCookieName = "mcpproxy_session"
 )
 
+// CookieSecurePolicy decides the Secure attribute of the session cookie
+// (Spec 107 FR-026, `session_cookie_secure`): "true" and "false" are
+// unconditional; "auto" (the default) is Secure when the deployment's
+// public_url is https, when the request arrived over in-process TLS, or when
+// a trusted proxy (FR-027, read live) says X-Forwarded-Proto: https.
+type CookieSecurePolicy struct {
+	// Mode is config.SessionCookieSecureAuto|True|False ("" = auto).
+	Mode string
+	// PublicURLHTTPS is whether server_edition.public_url is https
+	// (restart-pinned, resolved at setup).
+	PublicURLHTTPS bool
+	// TrustedProxies yields the LIVE trusted_proxies list; nil trusts nobody.
+	TrustedProxies config.TrustedProxiesProvider
+}
+
+// Secure resolves the policy for one request (nil = no request context).
+func (p CookieSecurePolicy) Secure(r *http.Request) bool {
+	switch p.Mode {
+	case config.SessionCookieSecureTrue:
+		return true
+	case config.SessionCookieSecureFalse:
+		return false
+	}
+	if p.PublicURLHTTPS {
+		return true
+	}
+	if r == nil {
+		return false
+	}
+	return config.ForwardedHeaders(r, p.trusted()).Scheme == "https"
+}
+
+func (p CookieSecurePolicy) trusted() []string {
+	if p.TrustedProxies == nil {
+		return nil
+	}
+	return p.TrustedProxies()
+}
+
 // SessionManager provides high-level session management on top of the
 // low-level BBolt UserStore. It adds HTTP cookie semantics, session creation
 // tied to OAuth login, and periodic cleanup of expired sessions.
 type SessionManager struct {
 	store      *users.UserStore
 	sessionTTL time.Duration
-	secure     bool // Set Secure flag on cookies (true for HTTPS)
+	policy     CookieSecurePolicy
 }
 
-// NewSessionManager creates a new SessionManager.
-//   - store: the BBolt-backed user/session store
-//   - sessionTTL: how long sessions remain valid
-//   - secure: whether to set the Secure flag on cookies (true for HTTPS deployments)
+// NewSessionManager creates a SessionManager with an unconditional Secure
+// decision (true → policy "true", false → policy "false") and no trusted
+// proxies. Production setup uses NewSessionManagerWithPolicy.
 func NewSessionManager(store *users.UserStore, sessionTTL time.Duration, secure bool) *SessionManager {
+	mode := config.SessionCookieSecureFalse
+	if secure {
+		mode = config.SessionCookieSecureTrue
+	}
+	return NewSessionManagerWithPolicy(store, sessionTTL, CookieSecurePolicy{Mode: mode})
+}
+
+// NewSessionManagerWithPolicy creates a SessionManager whose Secure decision
+// and client-IP resolution follow the given policy (Spec 107 FR-026/FR-027).
+func NewSessionManagerWithPolicy(store *users.UserStore, sessionTTL time.Duration, policy CookieSecurePolicy) *SessionManager {
 	return &SessionManager{
 		store:      store,
 		sessionTTL: sessionTTL,
-		secure:     secure,
+		policy:     policy,
 	}
 }
 
+// SecureFor resolves the Secure decision for one request.
+func (m *SessionManager) SecureFor(r *http.Request) bool {
+	return m.policy.Secure(r)
+}
+
 // CreateSession creates a new session for the given user, populating UserAgent
 // and IPAddress from the HTTP request. The caller is responsible for setting the
 // cookie on the response via SetSessionCookie.
 func (m *SessionManager) CreateSession(userID string, r *http.Request) (*users.Session, error) {
 	session := users.NewSession(userID, m.sessionTTL)
 	session.UserAgent = r.UserAgent()
-	session.IPAddress = extractIPAddress(r)
+	// FR-027: the forwarded client IP is believed only from a trusted proxy.
+	session.IPAddress = config.ForwardedHeaders(r, m.policy.trusted()).ClientIP
+	// The Secure decision is recorded on the session so the clearing cookie
+	// at logout carries the same attribute (RFC 6265 §4.1.2) whatever shape
+	// the logout request arrives in.
+	session.CookieSecure = m.policy.Secure(r)
 
 	if err := m.store.CreateSession(session); err != nil {
 		return nil, err
@@ -53,7 +110,8 @@ func (m *SessionManager) CreateSession(userID string, r *http.Request) (*users.S
 }
 
 // SetSessionCookie sets the session cookie on the HTTP response.
-// The cookie is HttpOnly, SameSite=Lax, with path "/" and MaxAge based on TTL.
+// The cookie is HttpOnly, SameSite=Lax, with path "/" and MaxAge based on TTL;
+// Secure is the decision recorded on the session at creation.
 func (m *SessionManager) SetSessionCookie(w http.ResponseWriter, session *users.Session) {
 	http.SetCookie(w, &http.Cookie{
 		Name:     SessionCookieName,
@@ -61,7 +119,7 @@ func (m *SessionManager) SetSessionCookie(w http.ResponseWriter, session *users.
 		Path:     "/",
 		MaxAge:   int(m.sessionTTL.Seconds()),
 		HttpOnly: true,
-		Secure:   m.secure,
+		Secure:   session.CookieSecure,
 		SameSite: http.SameSiteLaxMode,
 	})
 }
@@ -104,15 +162,30 @@ func (m *SessionManager) RevokeUserSessions(userID string) error {
 }
 
 // ClearSessionCookie sets the session cookie with MaxAge=-1 to instruct the
-// browser to delete it.
+// browser to delete it, with the policy's request-free Secure decision.
 func (m *SessionManager) ClearSessionCookie(w http.ResponseWriter) {
+	m.clearCookie(w, m.policy.Secure(nil))
+}
+
+// ClearSessionCookieFor clears the cookie of one session: Secure is what the
+// cookie was set with (recorded on the session), or else the policy resolved
+// for the logout request, so the browser accepts the deletion (RFC 6265).
+func (m *SessionManager) ClearSessionCookieFor(w http.ResponseWriter, r *http.Request, session *users.Session) {
+	secure := m.policy.Secure(r)
+	if session != nil && session.CookieSecure {
+		secure = true
+	}
+	m.clearCookie(w, secure)
+}
+
+func (m *SessionManager) clearCookie(w http.ResponseWriter, secure bool) {
 	http.SetCookie(w, &http.Cookie{
 		Name:     SessionCookieName,
 		Value:    "",
 		Path:     "/",
 		MaxAge:   -1,
 		HttpOnly: true,
-		Secure:   m.secure,
+		Secure:   secure,
 		SameSite: http.SameSiteLaxMode,
 	})
 }
@@ -122,29 +195,3 @@ func (m *SessionManager) ClearSessionCookie(w http.ResponseWriter) {
 func (m *SessionManager) CleanupExpired() (int, error) {
 	return m.store.CleanupExpiredSessions()
 }
-
-// extractIPAddress returns the client IP address from the request.
-// It checks X-Forwarded-For and X-Real-IP headers before falling back
-// to the remote address.
-func extractIPAddress(r *http.Request) string {
-	// Check X-Forwarded-For first (may contain multiple IPs)
-	if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
-		// Take the first IP (the original client)
-		if idx := strings.IndexByte(xff, ','); idx != -1 {
-			return strings.TrimSpace(xff[:idx])
-		}
-		return strings.TrimSpace(xff)
-	}
-
-	// Check X-Real-IP
-	if xri := r.Header.Get("X-Real-IP"); xri != "" {
-		return strings.TrimSpace(xri)
-	}
-
-	// Fall back to RemoteAddr (strip port)
-	host, _, err := net.SplitHostPort(r.RemoteAddr)
-	if err != nil {
-		return r.RemoteAddr
-	}
-	return host
-}
diff --git a/internal/serveredition/auth/session_store_test.go b/internal/serveredition/auth/session_store_test.go
index fb9f22584..4e108f18d 100644
--- a/internal/serveredition/auth/session_store_test.go
+++ b/internal/serveredition/auth/session_store_test.go
@@ -47,28 +47,61 @@ func TestSessionManager_CreateSession(t *testing.T) {
 	assert.WithinDuration(t, time.Now().Add(time.Hour), session.ExpiresAt, 5*time.Second)
 }
 
+// Spec 107 FR-027: forwarded headers are believed only from a trusted proxy
+// (the legacy bool constructor trusts nobody); the client IP is the
+// right-most X-Forwarded-For hop that is not itself a trusted proxy.
 func TestSessionManager_CreateSession_XForwardedFor(t *testing.T) {
-	mgr := setupTestSessionManager(t, time.Hour, false)
+	t.Run("untrusted peer is ignored", func(t *testing.T) {
+		mgr := setupTestSessionManager(t, time.Hour, false)
 
-	req := httptest.NewRequest(http.MethodGet, "/", nil)
-	req.Header.Set("X-Forwarded-For", "10.0.0.1, 10.0.0.2")
-	req.RemoteAddr = "127.0.0.1:8080"
+		req := httptest.NewRequest(http.MethodGet, "/", nil)
+		req.Header.Set("X-Forwarded-For", "10.0.0.1, 10.0.0.2")
+		req.RemoteAddr = "127.0.0.1:8080"
 
-	session, err := mgr.CreateSession("user-xff", req)
-	require.NoError(t, err)
-	assert.Equal(t, "10.0.0.1", session.IPAddress)
+		session, err := mgr.CreateSession("user-xff", req)
+		require.NoError(t, err)
+		assert.Equal(t, "127.0.0.1", session.IPAddress)
+	})
+
+	t.Run("trusted peer: right-most untrusted hop", func(t *testing.T) {
+		mgr := setupTestSessionManager(t, time.Hour, false)
+		mgr.policy.TrustedProxies = func() []string { return []string{"127.0.0.1/32", "10.0.0.2/32"} }
+
+		req := httptest.NewRequest(http.MethodGet, "/", nil)
+		req.Header.Set("X-Forwarded-For", "10.0.0.1, 10.0.0.2")
+		req.RemoteAddr = "127.0.0.1:8080"
+
+		session, err := mgr.CreateSession("user-xff", req)
+		require.NoError(t, err)
+		assert.Equal(t, "10.0.0.1", session.IPAddress)
+	})
 }
 
 func TestSessionManager_CreateSession_XRealIP(t *testing.T) {
-	mgr := setupTestSessionManager(t, time.Hour, false)
+	t.Run("untrusted peer is ignored", func(t *testing.T) {
+		mgr := setupTestSessionManager(t, time.Hour, false)
 
-	req := httptest.NewRequest(http.MethodGet, "/", nil)
-	req.Header.Set("X-Real-IP", "172.16.0.5")
-	req.RemoteAddr = "127.0.0.1:8080"
+		req := httptest.NewRequest(http.MethodGet, "/", nil)
+		req.Header.Set("X-Real-IP", "172.16.0.5")
+		req.RemoteAddr = "127.0.0.1:8080"
 
-	session, err := mgr.CreateSession("user-xri", req)
-	require.NoError(t, err)
-	assert.Equal(t, "172.16.0.5", session.IPAddress)
+		session, err := mgr.CreateSession("user-xri", req)
+		require.NoError(t, err)
+		assert.Equal(t, "127.0.0.1", session.IPAddress)
+	})
+
+	t.Run("trusted peer is honoured", func(t *testing.T) {
+		mgr := setupTestSessionManager(t, time.Hour, false)
+		mgr.policy.TrustedProxies = func() []string { return []string{"127.0.0.1/32"} }
+
+		req := httptest.NewRequest(http.MethodGet, "/", nil)
+		req.Header.Set("X-Real-IP", "172.16.0.5")
+		req.RemoteAddr = "127.0.0.1:8080"
+
+		session, err := mgr.CreateSession("user-xri", req)
+		require.NoError(t, err)
+		assert.Equal(t, "172.16.0.5", session.IPAddress)
+	})
 }
 
 func TestSessionManager_SetAndGetSessionCookie(t *testing.T) {
diff --git a/internal/serveredition/broker/oauth_connector.go b/internal/serveredition/broker/oauth_connector.go
index ea5f7d0d8..fe6efca14 100644
--- a/internal/serveredition/broker/oauth_connector.go
+++ b/internal/serveredition/broker/oauth_connector.go
@@ -156,6 +156,20 @@ func (c *OAuthConnector) emitConnect(ctx context.Context, userID, reason string)
 // ServerKey returns the store key this connector persists credentials under.
 func (c *OAuthConnector) ServerKey() string { return c.serverKey }
 
+// HasPendingFlow reports whether this connector currently holds at least one
+// in-flight connect flow (a state issued by BuildAuthorizationURL and not yet
+// consumed by Complete/Deny or expired). A cache that evicts connectors by
+// age alone can drop one mid-flow out from under its user, turning their
+// upcoming callback into a spurious invalid-state failure; callers use this
+// to prefer evicting an idle connector instead (cross-review round 8, chunk 3
+// P2).
+func (c *OAuthConnector) HasPendingFlow() bool {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.gcExpiredLocked()
+	return len(c.pending) > 0
+}
+
 // BuildAuthorizationURL starts a connect flow for userID. It generates a PKCE
 // verifier/challenge and an opaque state, records the pending flow, and returns
 // the upstream authorize URL (to which the gateway redirects the user) plus the
diff --git a/internal/serveredition/front_door_test.go b/internal/serveredition/front_door_test.go
new file mode 100644
index 000000000..4a35799b2
--- /dev/null
+++ b/internal/serveredition/front_door_test.go
@@ -0,0 +1,1009 @@
+//go:build server
+
+package serveredition
+
+// Spec 107 T048 (PR-B, Phase B.3) — the front door behind an ingress, driven
+// through the PRODUCTION setup and route table (the T046 harness) so a wiring
+// mistake in setup.go fails here even when every handler-level test passes.
+//
+// Compile-red until T050 (`config.Config.TrustedProxies`, the trusted-proxy
+// provider) and T051 (`ServerEditionConfig.PublicURL`,
+// `ServerEditionConfig.SessionCookieSecure`, the Secure-policy session
+// manager, the boot lines, the MCPPROXY_PUBLIC_URL override). Contract
+// exercised (spec FR-025..FR-027, US2.1, US2.6; contracts/config-keys.md rows
+// `public_url`, `session_cookie_secure`, `trusted_proxies`; research D10):
+//
+//	// T050 — edition-neutral, top-level, live.
+//	config.Config.TrustedProxies []string   // CIDR or IP; default empty = trust nobody
+//	// T051 — server build.
+//	config.ServerEditionConfig.PublicURL           string // absolute origin, no path; env MCPPROXY_PUBLIC_URL
+//	config.ServerEditionConfig.SessionCookieSecure string // "auto" (default) | "true" | "false"
+//
+// Behaviour pinned:
+//   - public_url set → redirect_uri is `<public_url>/api/v1/auth/callback`
+//     whatever Host or X-Forwarded-* say; the cookie is Secure for an https
+//     public_url; a callback that arrives over plain http while public_url is
+//     https logs ONE operator-readable warning carrying the request id and
+//     the login is never blocked (FR-025).
+//   - public_url unset → X-Forwarded-Proto / X-Forwarded-For / X-Forwarded-Host
+//     are honoured only when RemoteAddr is inside trusted_proxies, the client
+//     IP is the right-most untrusted hop, otherwise the listener scheme and
+//     RemoteAddr are used (FR-027).
+//   - session_cookie_secure auto|true|false matrix (FR-026); validation refuses
+//     `false` with an https public_url or tls.enabled through BOTH
+//     Config.Validate (boot) and ValidateDetailed (PATCH, /config/apply);
+//     explicit `false` elsewhere is honoured with one boot warning.
+//   - boot: one INFO line with the resolved public URL and callback URL and no
+//     IdP request (US2.1); unset public_url on a non-loopback listener → one
+//     boot warning (the `doctor` finding is asserted through the management
+//     service in internal/management/diagnostics_serveredition_test.go, T052).
+//   - MCPPROXY_PUBLIC_URL overrides the file value; an unset variable leaves
+//     it (the personal build's twin is internal/config/env_public_url_personal_test.go).
+//   - the per-user connect flow's base URL follows public_url with no
+//     first-seen latch (connector_provider.go).
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.etcd.io/bbolt"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapcore"
+	"go.uber.org/zap/zaptest/observer"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/auth"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/reqcontext"
+	teamsauth "github.com/smart-mcp-proxy/mcpproxy-go/internal/serveredition/auth"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/serveredition/users"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/storage"
+	"github.com/smart-mcp-proxy/mcpproxy-go/tests/oauthserver"
+)
+
+const (
+	fdUser            = "alice@example.com"
+	fdPassword        = "pass"
+	fdPublicHTTPS     = "https://mcp.example.com"
+	fdPublicHTTP      = "http://mcp.example.com"
+	fdCallbackPath    = "/api/v1/auth/callback"
+	fdLoopbackListen  = "127.0.0.1:8080"
+	fdAnyListen       = "0.0.0.0:8080"
+	fdRequestIDHeader = "X-Test-Request-Id"
+	fdIngressHost     = "127.0.0.1:8080"
+	fdCookieName      = teamsauth.SessionCookieName
+
+	// The FR-025 scheme-disagreement wording; the assertion below matches the
+	// two halves separately so a re-phrased line that keeps the substance
+	// still passes.
+	fdSchemeWarnPublic = "public_url is https"
+	fdSchemeWarnHTTP   = "arrived over http"
+)
+
+// The callback the fake IdP accepts for a loopback host (any port, any
+// scheme — tests/oauthserver's localhost rule), plus the two public ones.
+var fdRegisteredCallbacks = []string{
+	"http://127.0.0.1" + fdCallbackPath,
+	fdPublicHTTPS + fdCallbackPath,
+	fdPublicHTTP + fdCallbackPath,
+}
+
+// frontDoorOptions shapes one deployment: the config keys under test, the
+// listener the config declares, and whether the harness itself terminates
+// TLS (an in-process https listener).
+type frontDoorOptions struct {
+	PublicURL           string
+	SessionCookieSecure string
+	TrustedProxies      []string
+	Listen              string // default fdLoopbackListen
+	TLS                 bool   // in-process TLS: cfg.TLS.Enabled and an https httptest listener
+	// IssuerURL replaces the fake IdP (no fake is started); used with a
+	// counting issuer to prove setup makes no IdP request.
+	IssuerURL string
+	Servers   []*config.ServerConfig
+	// CredentialKey enables the per-user credential store (connect flow).
+	CredentialKey string
+}
+
+// frontDoorHarness is the T046 harness with an observed logger, a request-id
+// middleware and the front-door keys threaded through the production setup.
+type frontDoorHarness struct {
+	t        *testing.T
+	opts     frontDoorOptions
+	router   *chi.Mux
+	server   *httptest.Server
+	idp      *oauthserver.ServerResult
+	users    *users.UserStore
+	hmacKey  []byte
+	logs     *observer.ObservedLogs
+	cfgMu    sync.RWMutex
+	cfg      *config.Config
+	setupErr error
+}
+
+// currentConfig is the live provider handed to setup (read-only snapshot).
+func (h *frontDoorHarness) currentConfig() *config.Config {
+	h.cfgMu.RLock()
+	defer h.cfgMu.RUnlock()
+	return h.cfg
+}
+
+// setTrustedProxies replaces the live trusted_proxies list the way a hot
+// reload does: copy-on-write, a new snapshot pointer, no re-setup.
+func (h *frontDoorHarness) setTrustedProxies(list []string) {
+	h.cfgMu.Lock()
+	defer h.cfgMu.Unlock()
+	next := *h.cfg
+	next.TrustedProxies = list
+	h.cfg = &next
+}
+
+func newFrontDoorHarness(t *testing.T, opts frontDoorOptions) *frontDoorHarness {
+	t.Helper()
+
+	h := &frontDoorHarness{t: t, opts: opts}
+	if opts.Listen == "" {
+		opts.Listen = fdLoopbackListen
+	}
+
+	oauthCfg := &config.ServerEditionOAuthConfig{
+		Provider:            "oidc",
+		AllowInsecureIssuer: true, // loopback http fake
+		Scopes:              []string{"openid", "profile", "email"},
+		GroupsClaim:         "groups",
+		EmailVerifiedPolicy: config.EmailVerifiedPolicyRefuseFalse,
+	}
+	if opts.IssuerURL != "" {
+		oauthCfg.IssuerURL = opts.IssuerURL
+		oauthCfg.ClientID = "counting-client"
+		oauthCfg.ClientSecret = "counting-secret"
+	} else {
+		h.idp = oauthserver.Start(t, oauthserver.Options{
+			OIDC:       true,
+			ValidUsers: map[string]string{fdUser: fdPassword},
+			UserClaims: map[string]map[string]any{fdUser: {
+				"email": fdUser, "email_verified": true, "name": "Alice", "groups": []any{"eng"},
+			}},
+			ClientRedirectURIs: fdRegisteredCallbacks,
+			GroupsClaim:        "groups",
+		})
+		t.Cleanup(func() { _ = h.idp.Shutdown() })
+		oauthCfg.IssuerURL = h.idp.IssuerURL
+		oauthCfg.ClientID = h.idp.ClientID
+		oauthCfg.ClientSecret = h.idp.ClientSecret
+	}
+
+	tmpDir := t.TempDir()
+	db, err := bbolt.Open(filepath.Join(tmpDir, "front-door.db"), 0600, &bbolt.Options{Timeout: time.Second})
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = db.Close() })
+
+	core, logs := observer.New(zapcore.DebugLevel)
+	logger := zap.New(core).Sugar()
+	h.logs = logs
+
+	tokens, err := storage.NewManager(t.TempDir(), zap.NewNop().Sugar())
+	require.NoError(t, err)
+	t.Cleanup(func() { tokens.Close() })
+
+	h.cfg = &config.Config{
+		Listen:         opts.Listen,
+		DataDir:        tmpDir,
+		TrustedProxies: opts.TrustedProxies,
+		Servers:        opts.Servers,
+		ServerEdition: &config.ServerEditionConfig{
+			Enabled:                 true,
+			AdminEmails:             []string{"admin@example.com"},
+			SessionTTL:              config.Duration(24 * time.Hour),
+			BearerTokenTTL:          config.Duration(24 * time.Hour),
+			OAuth:                   oauthCfg,
+			PublicURL:               opts.PublicURL,
+			SessionCookieSecure:     opts.SessionCookieSecure,
+			CredentialEncryptionKey: opts.CredentialKey,
+		},
+	}
+	if opts.TLS {
+		h.cfg.TLS = &config.TLSConfig{Enabled: true}
+	}
+
+	// The production request-id middleware lives in internal/httpapi; the
+	// harness stamps the id from a test header so a log line can be keyed
+	// to one request.
+	h.router = chi.NewRouter()
+	h.router.Use(func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if rid := r.Header.Get(fdRequestIDHeader); rid != "" {
+				r = r.WithContext(reqcontext.WithRequestID(r.Context(), rid))
+			}
+			next.ServeHTTP(w, r)
+		})
+	})
+
+	h.setupErr = setupMultiUserOAuth(Dependencies{
+		Router:         h.router,
+		DB:             db,
+		Logger:         logger,
+		DataDir:        tmpDir,
+		Config:         h.cfg,
+		ConfigProvider: h.currentConfig,
+		StorageManager: tokens,
+	})
+
+	h.users = users.NewUserStore(db)
+	h.hmacKey, err = auth.GetOrCreateHMACKey(tmpDir)
+	require.NoError(t, err)
+
+	if opts.TLS {
+		h.server = httptest.NewTLSServer(h.router)
+	} else {
+		h.server = httptest.NewServer(h.router)
+	}
+	t.Cleanup(h.server.Close)
+	return h
+}
+
+// client returns a client that trusts the harness listener (the httptest
+// certificate under TLS) and never follows redirects.
+func (h *frontDoorHarness) client() *http.Client {
+	c := h.server.Client()
+	c.Timeout = 5 * time.Second
+	c.CheckRedirect = func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }
+	return c
+}
+
+// frontDoorRequest shapes how one browser request reaches the proxy.
+type frontDoorRequest struct {
+	via       *httptest.Server  // nil = the harness listener directly
+	host      string            // Host header ("" = the listener's)
+	headers   map[string]string // e.g. X-Forwarded-Proto
+	requestID string
+}
+
+func (h *frontDoorHarness) do(t *testing.T, method, path string, fr frontDoorRequest) *http.Response {
+	t.Helper()
+	base := h.server.URL
+	client := h.client()
+	if fr.via != nil {
+		base = fr.via.URL
+		client = &http.Client{Timeout: 5 * time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
+	}
+	req, err := http.NewRequest(method, base+path, http.NoBody)
+	require.NoError(t, err)
+	if fr.host != "" {
+		req.Host = fr.host
+	}
+	for k, v := range fr.headers {
+		req.Header.Set(k, v)
+	}
+	if fr.requestID != "" {
+		req.Header.Set(fdRequestIDHeader, fr.requestID)
+	}
+	resp, err := client.Do(req)
+	require.NoError(t, err)
+	body, _ := io.ReadAll(resp.Body)
+	_ = resp.Body.Close()
+	resp.Body = io.NopCloser(strings.NewReader(string(body)))
+	return resp
+}
+
+// loginOutcome is what one complete login left behind.
+type loginOutcome struct {
+	// idpRedirectURI is the redirect_uri the handler put on the authorization
+	// URL — the callback the IdP is told to send the browser back to.
+	idpRedirectURI string
+	callback       *http.Response
+	cookie         *http.Cookie
+	session        *users.Session
+}
+
+// login drives login → the fake's form → callback, delivering the login and
+// the callback with the SAME front-door shaping (an ingress shapes every
+// request the same way). The callback request id is fr.requestID + "-cb".
+func (h *frontDoorHarness) login(t *testing.T, fr frontDoorRequest, redirectURI string) loginOutcome {
+	t.Helper()
+	require.NotNil(t, h.idp, "login needs the fake IdP")
+
+	q := url.Values{}
+	if redirectURI != "" {
+		q.Set("redirect_uri", redirectURI)
+	}
+	loginResp := h.do(t, http.MethodGet, "/api/v1/auth/login?"+q.Encode(), fr)
+	body, _ := io.ReadAll(loginResp.Body)
+	require.Equal(t, http.StatusFound, loginResp.StatusCode, "login must redirect to the IdP; body=%s", body)
+	authURL, err := url.Parse(loginResp.Header.Get("Location"))
+	require.NoError(t, err)
+	out := loginOutcome{idpRedirectURI: authURL.Query().Get("redirect_uri")}
+	require.NotEmpty(t, out.idpRedirectURI, "the authorization URL must carry redirect_uri")
+
+	form := authURL.Query()
+	form.Set("username", fdUser)
+	form.Set("password", fdPassword)
+	form.Set("consent", "on")
+	form.Set("action", "approve")
+	idpClient := &http.Client{Timeout: 5 * time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
+	idpResp, err := idpClient.PostForm(h.idp.AuthorizationEndpoint, form)
+	require.NoError(t, err)
+	idpBody, _ := io.ReadAll(idpResp.Body)
+	_ = idpResp.Body.Close()
+	require.Equal(t, http.StatusFound, idpResp.StatusCode, "the fake must redirect back with a code; body=%s", idpBody)
+	cb, err := url.Parse(idpResp.Header.Get("Location"))
+	require.NoError(t, err)
+	require.NotEmpty(t, cb.Query().Get("code"), "the IdP must answer with a code: %s", cb)
+
+	cbReq := fr
+	if fr.requestID != "" {
+		cbReq.requestID = fr.requestID + "-cb"
+	}
+	out.callback = h.do(t, http.MethodGet, cb.RequestURI(), cbReq)
+	for _, c := range out.callback.Cookies() {
+		if c.Name == fdCookieName {
+			out.cookie = c
+		}
+	}
+	if out.cookie != nil && out.cookie.Value != "" {
+		out.session, err = h.users.GetSession(out.cookie.Value)
+		require.NoError(t, err)
+	}
+	return out
+}
+
+// mustLogin is login with a successful callback required.
+func (h *frontDoorHarness) mustLogin(t *testing.T, fr frontDoorRequest) loginOutcome {
+	t.Helper()
+	out := h.login(t, fr, "/ui/")
+	body, _ := io.ReadAll(out.callback.Body)
+	require.Equal(t, http.StatusFound, out.callback.StatusCode, "callback must succeed; body=%s", body)
+	assert.Equal(t, "/ui/", out.callback.Header.Get("Location"))
+	require.NotNil(t, out.cookie, "the callback must set the session cookie")
+	require.NotNil(t, out.session, "the cookie must name a stored session")
+	assert.True(t, out.cookie.HttpOnly, "HttpOnly is unchanged (FR-026)")
+	assert.Equal(t, http.SameSiteLaxMode, out.cookie.SameSite, "SameSite=Lax is unchanged (FR-026)")
+	return out
+}
+
+// entriesWith returns the observed entries at the level whose message or any
+// string field contains every needle.
+func (h *frontDoorHarness) entriesWith(level zapcore.Level, needles ...string) []observer.LoggedEntry {
+	var out []observer.LoggedEntry
+	for _, e := range h.logs.All() {
+		if e.Level != level {
+			continue
+		}
+		hay := e.Message
+		for _, f := range e.Context {
+			hay += " " + f.Key + "=" + fieldString(f)
+		}
+		ok := true
+		for _, n := range needles {
+			if !strings.Contains(hay, n) {
+				ok = false
+				break
+			}
+		}
+		if ok {
+			out = append(out, e)
+		}
+	}
+	return out
+}
+
+func fieldString(f zapcore.Field) string {
+	switch f.Type {
+	case zapcore.StringType:
+		return f.String
+	case zapcore.StringerType:
+		if s, ok := f.Interface.(interface{ String() string }); ok {
+			return s.String()
+		}
+	}
+	if f.Interface != nil {
+		if b, err := json.Marshal(f.Interface); err == nil {
+			return string(b)
+		}
+	}
+	return ""
+}
+
+func fieldValue(e observer.LoggedEntry, key string) string {
+	for _, f := range e.Context {
+		if f.Key == key {
+			return fieldString(f)
+		}
+	}
+	return ""
+}
+
+// ---------------------------------------------------------------------------
+// public_url behind a Host-rewriting ingress (US2.6 first clause, FR-025)
+// ---------------------------------------------------------------------------
+
+// TestFrontDoor_PublicURLBehindHostRewritingIngress: the ingress rewrites Host
+// to the upstream address and strips X-Forwarded-Proto; with public_url set
+// the redirect_uri is still `<public_url>/api/v1/auth/callback`, the cookie is
+// Secure, the callback that arrived over plain http is logged (with the
+// callback's request id) and the login is never blocked.
+func TestFrontDoor_PublicURLBehindHostRewritingIngress(t *testing.T) {
+	h := newFrontDoorHarness(t, frontDoorOptions{PublicURL: fdPublicHTTPS})
+	require.NoError(t, h.setupErr)
+	ingress := newForwardingProxy(t, h.server, forwardingProxyOptions{
+		Host:  fdIngressHost,
+		Strip: []string{"X-Forwarded-Proto", "X-Forwarded-For", "X-Forwarded-Host"},
+	})
+
+	out := h.mustLogin(t, frontDoorRequest{
+		via:       ingress,
+		headers:   map[string]string{"X-Forwarded-Proto": "https"}, // stripped by the ingress
+		requestID: "rid-ingress",
+	})
+
+	assert.Equal(t, fdPublicHTTPS+fdCallbackPath, out.idpRedirectURI,
+		"public_url is the sole source of the IdP redirect_uri; the rewritten Host must not leak into it")
+	assert.True(t, out.cookie.Secure, "an https public_url makes the session cookie Secure under auto")
+
+	// The callback reached the proxy over plain http (the ingress terminates
+	// TLS and forwards http) while public_url says https: one warning, keyed
+	// by the callback's request id, and the login above still succeeded.
+	warns := h.entriesWith(zapcore.WarnLevel, fdSchemeWarnPublic, fdSchemeWarnHTTP)
+	require.Len(t, warns, 1, "exactly one scheme-disagreement warning for the callback; got %+v", h.logs.All())
+	assert.Equal(t, "rid-ingress-cb", fieldValue(warns[0], "request_id"),
+		"the warning must carry the request id so the operator can find the request")
+}
+
+// TestFrontDoor_PublicURLIgnoresHostAndForwardedHeaders: with public_url set,
+// Host-header injection and forwarded headers — trusted or not — never move
+// the callback (FR-025 "Host and X-Forwarded-* are then ignored").
+func TestFrontDoor_PublicURLIgnoresHostAndForwardedHeaders(t *testing.T) {
+	for _, trusted := range [][]string{nil, {"127.0.0.1/32", "::1/128"}} {
+		name := "untrusted"
+		if trusted != nil {
+			name = "trusted"
+		}
+		t.Run(name, func(t *testing.T) {
+			h := newFrontDoorHarness(t, frontDoorOptions{PublicURL: fdPublicHTTPS, TrustedProxies: trusted})
+			require.NoError(t, h.setupErr)
+
+			out := h.mustLogin(t, frontDoorRequest{
+				host: "evil.example",
+				headers: map[string]string{
+					"X-Forwarded-Proto": "http",
+					"X-Forwarded-Host":  "evil.example",
+					"X-Forwarded-For":   "1.2.3.4",
+				},
+				requestID: "rid-evil",
+			})
+			assert.Equal(t, fdPublicHTTPS+fdCallbackPath, out.idpRedirectURI)
+			assert.True(t, out.cookie.Secure, "public_url decides Secure, not the forwarded scheme")
+			if trusted != nil {
+				assert.Equal(t, "1.2.3.4", out.session.IPAddress, "the client IP still follows the trusted forwarded chain")
+			} else {
+				assert.Equal(t, "127.0.0.1", out.session.IPAddress, "an untrusted X-Forwarded-For never sets the session IP")
+			}
+		})
+	}
+}
+
+// ---------------------------------------------------------------------------
+// public_url unset: forwarded headers only from trusted proxies (US2.6, FR-027)
+// ---------------------------------------------------------------------------
+
+// TestFrontDoor_ForwardedHeadersOnlyFromTrustedProxies: the same request —
+// X-Forwarded-Proto: https, X-Forwarded-For: 1.2.3.4 — from an address outside
+// trusted_proxies is ignored (listener scheme, RemoteAddr); from a trusted
+// proxy it is honoured (https callback, Secure cookie, recorded IP).
+func TestFrontDoor_ForwardedHeadersOnlyFromTrustedProxies(t *testing.T) {
+	forwarded := map[string]string{
+		"X-Forwarded-Proto": "https",
+		"X-Forwarded-For":   "1.2.3.4",
+	}
+
+	t.Run("untrusted peer is ignored", func(t *testing.T) {
+		// A non-empty list that does NOT contain the loopback peer, so the
+		// case is not confused with "no list configured".
+		h := newFrontDoorHarness(t, frontDoorOptions{TrustedProxies: []string{"10.0.0.0/8"}})
+		require.NoError(t, h.setupErr)
+
+		out := h.mustLogin(t, frontDoorRequest{host: "mcp.example.com", headers: forwarded, requestID: "rid-untrusted"})
+		assert.Equal(t, fdPublicHTTP+fdCallbackPath, out.idpRedirectURI, "scheme from the listener, not the untrusted header")
+		assert.False(t, out.cookie.Secure, "an untrusted client cannot force Secure on an http deployment")
+		assert.Equal(t, "127.0.0.1", out.session.IPAddress, "RemoteAddr, not the untrusted X-Forwarded-For")
+		assert.Empty(t, h.entriesWith(zapcore.WarnLevel, fdSchemeWarnPublic), "no public_url, no scheme-disagreement warning")
+	})
+
+	t.Run("empty list trusts nobody", func(t *testing.T) {
+		h := newFrontDoorHarness(t, frontDoorOptions{})
+		require.NoError(t, h.setupErr)
+
+		out := h.mustLogin(t, frontDoorRequest{host: "mcp.example.com", headers: forwarded, requestID: "rid-nobody"})
+		assert.Equal(t, fdPublicHTTP+fdCallbackPath, out.idpRedirectURI)
+		assert.False(t, out.cookie.Secure)
+		assert.Equal(t, "127.0.0.1", out.session.IPAddress)
+	})
+
+	t.Run("trusted peer is honoured", func(t *testing.T) {
+		h := newFrontDoorHarness(t, frontDoorOptions{TrustedProxies: []string{"127.0.0.1/32", "::1/128"}})
+		require.NoError(t, h.setupErr)
+
+		out := h.mustLogin(t, frontDoorRequest{host: "mcp.example.com", headers: forwarded, requestID: "rid-trusted"})
+		assert.Equal(t, fdPublicHTTPS+fdCallbackPath, out.idpRedirectURI, "X-Forwarded-Proto from a trusted proxy sets the scheme")
+		assert.True(t, out.cookie.Secure, "a trusted https hop makes the cookie Secure under auto")
+		assert.Equal(t, "1.2.3.4", out.session.IPAddress, "X-Forwarded-For from a trusted proxy sets the session IP")
+	})
+
+	t.Run("trusted peer: right-most untrusted hop is the client", func(t *testing.T) {
+		h := newFrontDoorHarness(t, frontDoorOptions{TrustedProxies: []string{"127.0.0.1/32", "10.0.0.0/8"}})
+		require.NoError(t, h.setupErr)
+
+		out := h.mustLogin(t, frontDoorRequest{
+			host: "mcp.example.com",
+			headers: map[string]string{
+				"X-Forwarded-Proto": "https",
+				// spoofed by the client, real client, trusted internal hop
+				"X-Forwarded-For": "9.9.9.9, 1.2.3.4, 10.0.0.5",
+			},
+			requestID: "rid-hops",
+		})
+		assert.Equal(t, "1.2.3.4", out.session.IPAddress,
+			"the first hop is client-controlled; the client IP is the right-most address not in trusted_proxies")
+	})
+
+	t.Run("trusted X-Forwarded-Host rewrites the callback host", func(t *testing.T) {
+		h := newFrontDoorHarness(t, frontDoorOptions{TrustedProxies: []string{"127.0.0.1/32"}})
+		require.NoError(t, h.setupErr)
+
+		out := h.mustLogin(t, frontDoorRequest{
+			host:      fdIngressHost,
+			headers:   map[string]string{"X-Forwarded-Proto": "https", "X-Forwarded-Host": "mcp.example.com"},
+			requestID: "rid-xfh",
+		})
+		assert.Equal(t, fdPublicHTTPS+fdCallbackPath, out.idpRedirectURI)
+	})
+
+	t.Run("untrusted X-Forwarded-Host is ignored", func(t *testing.T) {
+		h := newFrontDoorHarness(t, frontDoorOptions{})
+		require.NoError(t, h.setupErr)
+
+		out := h.mustLogin(t, frontDoorRequest{
+			host:      fdIngressHost,
+			headers:   map[string]string{"X-Forwarded-Proto": "https", "X-Forwarded-Host": "mcp.example.com"},
+			requestID: "rid-xfh-untrusted",
+		})
+		assert.Equal(t, "http://"+fdIngressHost+fdCallbackPath, out.idpRedirectURI, "Host and the listener scheme")
+	})
+
+	t.Run("X-Real-IP only from a trusted peer", func(t *testing.T) {
+		for _, trusted := range [][]string{nil, {"127.0.0.1/32"}} {
+			h := newFrontDoorHarness(t, frontDoorOptions{TrustedProxies: trusted})
+			require.NoError(t, h.setupErr)
+			out := h.mustLogin(t, frontDoorRequest{headers: map[string]string{"X-Real-IP": "5.6.7.8"}, requestID: "rid-xri"})
+			if trusted == nil {
+				assert.Equal(t, "127.0.0.1", out.session.IPAddress)
+			} else {
+				assert.Equal(t, "5.6.7.8", out.session.IPAddress)
+			}
+		}
+	})
+}
+
+// TestFrontDoor_TrustedProxiesIsLive: the readers evaluate the provider per
+// request (contracts/config-keys.md: `trusted_proxies` is live). The same
+// headers are ignored, then honoured, then ignored again as the live
+// configuration changes — without re-running setup.
+func TestFrontDoor_TrustedProxiesIsLive(t *testing.T) {
+	h := newFrontDoorHarness(t, frontDoorOptions{})
+	require.NoError(t, h.setupErr)
+	forwarded := map[string]string{"X-Forwarded-Proto": "https", "X-Forwarded-For": "1.2.3.4"}
+
+	out := h.mustLogin(t, frontDoorRequest{host: "mcp.example.com", headers: forwarded, requestID: "rid-live-1"})
+	assert.Equal(t, "127.0.0.1", out.session.IPAddress)
+	assert.Equal(t, fdPublicHTTP+fdCallbackPath, out.idpRedirectURI)
+
+	h.setTrustedProxies([]string{"127.0.0.1/32"})
+	out = h.mustLogin(t, frontDoorRequest{host: "mcp.example.com", headers: forwarded, requestID: "rid-live-2"})
+	assert.Equal(t, "1.2.3.4", out.session.IPAddress, "a reader that captured the boot slice is not live")
+	assert.Equal(t, fdPublicHTTPS+fdCallbackPath, out.idpRedirectURI)
+
+	h.setTrustedProxies(nil)
+	out = h.mustLogin(t, frontDoorRequest{host: "mcp.example.com", headers: forwarded, requestID: "rid-live-3"})
+	assert.Equal(t, "127.0.0.1", out.session.IPAddress)
+	assert.Equal(t, fdPublicHTTP+fdCallbackPath, out.idpRedirectURI)
+}
+
+// ---------------------------------------------------------------------------
+// session_cookie_secure matrix (FR-026)
+// ---------------------------------------------------------------------------
+
+func TestFrontDoor_SessionCookieSecureMatrix(t *testing.T) {
+	cases := []struct {
+		name       string
+		opts       frontDoorOptions
+		host       string
+		headers    map[string]string
+		wantSecure bool
+	}{
+		{name: "auto, plain http loopback", opts: frontDoorOptions{SessionCookieSecure: "auto"}, wantSecure: false},
+		{name: "default (unset) is auto", opts: frontDoorOptions{}, wantSecure: false},
+		{name: "auto, https public_url", opts: frontDoorOptions{SessionCookieSecure: "auto", PublicURL: fdPublicHTTPS}, wantSecure: true},
+		{name: "auto, http public_url", opts: frontDoorOptions{SessionCookieSecure: "auto", PublicURL: fdPublicHTTP}, host: "mcp.example.com", wantSecure: false},
+		{name: "auto, in-process TLS", opts: frontDoorOptions{SessionCookieSecure: "auto", TLS: true}, wantSecure: true},
+		{name: "auto, trusted X-Forwarded-Proto https", opts: frontDoorOptions{SessionCookieSecure: "auto", TrustedProxies: []string{"127.0.0.1/32"}},
+			host: "mcp.example.com", headers: map[string]string{"X-Forwarded-Proto": "https"}, wantSecure: true},
+		{name: "auto, untrusted X-Forwarded-Proto https", opts: frontDoorOptions{SessionCookieSecure: "auto"},
+			host: "mcp.example.com", headers: map[string]string{"X-Forwarded-Proto": "https"}, wantSecure: false},
+		{name: "true, plain http", opts: frontDoorOptions{SessionCookieSecure: "true"}, wantSecure: true},
+		{name: "true, http public_url", opts: frontDoorOptions{SessionCookieSecure: "true", PublicURL: fdPublicHTTP}, host: "mcp.example.com", wantSecure: true},
+		{name: "false, plain http", opts: frontDoorOptions{SessionCookieSecure: "false"}, wantSecure: false},
+		{name: "false, http public_url", opts: frontDoorOptions{SessionCookieSecure: "false", PublicURL: fdPublicHTTP}, host: "mcp.example.com", wantSecure: false},
+		{name: "false, trusted X-Forwarded-Proto https is still false", opts: frontDoorOptions{SessionCookieSecure: "false", TrustedProxies: []string{"127.0.0.1/32"}},
+			host: "mcp.example.com", headers: map[string]string{"X-Forwarded-Proto": "https"}, wantSecure: false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			h := newFrontDoorHarness(t, tc.opts)
+			require.NoError(t, h.setupErr, "the matrix row must boot")
+
+			out := h.mustLogin(t, frontDoorRequest{host: tc.host, headers: tc.headers, requestID: "rid-matrix"})
+			assert.Equal(t, tc.wantSecure, out.cookie.Secure, "Secure attribute of the session cookie")
+
+			// Logout clears the cookie with the same attributes, or the
+			// browser keeps the Secure one (RFC 6265 §4.1.2).
+			logout, err := http.NewRequest(http.MethodPost, h.server.URL+"/api/v1/auth/logout", http.NoBody)
+			require.NoError(t, err)
+			logout.AddCookie(&http.Cookie{Name: fdCookieName, Value: out.cookie.Value})
+			resp, err := h.client().Do(logout)
+			require.NoError(t, err)
+			_, _ = io.Copy(io.Discard, resp.Body)
+			_ = resp.Body.Close()
+			require.Equal(t, http.StatusOK, resp.StatusCode)
+			var cleared *http.Cookie
+			for _, c := range resp.Cookies() {
+				if c.Name == fdCookieName {
+					cleared = c
+				}
+			}
+			require.NotNil(t, cleared, "logout must clear the cookie")
+			assert.Equal(t, tc.wantSecure, cleared.Secure, "the clearing cookie carries the same Secure decision")
+		})
+	}
+}
+
+// TestFrontDoor_ExplicitFalseWarnsAtBoot: an explicit `false` on a plain-http
+// deployment is honoured with ONE startup warning naming the key (its only
+// legitimate use is a plain-http loopback or test deployment); `auto` and
+// `true` warn about nothing.
+func TestFrontDoor_ExplicitFalseWarnsAtBoot(t *testing.T) {
+	for _, policy := range []string{"false", "auto", "true", ""} {
+		t.Run("policy="+policy, func(t *testing.T) {
+			h := newFrontDoorHarness(t, frontDoorOptions{SessionCookieSecure: policy, PublicURL: "http://127.0.0.1:8080"})
+			require.NoError(t, h.setupErr)
+			warns := h.entriesWith(zapcore.WarnLevel, "session_cookie_secure")
+			if policy == "false" {
+				assert.Len(t, warns, 1, "exactly one boot warning for an explicit false; got %+v", warns)
+			} else {
+				assert.Empty(t, warns, "no warning for %q", policy)
+			}
+		})
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Boot lines (US2.1, FR-025)
+// ---------------------------------------------------------------------------
+
+// TestFrontDoor_BootLogsResolvedURLsWithoutContactingIdP: with public_url set,
+// setup logs one INFO line carrying the resolved public URL and the callback
+// URL, and makes no request to the issuer (discovery stays lazy).
+func TestFrontDoor_BootLogsResolvedURLsWithoutContactingIdP(t *testing.T) {
+	var hits atomic.Int32
+	issuer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		hits.Add(1)
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	t.Cleanup(issuer.Close)
+
+	h := newFrontDoorHarness(t, frontDoorOptions{PublicURL: fdPublicHTTPS, IssuerURL: issuer.URL})
+	require.NoError(t, h.setupErr)
+
+	infos := h.entriesWith(zapcore.InfoLevel, fdPublicHTTPS+fdCallbackPath)
+	require.Len(t, infos, 1, "exactly one INFO boot line carrying the callback URL; got %+v", h.logs.All())
+	assert.Contains(t, fieldsJoined(infos[0]), fdPublicHTTPS, "the same line carries the resolved public URL")
+	assert.Equal(t, int32(0), hits.Load(), "setup must not contact the IdP (discovery is lazy, US2.1)")
+}
+
+func fieldsJoined(e observer.LoggedEntry) string {
+	parts := []string{e.Message}
+	for _, f := range e.Context {
+		parts = append(parts, f.Key+"="+fieldString(f))
+	}
+	return strings.Join(parts, " ")
+}
+
+// TestFrontDoor_UnsetPublicURLOnNonLoopbackListenerWarns: the published image
+// listens on 0.0.0.0:8080 with no public_url — that is a boot warning
+// recommending the key, never a validation error; a loopback listener and a
+// set public_url warn about nothing. (The `doctor` finding of the same case
+// is asserted through the management service in
+// internal/management/diagnostics_serveredition_test.go, T052.)
+func TestFrontDoor_UnsetPublicURLOnNonLoopbackListenerWarns(t *testing.T) {
+	cases := []struct {
+		name     string
+		listen   string
+		public   string
+		wantWarn bool
+	}{
+		{name: "0.0.0.0 without public_url", listen: fdAnyListen, public: "", wantWarn: true},
+		{name: "[::] without public_url", listen: "[::]:8080", public: "", wantWarn: true},
+		{name: "0.0.0.0 with public_url", listen: fdAnyListen, public: fdPublicHTTPS, wantWarn: false},
+		{name: "loopback without public_url", listen: fdLoopbackListen, public: "", wantWarn: false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			h := newFrontDoorHarness(t, frontDoorOptions{Listen: tc.listen, PublicURL: tc.public})
+			require.NoError(t, h.setupErr, "never a validation error (FR-025)")
+			warns := h.entriesWith(zapcore.WarnLevel, "public_url")
+			if tc.wantWarn {
+				assert.Len(t, warns, 1, "one boot warning recommending public_url; got %+v", warns)
+			} else {
+				assert.Empty(t, warns)
+			}
+		})
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Validation through both doors (FR-025, FR-026, FR-039)
+// ---------------------------------------------------------------------------
+
+// frontDoorConfig returns a Config that passes Config.Validate on its own
+// with the given front-door keys.
+func frontDoorConfig(publicURL, cookieSecure string, tls bool) *config.Config {
+	cfg := &config.Config{
+		Listen:            fdLoopbackListen,
+		ToolsLimit:        15,
+		ToolResponseLimit: 1000,
+		CallToolTimeout:   config.Duration(time.Minute),
+		Servers:           []*config.ServerConfig{},
+		ServerEdition: &config.ServerEditionConfig{
+			Enabled:     true,
+			AdminEmails: []string{"admin@example.com"},
+			OAuth: &config.ServerEditionOAuthConfig{
+				Provider:     "google",
+				ClientID:     "cid",
+				ClientSecret: "csec",
+			},
+			PublicURL:           publicURL,
+			SessionCookieSecure: cookieSecure,
+		},
+	}
+	if tls {
+		cfg.TLS = &config.TLSConfig{Enabled: true}
+	}
+	return cfg
+}
+
+const (
+	msgSecureFalseRefused = "server_edition.session_cookie_secure=false cannot be combined with an https public_url or tls.enabled"
+	msgPublicURLShape     = "server_edition.public_url must be an absolute origin (scheme://host[:port]) with no path"
+)
+
+// TestFrontDoor_ValidationBothDoors: every rule is applied identically by
+// Config.Validate (boot) and ValidateDetailed (PATCH /api/v1/config and
+// /config/apply both call it — internal/runtime/runtime.go ValidateConfig /
+// applyConfigLocked), with the message text of contracts/config-keys.md.
+func TestFrontDoor_ValidationBothDoors(t *testing.T) {
+	cases := []struct {
+		name       string
+		publicURL  string
+		secure     string
+		tls        bool
+		wantErrMsg string // "" = valid
+	}{
+		{name: "false with https public_url is refused", publicURL: fdPublicHTTPS, secure: "false", wantErrMsg: msgSecureFalseRefused},
+		{name: "false with in-process TLS is refused", publicURL: "", secure: "false", tls: true, wantErrMsg: msgSecureFalseRefused},
+		{name: "false with http public_url is allowed", publicURL: fdPublicHTTP, secure: "false"},
+		{name: "false with no public_url and no TLS is allowed", secure: "false"},
+		{name: "auto with https public_url", publicURL: fdPublicHTTPS, secure: "auto"},
+		{name: "true with http public_url is allowed (explicit)", publicURL: fdPublicHTTP, secure: "true"},
+		{name: "unknown policy is refused", secure: "yes", wantErrMsg: "server_edition.session_cookie_secure"},
+		{name: "public_url with a path is refused", publicURL: "https://mcp.example.com/proxy", wantErrMsg: msgPublicURLShape},
+		{name: "public_url with a trailing slash is refused", publicURL: "https://mcp.example.com/", wantErrMsg: msgPublicURLShape},
+		{name: "public_url with a query is refused", publicURL: "https://mcp.example.com?x=1", wantErrMsg: msgPublicURLShape},
+		{name: "public_url with a fragment is refused", publicURL: "https://mcp.example.com#f", wantErrMsg: msgPublicURLShape},
+		{name: "public_url without a scheme is refused", publicURL: "mcp.example.com", wantErrMsg: msgPublicURLShape},
+		{name: "public_url with a non-http scheme is refused", publicURL: "ftp://mcp.example.com", wantErrMsg: msgPublicURLShape},
+		{name: "public_url with userinfo is refused", publicURL: "https://user:pw@mcp.example.com", wantErrMsg: msgPublicURLShape},
+		{name: "public_url with a port is allowed", publicURL: "https://mcp.example.com:8443"},
+		{name: "http public_url is allowed", publicURL: fdPublicHTTP},
+		{name: "unset public_url is allowed", publicURL: ""},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			// Boot door.
+			err := frontDoorConfig(tc.publicURL, tc.secure, tc.tls).Validate()
+			// Write doors (PATCH, apply).
+			detailed := frontDoorConfig(tc.publicURL, tc.secure, tc.tls).ValidateDetailed()
+
+			if tc.wantErrMsg == "" {
+				assert.NoError(t, err, "Config.Validate")
+				assert.Empty(t, detailed, "ValidateDetailed")
+				return
+			}
+			require.Error(t, err, "Config.Validate must refuse")
+			assert.Contains(t, err.Error(), tc.wantErrMsg, "boot message")
+			require.NotEmpty(t, detailed, "ValidateDetailed must refuse identically")
+			found := false
+			for _, ve := range detailed {
+				if strings.Contains(ve.Message, tc.wantErrMsg) {
+					found = true
+				}
+			}
+			assert.True(t, found, "ValidateDetailed must carry the same message; got %+v", detailed)
+		})
+	}
+}
+
+// TestFrontDoor_SetupRefusesFalseWithHTTPSPublicURL: the boot door as setup
+// runs it — the process comes up with the feature disabled and the error
+// names the rule.
+func TestFrontDoor_SetupRefusesFalseWithHTTPSPublicURL(t *testing.T) {
+	h := newFrontDoorHarness(t, frontDoorOptions{PublicURL: fdPublicHTTPS, SessionCookieSecure: "false"})
+	require.Error(t, h.setupErr)
+	assert.Contains(t, h.setupErr.Error(), msgSecureFalseRefused)
+}
+
+// ---------------------------------------------------------------------------
+// MCPPROXY_PUBLIC_URL (FR-025, the one nested key with an env alias)
+// ---------------------------------------------------------------------------
+
+func writeFrontDoorConfigFile(t *testing.T, publicURL string) string {
+	t.Helper()
+	dir := t.TempDir()
+	doc := map[string]any{
+		"listen":   fdLoopbackListen,
+		"data_dir": dir,
+		"server_edition": map[string]any{
+			"enabled":      true,
+			"admin_emails": []string{"admin@example.com"},
+			"oauth":        map[string]any{"provider": "google", "client_id": "cid", "client_secret": "csec"},
+			"public_url":   publicURL,
+		},
+	}
+	data, err := json.Marshal(doc)
+	require.NoError(t, err)
+	path := filepath.Join(dir, "mcp_config.json")
+	require.NoError(t, os.WriteFile(path, data, 0600))
+	return path
+}
+
+func TestFrontDoor_PublicURLEnvOverride(t *testing.T) {
+	t.Run("env overrides the file value", func(t *testing.T) {
+		t.Setenv("MCPPROXY_PUBLIC_URL", "https://env.example")
+		cfg, err := config.LoadFromFile(writeFrontDoorConfigFile(t, "https://file.example"))
+		require.NoError(t, err)
+		assert.Equal(t, "https://env.example", cfg.ServerEdition.PublicURL)
+	})
+	t.Run("env sets an unset file value", func(t *testing.T) {
+		t.Setenv("MCPPROXY_PUBLIC_URL", "https://env.example")
+		cfg, err := config.LoadFromFile(writeFrontDoorConfigFile(t, ""))
+		require.NoError(t, err)
+		assert.Equal(t, "https://env.example", cfg.ServerEdition.PublicURL)
+	})
+	t.Run("unset env leaves the file value", func(t *testing.T) {
+		t.Setenv("MCPPROXY_PUBLIC_URL", "")
+		require.NoError(t, os.Unsetenv("MCPPROXY_PUBLIC_URL"))
+		cfg, err := config.LoadFromFile(writeFrontDoorConfigFile(t, "https://file.example"))
+		require.NoError(t, err)
+		assert.Equal(t, "https://file.example", cfg.ServerEdition.PublicURL)
+	})
+	t.Run("an invalid env value is refused like a file value", func(t *testing.T) {
+		t.Setenv("MCPPROXY_PUBLIC_URL", "https://env.example/path")
+		_, err := config.LoadFromFile(writeFrontDoorConfigFile(t, "https://file.example"))
+		require.Error(t, err, "the override goes through the same validation")
+		assert.Contains(t, err.Error(), msgPublicURLShape)
+	})
+}
+
+// ---------------------------------------------------------------------------
+// Connect-flow base URL follows public_url (FR-025, connector_provider.go)
+// ---------------------------------------------------------------------------
+
+func fdConnectServer(name string) *config.ServerConfig {
+	return &config.ServerConfig{
+		Name:     name,
+		URL:      "https://" + name + ".example.com/mcp",
+		Protocol: "http",
+		Shared:   true,
+		Enabled:  true,
+		AuthBroker: &config.AuthBrokerConfig{
+			Mode:                  config.AuthBrokerModeOAuthConnect,
+			AuthorizationEndpoint: "https://as.example.com/authorize",
+			TokenEndpoint:         "https://as.example.com/token",
+			ClientID:              "client-" + name,
+			Scopes:                []string{"repo"},
+		},
+	}
+}
+
+// connectRedirectURI drives GET /api/v1/user/credentials/{server}/connect as
+// a tenant and returns the redirect_uri the proxy registered on the upstream
+// authorization URL.
+func (h *frontDoorHarness) connectRedirectURI(t *testing.T, bearer, server string, fr frontDoorRequest) string {
+	t.Helper()
+	if fr.headers == nil {
+		fr.headers = map[string]string{}
+	}
+	fr.headers["Authorization"] = "Bearer " + bearer
+	resp := h.do(t, http.MethodGet, "/api/v1/user/credentials/"+server+"/connect", fr)
+	body, _ := io.ReadAll(resp.Body)
+	require.Equal(t, http.StatusFound, resp.StatusCode, "connect must redirect to the upstream AS; body=%s", body)
+	loc, err := url.Parse(resp.Header.Get("Location"))
+	require.NoError(t, err)
+	return loc.Query().Get("redirect_uri")
+}
+
+func TestFrontDoor_ConnectFlowBaseURLFollowsPublicURL(t *testing.T) {
+	credKey := base64.StdEncoding.EncodeToString(make([]byte, 32))
+	const server = "gh"
+	wantPath := "/api/v1/user/credentials/" + server + "/callback"
+
+	t.Run("public_url set: never the Host, no first-seen latch", func(t *testing.T) {
+		h := newFrontDoorHarness(t, frontDoorOptions{
+			PublicURL:     fdPublicHTTPS,
+			Servers:       []*config.ServerConfig{fdConnectServer(server)},
+			CredentialKey: credKey,
+		})
+		require.NoError(t, h.setupErr)
+		u := users.NewUser("tenant@example.com", "Tenant", "oidc", "sub-tenant")
+		require.NoError(t, h.users.CreateUser(u))
+		bearer, err := teamsauth.GenerateBearerToken(h.hmacKey, u.ID, u.Email, u.DisplayName, "user", u.Provider, time.Hour)
+		require.NoError(t, err)
+
+		// The FIRST request carries a hostile Host and forwarded headers: a
+		// latch of the first-seen origin would poison every later connector.
+		first := h.connectRedirectURI(t, bearer, server, frontDoorRequest{
+			host:    "evil.example",
+			headers: map[string]string{"X-Forwarded-Proto": "http", "X-Forwarded-Host": "evil.example"},
+		})
+		assert.Equal(t, fdPublicHTTPS+wantPath, first)
+
+		second := h.connectRedirectURI(t, bearer, server, frontDoorRequest{host: fdIngressHost})
+		assert.Equal(t, fdPublicHTTPS+wantPath, second)
+	})
+
+	t.Run("public_url unset: forwarded scheme only from a trusted peer", func(t *testing.T) {
+		for _, trusted := range [][]string{nil, {"127.0.0.1/32"}} {
+			h := newFrontDoorHarness(t, frontDoorOptions{
+				TrustedProxies: trusted,
+				Servers:        []*config.ServerConfig{fdConnectServer(server)},
+				CredentialKey:  credKey,
+			})
+			require.NoError(t, h.setupErr)
+			u := users.NewUser("tenant@example.com", "Tenant", "oidc", "sub-tenant")
+			require.NoError(t, h.users.CreateUser(u))
+			bearer, err := teamsauth.GenerateBearerToken(h.hmacKey, u.ID, u.Email, u.DisplayName, "user", u.Provider, time.Hour)
+			require.NoError(t, err)
+
+			got := h.connectRedirectURI(t, bearer, server, frontDoorRequest{
+				host:    "mcp.example.com",
+				headers: map[string]string{"X-Forwarded-Proto": "https"},
+			})
+			if trusted == nil {
+				assert.Equal(t, fdPublicHTTP+wantPath, got, "untrusted X-Forwarded-Proto is ignored")
+			} else {
+				assert.Equal(t, fdPublicHTTPS+wantPath, got, "trusted X-Forwarded-Proto is honoured")
+			}
+		}
+	})
+}
diff --git a/internal/serveredition/harness_oidc_test.go b/internal/serveredition/harness_oidc_test.go
new file mode 100644
index 000000000..71ffb1c1d
--- /dev/null
+++ b/internal/serveredition/harness_oidc_test.go
@@ -0,0 +1,329 @@
+//go:build server
+
+package serveredition
+
+// Spec 107 T046: the wiring harness over an in-process OpenID Provider
+// (tests/oauthserver with Options.OIDC) so a test can drive a REAL login —
+// GET /api/v1/auth/login → the fake's headless form → the callback — through
+// the production setup and route table, and an httptest reverse proxy that
+// sets or strips the X-Forwarded-* headers and rewrites Host the way an
+// ingress does (for the PR-B front-door fixtures of Phase B.3).
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net"
+	"net/http"
+	"net/http/cookiejar"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+	"github.com/smart-mcp-proxy/mcpproxy-go/tests/oauthserver"
+)
+
+const (
+	harnessIdPPassword  = "pass"
+	harnessGroupsClaim  = "groups"
+	harnessCallbackHost = "127.0.0.1"
+)
+
+// harnessCallbackURI is the redirect_uri the handler derives from the request
+// Host the harness sends (no public_url in PR-B's harness).
+const harnessCallbackURI = "http://" + harnessCallbackHost + "/api/v1/auth/callback"
+
+// oidcWiringHarness is a wiringHarness whose provider is the in-process fake
+// IdP. Every user in `users` (email → groups) can log in with
+// harnessIdPPassword; their `sub` is derived by the fake from the email.
+type oidcWiringHarness struct {
+	*wiringHarness
+	idp      *oauthserver.ServerResult
+	idpUsers map[string][]string
+	// server serves the production router over TCP so the browser client and
+	// the reverse-proxy helper can reach it.
+	server *httptest.Server
+}
+
+// newOIDCWiringHarness starts the fake OpenID Provider with the given users
+// and drives the production setup with `provider: oidc` pointing at it.
+func newOIDCWiringHarness(t *testing.T, users map[string][]string) *oidcWiringHarness {
+	t.Helper()
+
+	valid := map[string]string{}
+	claims := map[string]map[string]any{}
+	for email, groups := range users {
+		valid[email] = harnessIdPPassword
+		gs := make([]any, 0, len(groups))
+		for _, g := range groups {
+			gs = append(gs, g)
+		}
+		claims[email] = map[string]any{
+			"email":            email,
+			"email_verified":   true,
+			"name":             strings.SplitN(email, "@", 2)[0],
+			harnessGroupsClaim: gs,
+		}
+	}
+	idp := oauthserver.Start(t, oauthserver.Options{
+		OIDC:               true,
+		ValidUsers:         valid,
+		UserClaims:         claims,
+		ClientRedirectURIs: []string{harnessCallbackURI},
+		GroupsClaim:        harnessGroupsClaim,
+	})
+	t.Cleanup(func() { _ = idp.Shutdown() })
+
+	base := newWiringHarnessWith(t, &config.ServerEditionOAuthConfig{
+		Provider:            "oidc",
+		ClientID:            idp.ClientID,
+		ClientSecret:        idp.ClientSecret,
+		IssuerURL:           idp.IssuerURL,
+		AllowInsecureIssuer: true, // loopback http fake
+		Scopes:              []string{"openid", "profile", "email"},
+		GroupsClaim:         harnessGroupsClaim,
+		EmailVerifiedPolicy: config.EmailVerifiedPolicyRefuseFalse,
+	})
+	h := &oidcWiringHarness{wiringHarness: base, idp: idp, idpUsers: users}
+	h.server = httptest.NewServer(h.router)
+	t.Cleanup(h.server.Close)
+	return h
+}
+
+// loginAs drives a complete login for email — login redirect, the fake's
+// headless form POST (username/password/consent), the callback — through the
+// production router, asserting the record now carries exactly `groups`, and
+// returns a cookie jar holding the session cookie for later requests. The
+// user must have been declared to newOIDCWiringHarness with those groups
+// (the fake's claims are fixed at start).
+func (h *oidcWiringHarness) loginAs(t *testing.T, email string, groups []string) http.CookieJar {
+	t.Helper()
+	declared, ok := h.idpUsers[email]
+	require.True(t, ok, "user %q must be declared to newOIDCWiringHarness", email)
+	require.Equal(t, groups, declared, "the fake's groups for %q are fixed at start", email)
+
+	jar, err := cookiejar.New(nil)
+	require.NoError(t, err)
+	noRedirect := &http.Client{
+		Timeout: 5 * time.Second,
+		CheckRedirect: func(*http.Request, []*http.Request) error {
+			return http.ErrUseLastResponse
+		},
+	}
+
+	// 1. GET /api/v1/auth/login → 302 to the IdP with state, nonce, PKCE.
+	loginReq, err := http.NewRequest(http.MethodGet, h.server.URL+"/api/v1/auth/login?redirect_uri=/ui/", nil)
+	require.NoError(t, err)
+	loginReq.Host = harnessCallbackHost
+	loginResp, err := noRedirect.Do(loginReq)
+	require.NoError(t, err)
+	_, _ = io.Copy(io.Discard, loginResp.Body)
+	_ = loginResp.Body.Close()
+	require.Equal(t, http.StatusFound, loginResp.StatusCode, "login must redirect to the IdP")
+	authURL, err := url.Parse(loginResp.Header.Get("Location"))
+	require.NoError(t, err)
+	require.NotEmpty(t, authURL.Query().Get("nonce"))
+
+	// 2. The fake's headless form → 302 back to the callback with a code.
+	form := authURL.Query()
+	form.Set("username", email)
+	form.Set("password", harnessIdPPassword)
+	form.Set("consent", "on")
+	form.Set("action", "approve")
+	idpResp, err := noRedirect.PostForm(h.idp.AuthorizationEndpoint, form)
+	require.NoError(t, err)
+	_, _ = io.Copy(io.Discard, idpResp.Body)
+	_ = idpResp.Body.Close()
+	require.Equal(t, http.StatusFound, idpResp.StatusCode, "the fake must redirect back with a code")
+	cb, err := url.Parse(idpResp.Header.Get("Location"))
+	require.NoError(t, err)
+	require.NotEmpty(t, cb.Query().Get("code"))
+
+	// 3. The callback on the production router, delivered as the browser would.
+	cbReq, err := http.NewRequest(http.MethodGet, h.server.URL+cb.RequestURI(), nil)
+	require.NoError(t, err)
+	cbReq.Host = harnessCallbackHost
+	cbResp, err := noRedirect.Do(cbReq)
+	require.NoError(t, err)
+	body, _ := io.ReadAll(cbResp.Body)
+	_ = cbResp.Body.Close()
+	require.Equal(t, http.StatusFound, cbResp.StatusCode, "callback must succeed; body=%s", body)
+	assert.Equal(t, "/ui/", cbResp.Header.Get("Location"))
+
+	serverURL, err := url.Parse(h.server.URL)
+	require.NoError(t, err)
+	jar.SetCookies(serverURL, cbResp.Cookies())
+	require.NotEmpty(t, jar.Cookies(serverURL), "the callback must set the session cookie")
+
+	u, err := h.users.GetUserByEmail(email)
+	require.NoError(t, err)
+	require.NotNil(t, u, "the login created the record")
+	assert.Equal(t, "oidc", u.Provider)
+	assert.NotEmpty(t, u.ProviderSubjectID)
+	assert.Equal(t, groups, u.Groups, "the stored groups are the verified token's")
+	return jar
+}
+
+// forwardingProxyOptions shape one hop of an ingress in front of the proxy.
+type forwardingProxyOptions struct {
+	// Host rewrites the Host header the upstream sees ("" = keep the client's).
+	Host string
+	// Set adds or replaces X-Forwarded-* (and any other) headers.
+	Set map[string]string
+	// Strip removes headers the client sent (an ingress that sanitises).
+	Strip []string
+	// SourceIP is the local address the proxy dials the upstream from, so
+	// the upstream's RemoteAddr is a chosen peer ("" = the default). On
+	// macOS only 127.0.0.1 is bound by default; Linux binds all of 127/8.
+	SourceIP string
+}
+
+// newForwardingProxy starts an httptest reverse proxy in front of upstream
+// that applies opts to every request: an ingress that sets or strips the
+// forwarded headers, rewrites Host and dials from a chosen source address.
+func newForwardingProxy(t *testing.T, upstream *httptest.Server, opts forwardingProxyOptions) *httptest.Server {
+	t.Helper()
+
+	dialer := &net.Dialer{Timeout: 5 * time.Second}
+	if opts.SourceIP != "" {
+		dialer.LocalAddr = &net.TCPAddr{IP: net.ParseIP(opts.SourceIP)}
+	}
+	client := &http.Client{
+		Timeout: 5 * time.Second,
+		Transport: &http.Transport{
+			DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
+				return dialer.DialContext(ctx, network, addr)
+			},
+			DisableKeepAlives: true,
+		},
+		CheckRedirect: func(*http.Request, []*http.Request) error {
+			return http.ErrUseLastResponse
+		},
+	}
+
+	proxy := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		out, err := http.NewRequestWithContext(r.Context(), r.Method, upstream.URL+r.URL.RequestURI(), r.Body)
+		if err != nil {
+			http.Error(w, err.Error(), http.StatusBadGateway)
+			return
+		}
+		for k, vs := range r.Header {
+			for _, v := range vs {
+				out.Header.Add(k, v)
+			}
+		}
+		for _, k := range opts.Strip {
+			out.Header.Del(k)
+		}
+		for k, v := range opts.Set {
+			out.Header.Set(k, v)
+		}
+		out.Host = r.Host
+		if opts.Host != "" {
+			out.Host = opts.Host
+		}
+		resp, err := client.Do(out)
+		if err != nil {
+			http.Error(w, err.Error(), http.StatusBadGateway)
+			return
+		}
+		defer resp.Body.Close()
+		for k, vs := range resp.Header {
+			for _, v := range vs {
+				w.Header().Add(k, v)
+			}
+		}
+		w.WriteHeader(resp.StatusCode)
+		_, _ = io.Copy(w, resp.Body)
+	}))
+	t.Cleanup(proxy.Close)
+	return proxy
+}
+
+// The harness itself, end to end through the production wiring: a real
+// `oidc` login lands a session whose /auth/me carries the verified groups
+// (FR-008, contracts/rest-endpoints.md §2), and the record is bound to the
+// fake's subject.
+func TestOIDCWiringHarness_LoginAsLandsSessionWithGroups(t *testing.T) {
+	h := newOIDCWiringHarness(t, map[string][]string{
+		"alice@example.com": {"eng", "sre"},
+		"bob@example.com":   {},
+	})
+
+	jar := h.loginAs(t, "alice@example.com", []string{"eng", "sre"})
+
+	client := &http.Client{Jar: jar, Timeout: 5 * time.Second}
+	resp, err := client.Get(h.server.URL + "/api/v1/auth/me")
+	require.NoError(t, err)
+	defer resp.Body.Close()
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+
+	var me struct {
+		Email           string   `json:"email"`
+		Role            string   `json:"role"`
+		Provider        string   `json:"provider"`
+		Groups          []string `json:"groups"`
+		GroupsUpdatedAt *string  `json:"groups_updated_at"`
+	}
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&me))
+	assert.Equal(t, "alice@example.com", me.Email)
+	assert.Equal(t, "user", me.Role)
+	assert.Equal(t, "oidc", me.Provider)
+	assert.Equal(t, []string{"eng", "sre"}, me.Groups)
+	require.NotNil(t, me.GroupsUpdatedAt)
+	_, err = time.Parse(time.RFC3339, *me.GroupsUpdatedAt)
+	assert.NoError(t, err)
+
+	// A user without groups stores [] (never null on the wire).
+	bobJar := h.loginAs(t, "bob@example.com", []string{})
+	bobResp, err := (&http.Client{Jar: bobJar, Timeout: 5 * time.Second}).Get(h.server.URL + "/api/v1/auth/me")
+	require.NoError(t, err)
+	defer bobResp.Body.Close()
+	var bob map[string]json.RawMessage
+	require.NoError(t, json.NewDecoder(bobResp.Body).Decode(&bob))
+	assert.Equal(t, "[]", string(bob["groups"]))
+}
+
+// The reverse-proxy helper: headers it sets reach the upstream, headers it
+// strips do not, and Host is rewritten.
+func TestForwardingProxy_SetsStripsAndRewritesHost(t *testing.T) {
+	var seen struct {
+		host  string
+		proto string
+		xff   string
+		xreal string
+	}
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		seen.host = r.Host
+		seen.proto = r.Header.Get("X-Forwarded-Proto")
+		seen.xff = r.Header.Get("X-Forwarded-For")
+		seen.xreal = r.Header.Get("X-Real-IP")
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	t.Cleanup(upstream.Close)
+
+	proxy := newForwardingProxy(t, upstream, forwardingProxyOptions{
+		Host:  "proxy.example.com",
+		Set:   map[string]string{"X-Forwarded-Proto": "https", "X-Forwarded-For": "203.0.113.9"},
+		Strip: []string{"X-Real-IP"},
+	})
+
+	req, err := http.NewRequest(http.MethodGet, proxy.URL+"/anything", nil)
+	require.NoError(t, err)
+	req.Header.Set("X-Real-IP", "198.51.100.1") // an attacker-supplied header the ingress strips
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	_ = resp.Body.Close()
+	require.Equal(t, http.StatusNoContent, resp.StatusCode)
+
+	assert.Equal(t, "proxy.example.com", seen.host)
+	assert.Equal(t, "https", seen.proto)
+	assert.Equal(t, "203.0.113.9", seen.xff)
+	assert.Empty(t, seen.xreal, "a stripped header never reaches the upstream")
+}
diff --git a/internal/serveredition/setup.go b/internal/serveredition/setup.go
index 55a0ac766..46cdb15e3 100644
--- a/internal/serveredition/setup.go
+++ b/internal/serveredition/setup.go
@@ -4,6 +4,7 @@ package serveredition
 
 import (
 	"fmt"
+	"strings"
 	"time"
 
 	"github.com/go-chi/chi/v5"
@@ -23,6 +24,23 @@ func init() {
 	})
 }
 
+// credentialMasterKey resolves the credential-store master key from the
+// already-defaulted ServerEditionConfig. It deliberately does NOT call
+// broker.ResolveMasterKey: cfg.CredentialEncryptionKey already went through
+// config.ServerEditionConfig.ApplyDefaults(), which gives the explicit
+// config value precedence and falls back to MCPPROXY_CRED_KEY only when the
+// config value is empty — matching docs/configuration/config-file.md's
+// "An explicit value wins over the environment" for this key.
+// broker.ResolveMasterKey has the OPPOSITE precedence (env wins) by its own
+// separate, deliberate design for its own callers; calling it again here on
+// top of the already-resolved value would silently discard an explicit
+// server_edition.credential_encryption_key whenever MCPPROXY_CRED_KEY is
+// also set, contradicting the documented precedence for this key
+// (cross-review round 5, chunk 3 P2).
+func credentialMasterKey(cfg *config.ServerEditionConfig) string {
+	return cfg.CredentialEncryptionKey
+}
+
 func setupMultiUserOAuth(deps Dependencies) error {
 	if deps.Config == nil || deps.Config.ServerEdition == nil || !deps.Config.ServerEdition.Enabled {
 		deps.Logger.Debug("Server multi-user OAuth: not enabled, skipping setup")
@@ -133,25 +151,47 @@ func setupMultiUserOAuth(deps Dependencies) error {
 		return fmt.Errorf("getting HMAC key: %w", err)
 	}
 
+	// The LIVE trusted_proxies list (Spec 107 FR-027, edition-neutral, hot-
+	// reloadable): every forwarded-header reader below evaluates this per
+	// request and never captures the boot slice.
+	trustedProxies := config.TrustedProxiesProvider(func() []string {
+		if deps.ConfigProvider != nil {
+			if live := deps.ConfigProvider(); live != nil {
+				return live.TrustedProxies
+			}
+		}
+		return deps.Config.TrustedProxies
+	})
+
+	// Front door (Spec 107 FR-025/FR-026): public_url is restart-pinned and
+	// resolved here; the Secure policy of the session cookie is auto|true|false
+	// over the public_url scheme, in-process TLS and a trusted X-Forwarded-Proto.
+	publicURL := strings.TrimSuffix(cfg.PublicURL, "/")
+	tlsEnabled := deps.Config.TLS != nil && deps.Config.TLS.Enabled
+	securePolicy := teamsauth.CookieSecurePolicy{
+		Mode:           cfg.EffectiveSessionCookieSecure(),
+		PublicURLHTTPS: cfg.PublicURLIsHTTPS() || tlsEnabled,
+		TrustedProxies: trustedProxies,
+	}
+	if publicURL != "" {
+		deps.Logger.Infow("Server edition front door: public_url resolved",
+			"public_url", publicURL,
+			"callback_url", publicURL+"/api/v1/auth/callback",
+			"session_cookie_secure", securePolicy.Mode)
+	} else if !config.ListenIsLoopback(deps.Config.Listen) {
+		deps.Logger.Warnw("server_edition.public_url is unset while listening on a non-loopback address; set it (or MCPPROXY_PUBLIC_URL) so the OAuth callback URL and the Secure cookie decision do not depend on Host or X-Forwarded-* headers",
+			"listen", deps.Config.Listen)
+	}
+	if securePolicy.Mode == config.SessionCookieSecureFalse {
+		deps.Logger.Warnw("server_edition.session_cookie_secure is explicitly false: the session cookie is sent without the Secure attribute; only a plain-http loopback or test deployment should run this way")
+	}
+
 	// Create session manager
 	sessionTTL := cfg.SessionTTL.Duration()
 	if sessionTTL == 0 {
 		sessionTTL = 24 * time.Hour
 	}
-	sessionManager := teamsauth.NewSessionManager(userStore, sessionTTL, false) // secure=false for localhost
-
-	// Create OAuth handler
-	oauthHandler := teamsauth.NewOAuthHandler(userStore, sessionManager, cfg, hmacKey, deps.Logger)
-
-	// The per-user credential store backs the oauth_connect flow (spec 074
-	// Path B): credentials a user connects are stored here, encrypted under
-	// MCPPROXY_CRED_KEY or server_edition.credential_encryption_key. With no key
-	// it is constructed disabled and the connect surface reports so. Nothing
-	// injects a stored credential into a proxied request (Spec 107 FR-034).
-	credStore, err := broker.NewBBoltAESStore(deps.DB, broker.ResolveMasterKey(cfg.CredentialEncryptionKey), deps.Logger.Desugar())
-	if err != nil {
-		return fmt.Errorf("creating credential store: %w", err)
-	}
+	sessionManager := teamsauth.NewSessionManagerWithPolicy(userStore, sessionTTL, securePolicy)
 
 	// The LIVE view of the server-edition block, read through the same provider
 	// the admin-servers check uses rather than a second mechanism.
@@ -177,6 +217,22 @@ func setupMultiUserOAuth(deps Dependencies) error {
 		return cfg
 	})
 
+	// Create OAuth handler. It resolves the identity provider once from the
+	// boot block (discovery stays lazy) and derives each login's role from the
+	// LIVE admin_emails through the same provider (Spec 107 T044).
+	oauthHandler := teamsauth.NewOAuthHandler(userStore, sessionManager, serverEditionConfig, hmacKey, deps.Logger)
+	oauthHandler.SetTrustedProxiesProvider(trustedProxies)
+
+	// The per-user credential store backs the oauth_connect flow (spec 074
+	// Path B): credentials a user connects are stored here, encrypted under
+	// MCPPROXY_CRED_KEY or server_edition.credential_encryption_key. With no key
+	// it is constructed disabled and the connect surface reports so. Nothing
+	// injects a stored credential into a proxied request (Spec 107 FR-034).
+	credStore, err := broker.NewBBoltAESStore(deps.DB, credentialMasterKey(cfg), deps.Logger.Desugar())
+	if err != nil {
+		return fmt.Errorf("creating credential store: %w", err)
+	}
+
 	// Create auth middleware
 	authMiddleware := teamsauth.NewServerEditionAuthMiddleware(sessionManager, userStore, serverEditionConfig, hmacKey, deps.Logger)
 
@@ -185,6 +241,10 @@ func setupMultiUserOAuth(deps Dependencies) error {
 	// These are mounted outside the API key auth group.
 	deps.Router.Get("/api/v1/auth/login", oauthHandler.HandleLogin)
 	deps.Router.Get("/api/v1/auth/callback", oauthHandler.HandleCallback)
+	// The public edition probe (Spec 107 FR-030, T053) is mounted beside
+	// login/callback, outside every auth group, only on this enabled block.
+	authEndpoints := teamsapi.NewAuthEndpoints(userStore, sessionManager, cfg, hmacKey, deps.Logger)
+	authEndpoints.RegisterPublicRoutesWithPrefix(deps.Router, "/api/v1")
 
 	// Shared servers are the main config servers (admin-configured).
 	sharedServers := deps.Config.Servers
@@ -210,7 +270,6 @@ func setupMultiUserOAuth(deps Dependencies) error {
 
 	// All server edition endpoints that require session cookie or JWT authentication.
 	// Mounted outside the API key group so session cookies work.
-	authEndpoints := teamsapi.NewAuthEndpoints(userStore, sessionManager, cfg, hmacKey, deps.Logger)
 	configPath := config.GetConfigPath(deps.Config.DataDir)
 	adminHandlers := teamsapi.NewAdminHandlers(userStore, nil, sessionManager, cfg.AdminEmails, sharedServers, deps.Config, configPath, deps.ManagementService, deps.Logger)
 	adminHandlers.SetSharingUpdater(deps.SetServerShared)
@@ -231,6 +290,7 @@ func setupMultiUserOAuth(deps Dependencies) error {
 	brokerAudit := teamsapi.NewActivityAuditSink(deps.StorageManager, deps.Logger)
 	credentialHandlers := teamsapi.NewCredentialHandlers(credStore, sharedServers, brokerAudit, deps.Logger)
 	credentialHandlers.SetAdminServersProvider(adminServers)
+	credentialHandlers.SetFrontDoor(publicURL, trustedProxies)
 
 	deps.Router.Group(func(r chi.Router) {
 		r.Use(authMiddleware.Middleware())
diff --git a/internal/serveredition/setup_test.go b/internal/serveredition/setup_test.go
index e33a579d9..dfb1e7954 100644
--- a/internal/serveredition/setup_test.go
+++ b/internal/serveredition/setup_test.go
@@ -16,6 +16,37 @@ import (
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
 )
 
+func TestCredentialMasterKey_ExplicitConfigWinsOverEnv(t *testing.T) {
+	// docs/configuration/config-file.md documents server_edition.
+	// credential_encryption_key as "An explicit value wins over the
+	// environment" — the same precedence config.ServerEditionConfig.
+	// ApplyDefaults() already gives it (falls back to MCPPROXY_CRED_KEY
+	// only when the config value is empty). broker.ResolveMasterKey has
+	// the OPPOSITE precedence by its own separate, deliberate design
+	// (env wins, TestResolveMasterKey); calling it again on the
+	// already-defaulted config value at the credential-store call site
+	// would silently discard an explicit config value whenever
+	// MCPPROXY_CRED_KEY is also set (cross-review round 5, chunk 3 P2).
+	t.Setenv("MCPPROXY_CRED_KEY", "from-env")
+	got := credentialMasterKey(&config.ServerEditionConfig{CredentialEncryptionKey: "from-config"})
+	if got != "from-config" {
+		t.Errorf("explicit config value must win over MCPPROXY_CRED_KEY, got %q", got)
+	}
+}
+
+func TestCredentialMasterKey_FallsBackToApplyDefaultsEnvCopy(t *testing.T) {
+	// When the config value is empty, ApplyDefaults() already copied the
+	// env var into it — credentialMasterKey must not re-derive from the
+	// environment a second time, just pass through what ApplyDefaults set.
+	cfg := &config.ServerEditionConfig{}
+	t.Setenv("MCPPROXY_CRED_KEY", "from-env")
+	cfg.ApplyDefaults()
+	got := credentialMasterKey(cfg)
+	if got != "from-env" {
+		t.Errorf("expected the ApplyDefaults-resolved env fallback %q, got %q", "from-env", got)
+	}
+}
+
 func TestSetupMultiUserOAuth_Disabled(t *testing.T) {
 	// When server edition is not enabled, setup should be a no-op
 	logger := zap.NewNop().Sugar()
@@ -147,13 +178,15 @@ func TestSetupMultiUserOAuth_RegistersRoutes(t *testing.T) {
 		t.Errorf("expected login to redirect (302), got %d", loginRec.Code)
 	}
 
-	// Callback without params should return 400
+	// Callback without params is state_invalid: the one generic 403 page
+	// (Spec 107 FR-024; a distinct 400 would disclose which parameter was
+	// missing).
 	callbackReq := httptest.NewRequest(http.MethodGet, "/api/v1/auth/callback", nil)
 	callbackReq.Host = "localhost:8080"
 	callbackRec := httptest.NewRecorder()
 	router.ServeHTTP(callbackRec, callbackReq)
-	if callbackRec.Code != http.StatusBadRequest {
-		t.Errorf("expected callback without params to return 400, got %d", callbackRec.Code)
+	if callbackRec.Code != http.StatusForbidden {
+		t.Errorf("expected callback without params to return 403, got %d", callbackRec.Code)
 	}
 
 	// Logout without auth should return 401
diff --git a/internal/serveredition/setup_wiring_test.go b/internal/serveredition/setup_wiring_test.go
index 1ee195359..23536ab21 100644
--- a/internal/serveredition/setup_wiring_test.go
+++ b/internal/serveredition/setup_wiring_test.go
@@ -56,6 +56,18 @@ func (h *wiringHarness) currentConfig() *config.Config {
 
 func newWiringHarness(t *testing.T) *wiringHarness {
 	t.Helper()
+	return newWiringHarnessWith(t, &config.ServerEditionOAuthConfig{
+		Provider:     "google",
+		ClientID:     "test-client-id",
+		ClientSecret: "test-client-secret",
+	})
+}
+
+// newWiringHarnessWith drives the production setup with the given OAuth
+// block. newOIDCWiringHarness (harness_oidc_test.go) points it at an
+// in-process tests/oauthserver OpenID Provider so a test can log in for real.
+func newWiringHarnessWith(t *testing.T, oauthCfg *config.ServerEditionOAuthConfig) *wiringHarness {
+	t.Helper()
 
 	tmpDir := t.TempDir()
 	db, err := bbolt.Open(tmpDir+"/test.db", 0600, &bbolt.Options{Timeout: time.Second})
@@ -76,11 +88,7 @@ func newWiringHarness(t *testing.T) *wiringHarness {
 				AdminEmails:    []string{"admin@example.com"},
 				SessionTTL:     config.Duration(24 * time.Hour),
 				BearerTokenTTL: config.Duration(24 * time.Hour),
-				OAuth: &config.ServerEditionOAuthConfig{
-					Provider:     "google",
-					ClientID:     "test-client-id",
-					ClientSecret: "test-client-secret",
-				},
+				OAuth:          oauthCfg,
 			},
 		},
 	}
diff --git a/internal/serveredition/users/models.go b/internal/serveredition/users/models.go
index f7140a159..c396c50a3 100644
--- a/internal/serveredition/users/models.go
+++ b/internal/serveredition/users/models.go
@@ -16,11 +16,24 @@ type User struct {
 	ID                string    `json:"id"`                  // ULID
 	Email             string    `json:"email"`               // From OAuth provider
 	DisplayName       string    `json:"display_name"`        // From OAuth provider
-	Provider          string    `json:"provider"`            // google, github, microsoft
+	Provider          string    `json:"provider"`            // google, github, microsoft, oidc
 	ProviderSubjectID string    `json:"provider_subject_id"` // Provider's unique subject ID
 	CreatedAt         time.Time `json:"created_at"`
 	LastLoginAt       time.Time `json:"last_login_at"`
 	Disabled          bool      `json:"disabled"`
+
+	// Groups holds the groups claim of the last successful `oidc` login,
+	// replaced wholesale on every login (Spec 107 FR-008). Legacy providers
+	// store []. An upgraded record decodes as nil until its next login.
+	Groups []string `json:"groups"`
+	// GroupsUpdatedAt is stamped by the login write that set Groups; zero on
+	// an upgraded record that has not logged in since.
+	GroupsUpdatedAt time.Time `json:"groups_updated_at,omitzero"`
+	// SubjectRebindArmedAt is the administrator-opened rebind window (FR-023):
+	// set by a real disabled→enabled transition, cleared by disable and by the
+	// first successful login while set (which then accepts a new subject).
+	// Nil = closed; absent on every upgraded record.
+	SubjectRebindArmedAt *time.Time `json:"subject_rebind_armed_at,omitempty"`
 }
 
 // NewUser creates a new User with a generated ULID.
@@ -45,7 +58,7 @@ func (u *User) Validate() error {
 	if u.Email == "" {
 		return fmt.Errorf("user email is required")
 	}
-	validProviders := map[string]bool{"google": true, "github": true, "microsoft": true}
+	validProviders := map[string]bool{"google": true, "github": true, "microsoft": true, "oidc": true}
 	if !validProviders[u.Provider] {
 		return fmt.Errorf("invalid provider: %s", u.Provider)
 	}
@@ -64,6 +77,9 @@ type Session struct {
 	ExpiresAt   time.Time `json:"expires_at"`
 	UserAgent   string    `json:"user_agent,omitempty"`
 	IPAddress   string    `json:"ip_address,omitempty"`
+	// CookieSecure records whether the session cookie was set with the Secure
+	// attribute (Spec 107 FR-026) so logout clears it with the same attribute.
+	CookieSecure bool `json:"cookie_secure,omitempty"`
 }
 
 // NewSession creates a new Session with a generated UUID.
@@ -106,3 +122,33 @@ func (s *Session) Validate() error {
 func (s *Session) isLoginSession() bool {
 	return s.UserID != "" && !s.ExpiresAt.IsZero()
 }
+
+// LoginClaims carries the VERIFIED identity of one successful login attempt
+// into UpdateUserLogin (Spec 107 FR-008/FR-023): only values that passed the
+// provider's checks may be placed here. Groups is the captured groups claim
+// (nil or empty → stored as []); GroupsKnown reports whether the login
+// captured groups at all — false leaves the stored list untouched.
+type LoginClaims struct {
+	Email       string
+	Provider    string
+	Subject     string
+	Name        string
+	AvatarURL   string
+	Groups      []string
+	GroupsKnown bool
+}
+
+// LoginOutcome is what UpdateUserLogin decided inside its transaction.
+type LoginOutcome struct {
+	// User is the record as written (never nil on a nil error).
+	User *User
+	// Created reports a first login: the record did not exist.
+	Created bool
+	// Rebound reports that (provider, subject) changed on an existing record —
+	// a configured-provider change, or a different subject inside an armed
+	// rebind window. The auth_event line carries `provider_rebound`.
+	Rebound bool
+	// RebindConsumed reports that SubjectRebindArmedAt was set and has been
+	// cleared by this write.
+	RebindConsumed bool
+}
diff --git a/internal/serveredition/users/models_test.go b/internal/serveredition/users/models_test.go
index 4fd80a21b..e77c83834 100644
--- a/internal/serveredition/users/models_test.go
+++ b/internal/serveredition/users/models_test.go
@@ -179,3 +179,19 @@ func TestSession_JSON_RoundTrip(t *testing.T) {
 	assert.Equal(t, original.UserAgent, restored.UserAgent)
 	assert.Equal(t, original.IPAddress, restored.IPAddress)
 }
+
+// Spec 107 FR-020/FR-022 (T040, behaviour-red until T041): the generic `oidc`
+// provider is a valid User.Provider, and `sub` stays mandatory for it — it is
+// the ProviderSubjectID that FR-023 binds the record to.
+func TestUser_Validate_OIDCProviderAdmitted(t *testing.T) {
+	u := NewUser("test@example.com", "Test User", "oidc", "sub-oidc-1")
+	assert.NoError(t, u.Validate(), "provider oidc must be admitted")
+}
+
+func TestUser_Validate_OIDCRequiresSubject(t *testing.T) {
+	u := NewUser("test@example.com", "Test User", "oidc", "")
+	err := u.Validate()
+	require.Error(t, err, "oidc without a subject must be refused")
+	assert.Contains(t, err.Error(), "provider subject ID",
+		"the refusal must be the subject rule, not the provider enum")
+}
diff --git a/internal/serveredition/users/store.go b/internal/serveredition/users/store.go
index a18a3f5dc..baa20f4a9 100644
--- a/internal/serveredition/users/store.go
+++ b/internal/serveredition/users/store.go
@@ -3,7 +3,9 @@
 package users
 
 import (
+	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"strings"
 	"time"
@@ -468,3 +470,213 @@ func (s *UserStore) CleanupExpiredSessions() (int, error) {
 
 	return count, err
 }
+
+// Sentinel errors of UpdateUserLogin. The caller maps them to the FR-013
+// closed reasons (subject_mismatch, user_disabled).
+var (
+	// ErrSubjectMismatch: same provider, same email, a different subject and
+	// no administrator-armed rebind window (Spec 107 FR-023).
+	ErrSubjectMismatch = errors.New("provider subject does not match the stored binding")
+	// ErrUserDisabled: the record is disabled; nothing is written.
+	ErrUserDisabled = errors.New("user is disabled")
+)
+
+// UpdateUserLogin applies one successful login to the user record keyed by
+// the claims' normalised email, atomically (Spec 107 FR-008/FR-023).
+//
+// It is transaction-owned: the record is re-read by the email index INSIDE
+// one db.Update, the subject rule is evaluated there, and groups, subject,
+// provider, display name and last-login are written in that same
+// transaction. Two concurrent logins therefore serialise on the store: when
+// the rebind window is armed and both present different subjects, exactly
+// one rebinds (and clears the window) and the other sees the consumed window
+// and is refused with ErrSubjectMismatch. A pre-mutated *User handed to
+// UpdateUser could not provide this — both callers would observe the armed
+// flag.
+//
+// Subject rule on an existing record:
+//   - Disabled → ErrUserDisabled, nothing written.
+//   - stored subject empty, or same (provider, subject) → bind.
+//   - stored provider differs from the presented one → rebind (Rebound).
+//   - same provider, different subject: rebind only while
+//     SubjectRebindArmedAt is set (Rebound + RebindConsumed, the flag is
+//     cleared in the same write); otherwise ErrSubjectMismatch, nothing
+//     written.
+//
+// A successful login while the window is armed always closes it (Rebound +
+// RebindConsumed both set), even when the subject did not change: FR-023
+// carries provider_rebound on "the first successful login" while armed
+// unconditionally, and RebindConsumed alone is never logged anywhere, so a
+// same-subject consumption would otherwise leave no audit trace. A missing
+// record is created bound to the presented (provider, subject) (Created).
+func (s *UserStore) UpdateUserLogin(ctx context.Context, claims LoginClaims) (LoginOutcome, error) {
+	if err := ctx.Err(); err != nil {
+		return LoginOutcome{}, err
+	}
+	email := strings.ToLower(strings.TrimSpace(claims.Email))
+	if email == "" {
+		return LoginOutcome{}, fmt.Errorf("login claims: email is required")
+	}
+	if claims.Subject == "" {
+		return LoginOutcome{}, fmt.Errorf("login claims: subject is required")
+	}
+	now := time.Now().UTC()
+
+	var out LoginOutcome
+	err := s.db.Update(func(tx *bbolt.Tx) error {
+		usersBucket := tx.Bucket([]byte(BucketUsers))
+		if usersBucket == nil {
+			return fmt.Errorf("bucket %s not found", BucketUsers)
+		}
+		emailBucket := tx.Bucket([]byte(BucketUsersByEmail))
+		if emailBucket == nil {
+			return fmt.Errorf("bucket %s not found", BucketUsersByEmail)
+		}
+
+		var user *User
+		if id := emailBucket.Get([]byte(email)); id != nil {
+			if data := usersBucket.Get(id); data != nil {
+				user = &User{}
+				if err := json.Unmarshal(data, user); err != nil {
+					return fmt.Errorf("failed to unmarshal user: %w", err)
+				}
+			}
+		}
+
+		if user == nil {
+			user = NewUser(email, claims.Name, claims.Provider, claims.Subject)
+			user.CreatedAt = now
+			out.Created = true
+		} else {
+			if user.Disabled {
+				return ErrUserDisabled
+			}
+			armed := user.SubjectRebindArmedAt != nil
+			switch {
+			case user.ProviderSubjectID == "":
+				// An upgraded record bound before the IdP exposed a subject: bind.
+			case user.Provider == claims.Provider && user.ProviderSubjectID == claims.Subject:
+				// Plain bind — no identity change, but see below: consuming an
+				// armed window is itself the reportable event (FR-023).
+			case user.Provider != claims.Provider:
+				out.Rebound = true
+			case armed:
+				out.Rebound = true
+			default:
+				return ErrSubjectMismatch
+			}
+			if armed {
+				// FR-023: "the first successful login" while armed "carries
+				// provider_rebound in the line's flags" — unconditionally, not
+				// only when the presented (provider, sub) actually differs from
+				// the stored one. RebindConsumed alone reaches no audit line, so
+				// a same-subject login while armed would otherwise close the
+				// administrator-opened window with no trace at all.
+				user.SubjectRebindArmedAt = nil
+				out.RebindConsumed = true
+				out.Rebound = true
+			}
+			user.Provider = claims.Provider
+			user.ProviderSubjectID = claims.Subject
+			if claims.Name != "" {
+				user.DisplayName = claims.Name
+			}
+		}
+		user.LastLoginAt = now
+		if claims.GroupsKnown {
+			groups := claims.Groups
+			if groups == nil {
+				groups = []string{}
+			}
+			user.Groups = groups
+			user.GroupsUpdatedAt = now
+		}
+
+		if err := user.Validate(); err != nil {
+			return fmt.Errorf("invalid user: %w", err)
+		}
+		data, err := json.Marshal(user)
+		if err != nil {
+			return fmt.Errorf("failed to marshal user: %w", err)
+		}
+		if err := usersBucket.Put([]byte(user.ID), data); err != nil {
+			return fmt.Errorf("failed to store user: %w", err)
+		}
+		if out.Created {
+			if err := emailBucket.Put([]byte(email), []byte(user.ID)); err != nil {
+				return fmt.Errorf("failed to store email index: %w", err)
+			}
+		}
+		out.User = user
+		return nil
+	})
+	if err != nil {
+		return LoginOutcome{}, err
+	}
+	return out, nil
+}
+
+// SetUserDisabled atomically toggles the Disabled flag (and, for an enable,
+// the FR-023 rebind window) inside ONE db.Update transaction: the record is
+// re-read by id INSIDE the transaction, not handed in pre-mutated.
+//
+// A blind GetUser (View) + mutate + UpdateUser (Put), which is what the admin
+// handlers used before, has a lost-update window: a concurrent successful
+// login can run its own UpdateUserLogin transaction — writing Groups,
+// GroupsUpdatedAt, Provider, ProviderSubjectID, LastLoginAt and clearing
+// SubjectRebindArmedAt — entirely between the admin's read and its write, and
+// the admin's blind Put then overwrites the record back to the stale
+// snapshot, reopening a just-consumed rebind window or discarding a
+// concurrent subject rebind (cross-review round 1, chunk 2 P1).
+//
+// Returns (nil, false, nil) when the user does not exist (GetUser's own
+// not-found convention), and armed reports whether a real disabled→enabled
+// transition opened the FR-023 rebind window (mirrors the enableUser
+// semantics: enabling an already-enabled record is not a transition).
+func (s *UserStore) SetUserDisabled(id string, disabled bool) (user *User, armed bool, err error) {
+	now := time.Now().UTC()
+	txErr := s.db.Update(func(tx *bbolt.Tx) error {
+		usersBucket := tx.Bucket([]byte(BucketUsers))
+		if usersBucket == nil {
+			return fmt.Errorf("bucket %s not found", BucketUsers)
+		}
+		data := usersBucket.Get([]byte(id))
+		if data == nil {
+			return nil // not found; user stays nil
+		}
+		u := &User{}
+		if err := json.Unmarshal(data, u); err != nil {
+			return fmt.Errorf("failed to unmarshal user: %w", err)
+		}
+
+		if disabled {
+			u.Disabled = true
+			// Disabling closes any open rebind window (FR-023); the binding
+			// itself (ProviderSubjectID) is kept.
+			u.SubjectRebindArmedAt = nil
+		} else {
+			if u.Disabled {
+				u.SubjectRebindArmedAt = &now
+				armed = true
+			}
+			u.Disabled = false
+		}
+
+		if err := u.Validate(); err != nil {
+			return fmt.Errorf("invalid user: %w", err)
+		}
+		out, err := json.Marshal(u)
+		if err != nil {
+			return fmt.Errorf("failed to marshal user: %w", err)
+		}
+		if err := usersBucket.Put([]byte(id), out); err != nil {
+			return fmt.Errorf("failed to store user: %w", err)
+		}
+		user = u
+		return nil
+	})
+	if txErr != nil {
+		return nil, false, txErr
+	}
+	return user, armed, nil
+}
diff --git a/internal/serveredition/users/store_test.go b/internal/serveredition/users/store_test.go
index 487dd42ef..b950ec23a 100644
--- a/internal/serveredition/users/store_test.go
+++ b/internal/serveredition/users/store_test.go
@@ -3,7 +3,10 @@
 package users
 
 import (
+	"context"
+	"fmt"
 	"path/filepath"
+	"sync"
 	"testing"
 	"time"
 
@@ -177,6 +180,110 @@ func TestUserStore_ListUsers_Empty(t *testing.T) {
 	assert.Empty(t, users)
 }
 
+// --- SetUserDisabled --------------------------------------------------------
+
+func TestSetUserDisabled_TogglesFlag(t *testing.T) {
+	store := setupTestStore(t)
+	user := NewUser("erin@example.com", "Erin", "google", "g-sub-erin")
+	require.NoError(t, store.CreateUser(user))
+
+	got, armed, err := store.SetUserDisabled(user.ID, true)
+	require.NoError(t, err)
+	require.NotNil(t, got)
+	assert.True(t, got.Disabled)
+	assert.False(t, armed, "disabling never arms the rebind window")
+
+	got, armed, err = store.SetUserDisabled(user.ID, false)
+	require.NoError(t, err)
+	require.NotNil(t, got)
+	assert.False(t, got.Disabled)
+	assert.True(t, armed, "a real disabled→enabled transition arms the rebind window")
+	require.NotNil(t, got.SubjectRebindArmedAt)
+
+	// A no-op enable (already enabled) is not a transition: it neither
+	// re-arms nor closes an already-open window.
+	armedAt := *got.SubjectRebindArmedAt
+	got, armed, err = store.SetUserDisabled(user.ID, false)
+	require.NoError(t, err)
+	assert.False(t, armed)
+	require.NotNil(t, got.SubjectRebindArmedAt)
+	assert.True(t, got.SubjectRebindArmedAt.Equal(armedAt))
+}
+
+func TestSetUserDisabled_NotFound(t *testing.T) {
+	store := setupTestStore(t)
+	got, armed, err := store.SetUserDisabled("ghost-id", true)
+	require.NoError(t, err)
+	assert.Nil(t, got)
+	assert.False(t, armed)
+}
+
+// TestSetUserDisabled_DoesNotLoseConcurrentLoginWrite is the regression test
+// for cross-review round 1, chunk 2 P1: SetUserDisabled used to be a blind
+// GetUser (View) + mutate + UpdateUser (Put) in the admin handlers, so a
+// concurrent UpdateUserLogin — writing Groups/Provider/ProviderSubjectID in
+// its own atomic transaction entirely between the admin's read and its write
+// — could be silently reverted by the admin's stale-snapshot overwrite.
+// SetUserDisabled now re-reads the record INSIDE its own db.Update, exactly
+// like UpdateUserLogin, so bbolt's single-writer serialization guarantees
+// neither transaction's write is ever lost, whichever commits second.
+func TestSetUserDisabled_DoesNotLoseConcurrentLoginWrite(t *testing.T) {
+	const iterations = 20
+
+	store := setupTestStore(t)
+	user := NewUser("frank@example.com", "Frank", "google", "sub-A")
+	user.Groups = []string{"old"}
+	require.NoError(t, store.CreateUser(user))
+
+	// SetUserDisabled(id, false) on an already-enabled user is a no-op write
+	// (Disabled was already false, so it never touches the rebind window
+	// either) — it can never fail and never changes what the login writes.
+	// This reproduces the original bug shape exactly (both disable AND
+	// enable used the same blind GetUser+UpdateUser pattern): a same-subject
+	// login updates Groups in its own transaction while a concurrent no-op
+	// admin write races it. With the old blind-write code, an admin write
+	// that read its stale snapshot before the login committed would put that
+	// snapshot back afterwards, silently reverting the login's Groups.
+	for i := 0; i < iterations; i++ {
+		var (
+			wg       sync.WaitGroup
+			barrier  = make(chan struct{})
+			loginErr error
+			noopErr  error
+		)
+		wg.Add(2)
+		go func() {
+			defer wg.Done()
+			<-barrier
+			_, loginErr = store.UpdateUserLogin(context.Background(), LoginClaims{
+				Email:       "frank@example.com",
+				Provider:    "google",
+				Subject:     "sub-A",
+				Name:        "Frank",
+				Groups:      []string{fmt.Sprintf("new-%d", i)},
+				GroupsKnown: true,
+			})
+		}()
+		go func() {
+			defer wg.Done()
+			<-barrier
+			_, _, noopErr = store.SetUserDisabled(user.ID, false)
+		}()
+		close(barrier)
+		wg.Wait()
+
+		require.NoError(t, loginErr, "round %d", i)
+		require.NoError(t, noopErr, "round %d", i)
+
+		stored, err := store.GetUser(user.ID)
+		require.NoError(t, err)
+		require.NotNil(t, stored)
+		assert.False(t, stored.Disabled, "round %d", i)
+		assert.Equal(t, []string{fmt.Sprintf("new-%d", i)}, stored.Groups,
+			"round %d: the login's groups write must survive, never silently reverted by a concurrent no-op admin write", i)
+	}
+}
+
 func TestUserStore_DeleteUser_RemovesEmailIndex(t *testing.T) {
 	store := setupTestStore(t)
 
diff --git a/internal/telemetry/current_error_codes_test.go b/internal/telemetry/current_error_codes_test.go
index 4dd5b3d0c..86e307d8e 100644
--- a/internal/telemetry/current_error_codes_test.go
+++ b/internal/telemetry/current_error_codes_test.go
@@ -265,7 +265,7 @@ func TestPayloadV11_CurrentErrorCodesReachTheWire(t *testing.T) {
 	js := string(data)
 
 	for _, want := range []string{
-		`"schema_version":12`,
+		`"schema_version":13`,
 		`"MCPX_OAUTH_LOGIN_REQUIRED":2`,
 		`"MCPX_HTTP_DNS_FAILED":1`,
 		`"current_error_codes"`,
diff --git a/internal/telemetry/feature_flags.go b/internal/telemetry/feature_flags.go
index 3db6791d8..36b7c7028 100644
--- a/internal/telemetry/feature_flags.go
+++ b/internal/telemetry/feature_flags.go
@@ -48,6 +48,54 @@ type FeatureFlagSnapshot struct {
 	// tpa_scanner scan volume against the population that actually turned the
 	// deep-scan layer on.
 	DeepScanEnabled bool `json:"deep_scan_enabled"`
+
+	// Schema v13 (Spec 107 US7): ServerEditionEnabled reports whether the
+	// server_edition block is present and enabled. Read through the
+	// build-tagged config.ServerEditionEnabled accessor, so the personal
+	// build — where the block is an opaque, uninterpreted carrier — always
+	// reports false.
+	ServerEditionEnabled bool `json:"server_edition_enabled"`
+
+	// Schema v13 (Spec 107 US7): IdPProvider is the configured identity
+	// provider FAMILY as a closed enum — one of "google" | "github" |
+	// "microsoft" | "oidc" | "none". It is the provider kind only: NEVER the
+	// issuer URL, tenant id, client id or display name. "none" when the block
+	// is disabled, absent, has no oauth section, or (personal build) cannot be
+	// interpreted. Set by BuildFeatureFlagSnapshot (pure, config-only).
+	IdPProvider string `json:"idp_provider"`
+}
+
+// IdP provider families reported in feature_flags.idp_provider (schema v13).
+// The vocabulary is closed: idpProviderEnum clamps anything else to
+// IdPProviderNone so a misconfigured or pre-validation provider string can
+// never widen the enum on the wire.
+const (
+	IdPProviderGoogle    = "google"
+	IdPProviderGitHub    = "github"
+	IdPProviderMicrosoft = "microsoft"
+	IdPProviderOIDC      = "oidc"
+	IdPProviderNone      = "none"
+)
+
+// idpProviderEnum maps the accessor's raw provider family to the closed
+// telemetry enum. enabled=false short-circuits to "none" regardless of what
+// the block says (contract: "none when disabled/unset").
+func idpProviderEnum(enabled bool, family string) string {
+	if !enabled {
+		return IdPProviderNone
+	}
+	switch strings.ToLower(strings.TrimSpace(family)) {
+	case IdPProviderGoogle:
+		return IdPProviderGoogle
+	case IdPProviderGitHub:
+		return IdPProviderGitHub
+	case IdPProviderMicrosoft:
+		return IdPProviderMicrosoft
+	case IdPProviderOIDC:
+		return IdPProviderOIDC
+	default:
+		return IdPProviderNone
+	}
 }
 
 // protocolKeys is the canonical fixed-enum set of protocol labels emitted by
@@ -121,7 +169,7 @@ func normalizeProtocolKey(p string) string {
 // is returned if no upstream servers have OAuth configured.
 func BuildFeatureFlagSnapshot(cfg *config.Config) *FeatureFlagSnapshot {
 	if cfg == nil {
-		return &FeatureFlagSnapshot{OAuthProviderTypes: []string{}}
+		return &FeatureFlagSnapshot{OAuthProviderTypes: []string{}, IdPProvider: IdPProviderNone}
 	}
 
 	snap := &FeatureFlagSnapshot{
@@ -156,6 +204,13 @@ func BuildFeatureFlagSnapshot(cfg *config.Config) *FeatureFlagSnapshot {
 	// security block reports false.
 	snap.DeepScanEnabled = cfg.Security.IsDeepScanEnabled()
 
+	// Schema v13 (Spec 107 US7): server-edition presence and IdP family, read
+	// only through the build-tagged accessors so the personal build never
+	// interprets the block. The family is clamped to the closed enum; the
+	// issuer is never consulted.
+	snap.ServerEditionEnabled = config.ServerEditionEnabled(cfg)
+	snap.IdPProvider = idpProviderEnum(snap.ServerEditionEnabled, config.IdPProviderFamily(cfg))
+
 	// Derive OAuth provider types from upstream server URLs.
 	var providerTypes []string
 	for _, srv := range cfg.Servers {
diff --git a/internal/telemetry/payload_privacy_test.go b/internal/telemetry/payload_privacy_test.go
index 08d895850..861a417a6 100644
--- a/internal/telemetry/payload_privacy_test.go
+++ b/internal/telemetry/payload_privacy_test.go
@@ -144,7 +144,7 @@ func TestPayloadHasNoForbiddenSubstrings(t *testing.T) {
 	// Sanity check: the payload should still contain the legitimate fields,
 	// otherwise we've over-redacted.
 	for _, required := range []string{
-		`"schema_version":12`,
+		`"schema_version":13`,
 		`"surface_requests"`,
 		`"builtin_tool_calls"`,
 		`"upstream_tool_call_count_bucket"`,
diff --git a/internal/telemetry/payload_v13_fixture_personal_test.go b/internal/telemetry/payload_v13_fixture_personal_test.go
new file mode 100644
index 000000000..ab7a29478
--- /dev/null
+++ b/internal/telemetry/payload_v13_fixture_personal_test.go
@@ -0,0 +1,18 @@
+//go:build !server
+
+package telemetry
+
+// newV13Fixture is the personal-edition twin of the v13 fixture (Spec 107
+// US7): the same config bytes are loaded — the server_edition block is an
+// opaque carrier here (FR-040) — but the stub accessors must report
+// server_edition_enabled=false and idp_provider="none", and with no user
+// counter installed user_count_bucket is "0".
+func newV13Fixture() v13Fixture {
+	return v13Fixture{
+		cfg:         v13CanaryConfig(),
+		userCounter: nil,
+		wantEnabled: false,
+		wantIdP:     "none",
+		wantBucket:  "0",
+	}
+}
diff --git a/internal/telemetry/payload_v13_fixture_server_test.go b/internal/telemetry/payload_v13_fixture_server_test.go
new file mode 100644
index 000000000..102b8d306
--- /dev/null
+++ b/internal/telemetry/payload_v13_fixture_server_test.go
@@ -0,0 +1,17 @@
+//go:build server
+
+package telemetry
+
+// newV13Fixture is the server-edition twin of the v13 fixture (Spec 107 US7):
+// the block is enabled with a generic OIDC provider and a user counter that
+// reports three users, so the build-tagged accessors must surface
+// server_edition_enabled=true, idp_provider="oidc" and user_count_bucket="1-10".
+func newV13Fixture() v13Fixture {
+	return v13Fixture{
+		cfg:         v13CanaryConfig(),
+		userCounter: func() (int, error) { return 3, nil },
+		wantEnabled: true,
+		wantIdP:     "oidc",
+		wantBucket:  "1-10",
+	}
+}
diff --git a/internal/telemetry/payload_v13_test.go b/internal/telemetry/payload_v13_test.go
new file mode 100644
index 000000000..4a13edc89
--- /dev/null
+++ b/internal/telemetry/payload_v13_test.go
@@ -0,0 +1,293 @@
+package telemetry
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+)
+
+// Spec 107 (US7, FR-038): schema v13 adds feature_flags.server_edition_enabled,
+// feature_flags.idp_provider and member_count_bucket (the contract's
+// user_count_bucket, renamed off the "user" substring — see
+// TestPayloadV13_PassesScanWithCommonUsernameBlocked). The shared test body below
+// is untagged; the fixture it consumes is defined twice — once under
+// `//go:build server` (payload_v13_fixture_server_test.go) and once under
+// `//go:build !server` (payload_v13_fixture_personal_test.go) — so the
+// build-tagged config accessors are proven under their own tag rather than
+// assumed.
+
+// Canary strings the v13 fixture plants in the server-edition block. None of
+// them may ever reach the wire form (contracts/telemetry-v13.md, Privacy).
+const (
+	v13CanaryIssuerHost = "login.corp.example"
+	v13CanaryIssuerURL  = "https://" + v13CanaryIssuerHost + "/realms/corp"
+	v13CanaryAdminEmail = "alice.admin@corp.example"
+	v13CanaryUserEmail  = "bob.user@corp.example"
+	v13CanaryGroupName  = "grp-platform-admins"
+	v13CanaryGroupClaim = "corp_groups_claim"
+	v13CanaryClientID   = "oidc-client-id-CANARY-4242"
+	v13CanarySecret     = "oidc-client-secret-CANARY-9999"
+	v13CanaryServerName = "MY-V13-CANARY-SERVER"
+	v13CanaryServerURL  = "https://mcp-internal.corp.example/mcp"
+	v13CanaryDisplay    = "Corp SSO CANARY"
+)
+
+// v13Fixture is what each tagged twin hands the shared body: a config whose
+// server-edition block carries every canary, an optional user counter, and the
+// values the edition under test must report.
+type v13Fixture struct {
+	cfg         *config.Config
+	userCounter func() (int, error)
+	wantEnabled bool
+	wantIdP     string
+	wantBucket  string
+}
+
+// v13CanaryConfig is the edition-neutral part of the fixture. The
+// server_edition block is loaded from JSON bytes because the personal build
+// holds it as an opaque canonical-JSON carrier with no fields (FR-040): the
+// identical document is loaded by both editions, so the personal twin proves
+// the carrier leaks nothing while the server twin proves the accessors read it.
+func v13CanaryConfig() *config.Config {
+	enabled := true
+	cfg := &config.Config{
+		EnableSocket:      true,
+		Features:          &config.FeatureFlags{EnableWebUI: true},
+		QuarantineEnabled: &enabled,
+		Telemetry: &config.TelemetryConfig{
+			AnonymousID:          "550e8400-e29b-41d4-a716-446655440000",
+			AnonymousIDCreatedAt: "2026-04-10T12:00:00Z",
+		},
+		Servers: []*config.ServerConfig{
+			{Name: v13CanaryServerName, URL: v13CanaryServerURL, Protocol: "http"},
+		},
+	}
+	block := map[string]any{
+		"enabled":      true,
+		"admin_emails": []string{v13CanaryAdminEmail},
+		"public_url":   "https://" + v13CanaryIssuerHost,
+		"oauth": map[string]any{
+			"provider":      "oidc",
+			"client_id":     v13CanaryClientID,
+			"client_secret": v13CanarySecret,
+			"issuer_url":    v13CanaryIssuerURL,
+			"groups_claim":  v13CanaryGroupClaim,
+			"display_name":  v13CanaryDisplay,
+		},
+	}
+	raw, err := json.Marshal(block)
+	if err != nil {
+		panic("v13 fixture: marshal server_edition block: " + err.Error())
+	}
+	if err := json.Unmarshal(raw, &cfg.ServerEdition); err != nil {
+		panic("v13 fixture: load server_edition block: " + err.Error())
+	}
+	return cfg
+}
+
+// v13Forbidden is every canary plus the enum-free strings the contract names
+// (issuer host, group names, emails, server names). All of them are asserted
+// absent from the rendered payload.
+func v13Forbidden() []string {
+	return []string{
+		v13CanaryIssuerHost, v13CanaryIssuerURL, v13CanaryAdminEmail, v13CanaryUserEmail,
+		v13CanaryGroupName, v13CanaryGroupClaim, v13CanaryClientID, v13CanarySecret,
+		v13CanaryServerName, v13CanaryServerURL, v13CanaryDisplay,
+		"corp.example", "@", "issuer", "client_secret", "admin_emails", "groups",
+	}
+}
+
+func newV13Service(t *testing.T, fx v13Fixture) *Service {
+	t.Helper()
+	t.Setenv("DO_NOT_TRACK", "")
+	t.Setenv("CI", "")
+	t.Setenv("MCPPROXY_TELEMETRY", "")
+	ResetEnvKindForTest()
+	t.Cleanup(ResetEnvKindForTest)
+
+	svc := New(fx.cfg, "", "v1.2.3", "test", zap.NewNop())
+	svc.SetRuntimeStats(&mockRuntimeStats{
+		serverCount: 1, connectedCount: 1, toolCount: 10,
+		routingMode: "retrieve_tools", quarantine: true,
+	})
+	svc.SetUserCounter(fx.userCounter)
+	return svc
+}
+
+// TestPayloadV13_EditionFields proves the three v13 fields for the edition
+// this binary was built as, plus that env_markers.is_container is still on
+// the wire (unchanged, but the container topology is what US7 reads it with).
+func TestPayloadV13_EditionFields(t *testing.T) {
+	fx := newV13Fixture()
+	svc := newV13Service(t, fx)
+	payload := svc.BuildPayload()
+
+	if payload.SchemaVersion != SchemaVersion {
+		t.Fatalf("payload.SchemaVersion = %d, want SchemaVersion (%d)", payload.SchemaVersion, SchemaVersion)
+	}
+	if payload.FeatureFlags == nil {
+		t.Fatal("feature_flags missing from payload")
+	}
+	if payload.FeatureFlags.ServerEditionEnabled != fx.wantEnabled {
+		t.Errorf("feature_flags.server_edition_enabled = %v, want %v", payload.FeatureFlags.ServerEditionEnabled, fx.wantEnabled)
+	}
+	if payload.FeatureFlags.IdPProvider != fx.wantIdP {
+		t.Errorf("feature_flags.idp_provider = %q, want %q", payload.FeatureFlags.IdPProvider, fx.wantIdP)
+	}
+	if payload.UserCountBucket != fx.wantBucket {
+		t.Errorf("member_count_bucket = %q, want %q", payload.UserCountBucket, fx.wantBucket)
+	}
+	if payload.EnvMarkers == nil {
+		t.Fatal("env_markers missing from payload")
+	}
+
+	data, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	js := string(data)
+	for _, required := range []string{
+		`"server_edition_enabled":`,
+		`"idp_provider":"` + fx.wantIdP + `"`,
+		`"member_count_bucket":"` + fx.wantBucket + `"`,
+		`"is_container":`,
+	} {
+		if !strings.Contains(js, required) {
+			t.Errorf("expected payload to contain %q, missing from:\n%s", required, js)
+		}
+	}
+}
+
+// TestPayloadV13_IdPProviderIsClosedEnum pins the vocabulary: whatever the
+// edition reports must be one of the five contract values, never an issuer.
+func TestPayloadV13_IdPProviderIsClosedEnum(t *testing.T) {
+	fx := newV13Fixture()
+	payload := newV13Service(t, fx).BuildPayload()
+	switch payload.FeatureFlags.IdPProvider {
+	case "google", "github", "microsoft", "oidc", "none":
+	default:
+		t.Errorf("idp_provider %q is outside the closed enum google|github|microsoft|oidc|none", payload.FeatureFlags.IdPProvider)
+	}
+	switch payload.UserCountBucket {
+	case "0", "1-10", "11-100", "101-1000", "1000+":
+	default:
+		t.Errorf("member_count_bucket %q is outside the closed enum 0|1-10|11-100|101-1000|1000+", payload.UserCountBucket)
+	}
+}
+
+// TestPayloadV13_UserCounterNilReportsZero: no counter installed (the personal
+// edition, or a short-lived CLI command) reports "0", never an omitted field.
+func TestPayloadV13_UserCounterNilReportsZero(t *testing.T) {
+	fx := newV13Fixture()
+	fx.userCounter = nil
+	payload := newV13Service(t, fx).BuildPayload()
+	if payload.UserCountBucket != "0" {
+		t.Errorf("member_count_bucket with nil counter = %q, want \"0\"", payload.UserCountBucket)
+	}
+}
+
+// TestPayloadV13_UserCounterErrorOmitsBucket: an installed counter that fails
+// omits the field (the only case it is absent), and the payload still builds.
+func TestPayloadV13_UserCounterErrorOmitsBucket(t *testing.T) {
+	fx := newV13Fixture()
+	fx.userCounter = func() (int, error) { return 0, errors.New("bucket unavailable: " + v13CanaryIssuerHost) }
+	payload := newV13Service(t, fx).BuildPayload()
+	if payload.UserCountBucket != "" {
+		t.Errorf("member_count_bucket with erroring counter = %q, want omitted", payload.UserCountBucket)
+	}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	if strings.Contains(string(data), `"member_count_bucket"`) {
+		t.Errorf("member_count_bucket must be omitted when the counter errors, got:\n%s", data)
+	}
+	if strings.Contains(string(data), v13CanaryIssuerHost) {
+		t.Errorf("counter error text leaked into the payload:\n%s", data)
+	}
+}
+
+// TestPayloadV13_UserCountBuckets pins the bucket edges to the bucketUpstream
+// vocabulary the contract reuses.
+func TestPayloadV13_UserCountBuckets(t *testing.T) {
+	cases := []struct {
+		n    int
+		want string
+	}{
+		{0, "0"}, {1, "1-10"}, {10, "1-10"}, {11, "11-100"}, {100, "11-100"},
+		{101, "101-1000"}, {1000, "101-1000"}, {1001, "1000+"},
+	}
+	for _, c := range cases {
+		fx := newV13Fixture()
+		n := c.n
+		fx.userCounter = func() (int, error) { return n, nil }
+		got := newV13Service(t, fx).BuildPayload().UserCountBucket
+		if got != c.want {
+			t.Errorf("member_count_bucket(%d) = %q, want %q", c.n, got, c.want)
+		}
+	}
+}
+
+// TestPayloadV13_NoForbiddenSubstrings is the Spec 042 privacy regression for
+// the v13 additions: the issuer host, group names, admin/user emails, client
+// id/secret and server names planted in the fixture must not appear anywhere
+// in the rendered payload, and ScanForPII must accept it with those strings
+// registered as runtime-blocked values.
+func TestPayloadV13_NoForbiddenSubstrings(t *testing.T) {
+	fx := newV13Fixture()
+	fx.userCounter = func() (int, error) { return 7, nil }
+	svc := newV13Service(t, fx)
+	// Try to leak identity through the counters too — must be dropped.
+	svc.Registry().RecordBuiltinTool(v13CanaryServerName + ":" + v13CanaryGroupName)
+
+	payload := svc.BuildPayload()
+	data, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	js := string(data)
+	for _, forbidden := range v13Forbidden() {
+		if strings.Contains(js, forbidden) {
+			t.Errorf("PRIVACY VIOLATION: payload contains forbidden substring %q\nfull payload:\n%s", forbidden, js)
+		}
+	}
+
+	withoutBlockedValues(t)
+	BlockedValues = []string{
+		v13CanaryIssuerHost, v13CanaryAdminEmail, v13CanaryUserEmail,
+		v13CanaryGroupName, v13CanaryServerName,
+	}
+	if err := ScanForPII(data); err != nil {
+		t.Errorf("ScanForPII rejected the v13 payload: %v\n%s", err, js)
+	}
+}
+
+// TestPayloadV13_PassesScanWithCommonUsernameBlocked pins the reason the wire
+// key is member_count_bucket and not user_count_bucket. PopulateBlockedValues
+// adds the home-dir basename to BlockedValues and ScanForPII rule 2 matches it
+// as a substring of the WHOLE wire form — keys included. "user" is the
+// username of every `USER user` container image, so a payload key containing
+// "user" would have had every heartbeat from such an install refused before
+// it left the machine (observed: the whole heartbeat-send suite fails on a
+// machine whose HOME is /Users/user). Any future key must keep this green.
+func TestPayloadV13_PassesScanWithCommonUsernameBlocked(t *testing.T) {
+	fx := newV13Fixture()
+	fx.userCounter = func() (int, error) { return 3, nil }
+	payload := newV13Service(t, fx).BuildPayload()
+	data, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	withoutBlockedValues(t)
+	for _, username := range []string{"user", "admin", "mcpproxy"} {
+		BlockedValues = []string{username}
+		if err := ScanForPII(data); err != nil {
+			t.Errorf("a payload key collides with the common username/home basename %q: %v\n%s", username, err, data)
+		}
+	}
+}
diff --git a/internal/telemetry/payload_v2_test.go b/internal/telemetry/payload_v2_test.go
index d7603ca98..da9460ec2 100644
--- a/internal/telemetry/payload_v2_test.go
+++ b/internal/telemetry/payload_v2_test.go
@@ -88,8 +88,8 @@ func TestHeartbeatPayloadV2Marshal(t *testing.T) {
 
 	payload := svc.BuildPayload()
 
-	if payload.SchemaVersion != 12 {
-		t.Errorf("schema_version = %d, want 12", payload.SchemaVersion)
+	if payload.SchemaVersion != 13 {
+		t.Errorf("schema_version = %d, want 13", payload.SchemaVersion)
 	}
 	if payload.AnonymousID != "fixed-id" {
 		t.Errorf("anonymous_id = %q", payload.AnonymousID)
@@ -135,7 +135,7 @@ func TestHeartbeatPayloadV2Marshal(t *testing.T) {
 	}
 	js := string(data)
 	for _, key := range []string{
-		`"schema_version":12`,
+		`"schema_version":13`,
 		`"surface_requests"`,
 		`"builtin_tool_calls"`,
 		`"upstream_tool_call_count_bucket":"11-100"`,
diff --git a/internal/telemetry/payload_v7_test.go b/internal/telemetry/payload_v7_test.go
index 510642c6a..b261444cc 100644
--- a/internal/telemetry/payload_v7_test.go
+++ b/internal/telemetry/payload_v7_test.go
@@ -8,7 +8,7 @@ import (
 )
 
 // TestSchemaVersionIsAtLeastV7 pins FR-014: the Spec 080 payload contract
-// shipped at v7 and may only move forward. The current version is 12 (v8's
+// shipped at v7 and may only move forward. The current version is 13 (v8's
 // additive tpa_scanner / deep_scan_enabled bump, v9's TPA funnel counters +
 // trust_mode_distribution, v10's tool_response_mode /
 // direct_tool_response_mode, then v11's edge-triggered error_code_counts_24h +
@@ -17,8 +17,8 @@ func TestSchemaVersionIsAtLeastV7(t *testing.T) {
 	if SchemaVersion < 7 {
 		t.Fatalf("SchemaVersion = %d, want >= 7 (Spec 080 FR-014)", SchemaVersion)
 	}
-	if SchemaVersion != 12 {
-		t.Fatalf("SchemaVersion = %d, want 12 (v12 heartbeat idempotency key)", SchemaVersion)
+	if SchemaVersion != 13 {
+		t.Fatalf("SchemaVersion = %d, want 13 (v13 server-edition fields)", SchemaVersion)
 	}
 }
 
@@ -78,7 +78,7 @@ func TestPayloadV7_FullyPopulatedPassesScanner(t *testing.T) {
 	}
 
 	for _, required := range []string{
-		`"schema_version":12`,
+		`"schema_version":13`,
 		`"wizard_shown":true`,
 		`"wizard_connect_step":"completed_external"`,
 		`"web_ui_opened":3`,
@@ -109,8 +109,8 @@ func TestPayloadV7_ZeroNewFieldsShapeCompatibleWithV6(t *testing.T) {
 	}
 	js := string(data)
 
-	if !strings.Contains(js, `"schema_version":12`) {
-		t.Errorf("expected schema_version:12 even on a zero-valued payload, got:\n%s", js)
+	if !strings.Contains(js, `"schema_version":13`) {
+		t.Errorf("expected schema_version:13 even on a zero-valued payload, got:\n%s", js)
 	}
 	for _, forbidden := range []string{
 		`"wizard_shown"`,
diff --git a/internal/telemetry/schema_version_guard_test.go b/internal/telemetry/schema_version_guard_test.go
new file mode 100644
index 000000000..5a50fee78
--- /dev/null
+++ b/internal/telemetry/schema_version_guard_test.go
@@ -0,0 +1,65 @@
+package telemetry
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+// schemaVersionGuardFile is this file's own name; the guard skips it because
+// the fragments below, once concatenated, are exactly the literals it hunts.
+const schemaVersionGuardFile = "schema_version_guard_test.go"
+
+// TestSchemaVersionGuard_NoV12PinSurvives (Spec 107 FR-038) walks every Go
+// file in this package and asserts that none of the eleven schema-version pins
+// that were bumped from v12 to v13 survived, in any of the spellings the
+// package used for them. The regex is assembled from fragments so its own
+// source never matches itself, and the v3…v12 change-log comment in
+// telemetry.go ("v12 adds heartbeat_id") is deliberately outside every
+// pattern: it is history, not a pin.
+func TestSchemaVersionGuard_NoV12PinSurvives(t *testing.T) {
+	const old = "1" + "2"
+	// Spellings the eleven bumped sites used, written with <old> in place of
+	// the literal so neither this file nor a raw `grep` over the package
+	// self-matches: `"schema_version":<old>`, `schema_version:<old>`,
+	// `SchemaVersion != <old>`, `const SchemaVersion = <old>`, `want <old>`,
+	// `The current version is <old>`.
+	patterns := []string{
+		`schema_version\\?"?:` + old + `\b`,
+		`SchemaVersion\s*!=\s*` + old + `\b`,
+		`SchemaVersion\s*=\s*` + old + `\b`,
+		`want\s+` + old + `\b`,
+		`version\s+is\s+` + old + `\b`,
+	}
+	re := regexp.MustCompile("(" + strings.Join(patterns, ")|(") + ")")
+
+	entries, err := os.ReadDir(".")
+	if err != nil {
+		t.Fatalf("read package dir: %v", err)
+	}
+	var scanned int
+	for _, e := range entries {
+		name := e.Name()
+		if e.IsDir() || filepath.Ext(name) != ".go" || name == schemaVersionGuardFile {
+			continue
+		}
+		data, err := os.ReadFile(name)
+		if err != nil {
+			t.Fatalf("read %s: %v", name, err)
+		}
+		scanned++
+		for i, line := range strings.Split(string(data), "\n") {
+			if re.MatchString(line) {
+				t.Errorf("%s:%d: a v%s schema pin survived the v%d bump: %s", name, i+1, old, SchemaVersion, strings.TrimSpace(line))
+			}
+		}
+	}
+	if scanned == 0 {
+		t.Fatal("guard scanned no files — it is not running in the package directory")
+	}
+	if SchemaVersion < 13 {
+		t.Errorf("SchemaVersion = %d, want >= 13 (Spec 107 US7)", SchemaVersion)
+	}
+}
diff --git a/internal/telemetry/telemetry.go b/internal/telemetry/telemetry.go
index a7f0bd818..1e26a7e04 100644
--- a/internal/telemetry/telemetry.go
+++ b/internal/telemetry/telemetry.go
@@ -135,7 +135,21 @@ import (
 // events idempotently even when a response is lost after the endpoint has
 // committed the heartbeat. The id is random, contains no machine data, and is
 // scoped to one reporting window.
-const SchemaVersion = 12
+//
+// v13 (Spec 107): feature_flags.server_edition_enabled (bool), feature_flags.idp_provider
+// (closed enum google|github|microsoft|oidc|none — never an issuer), member_count_bucket
+// (closed enum 0|1-10|11-100|101-1000|1000+; "0" when no user counter is installed — the personal
+// edition — and omitted only when the installed counter errors).
+// env_markers.is_container unchanged. No worker migration: fields ride in payload_json.
+//
+// The wire key is member_count_bucket, not the user_count_bucket the Spec 107
+// contract first named: ScanForPII rule 2 substring-matches the home-dir
+// basename against the WHOLE wire form, keys included, and "user" is the
+// username of every `USER user` container image (the server edition's own
+// topology). A key containing "user" would have had every heartbeat from such
+// an install refused before it left the machine. See
+// TestPayloadV13_PassesScanWithCommonUsernameBlocked.
+const SchemaVersion = 13
 
 // HeartbeatPayload is the anonymous telemetry payload sent periodically.
 // Spec 042 expanded the payload with Tier 2 fields; v1 fields are preserved.
@@ -360,6 +374,15 @@ type HeartbeatPayload struct {
 	// "scan" mode can produce a tool-change gate scan at all. No PII: counts
 	// only, no server names, no raw config strings.
 	TrustModeDistribution map[string]int `json:"trust_mode_distribution,omitempty"`
+
+	// Schema v13 (Spec 107 US7): UserCountBucket is the number of server-
+	// edition user records (team members), bucketed into the bucketUpstream
+	// vocabulary (0|1-10|11-100|101-1000|1000+). "0" when no user counter is
+	// installed (the personal edition, short-lived CLI commands); omitted ONLY
+	// when the installed counter errors. A count only — never a user id,
+	// email, group or IdP subject. The wire key deliberately avoids the
+	// substring "user" (see the SchemaVersion comment).
+	UserCountBucket string `json:"member_count_bucket,omitempty"`
 }
 
 // OnboardingSnapshot is the data the telemetry service needs to populate
@@ -481,6 +504,14 @@ type Service struct {
 	// simply omitted (short-lived CLI commands have no supervisor).
 	currentErrorCodesProvider func() map[string]int
 
+	// Spec 107 (US7, schema v13): optional counter of server-edition user
+	// records, installed by the server-edition wiring
+	// (internal/server/serveredition_wire.go) with a closure over the user
+	// store. nil-safe: when unset — the personal edition, short-lived CLI
+	// commands — member_count_bucket reports "0"; when the installed counter
+	// errors, the field is omitted for that heartbeat.
+	userCounter func() (int, error)
+
 	// For testing: override initial delay and heartbeat interval
 	initialDelay      time.Duration
 	heartbeatInterval time.Duration
@@ -824,6 +855,35 @@ func (s *Service) SetCurrentErrorCodesProvider(fn func() map[string]int) {
 	s.currentErrorCodesProvider = fn
 }
 
+// SetUserCounter installs the server-edition user counter behind
+// member_count_bucket (schema v13, Spec 107 US7). Only the count crosses this
+// seam; the closure must never expose user records. nil-safe: passing nil (or
+// never calling this) reports "0", the personal-edition value.
+//
+// Guarded by s.mu (cross-review round 4, chunk 4 P2): Start() launches the
+// heartbeat loop on its own goroutine (runtime/lifecycle.go
+// "go r.telemetryService.Start(...)") from StartBackgroundInitialization,
+// while SetUserCounter is called later, from a different call chain
+// (server.startCustomHTTPServer -> serveredition_wire.go), with no ordering
+// guarantee between the two relative to each other. An unsynchronized write
+// here racing the unsynchronized read in BuildPayload is a real data race
+// under the Go memory model, not merely a theoretical one — the same class
+// the file's own s.mu already protects for resolvedEnabled/config/endpoint
+// and the anonymous-id/funnel fields.
+func (s *Service) SetUserCounter(fn func() (int, error)) {
+	s.mu.Lock()
+	s.userCounter = fn
+	s.mu.Unlock()
+}
+
+// userCounterFunc returns the currently installed user counter (or nil)
+// under s.mu, so BuildPayload never reads s.userCounter directly.
+func (s *Service) userCounterFunc() func() (int, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.userCounter
+}
+
 // resolveLaunchSource returns the LaunchSource to emit in the current
 // heartbeat. Precedence:
 //  1. If the activation bucket's installer_heartbeat_pending flag is true,
@@ -1394,6 +1454,23 @@ func (s *Service) buildHeartbeatWithOneShots(consumeOneShots bool) HeartbeatPayl
 		payload.FeatureFlags.DockerCLISource = s.stats.GetDockerCLISource()
 	}
 
+	// Schema v13 (Spec 107 US7): bucketed server-edition user count. The
+	// counter is a runtime concern (a BBolt read through the user store), so
+	// it is spliced in here rather than in the side-effect-free snapshot
+	// helper. No counter installed → "0"; counter error → field omitted for
+	// this heartbeat (the error text never reaches the payload).
+	payload.UserCountBucket = bucketUpstream(0)
+	if counter := s.userCounterFunc(); counter != nil {
+		if n, err := counter(); err != nil {
+			if s.logger != nil {
+				s.logger.Debug("telemetry: user counter failed; omitting member_count_bucket", zap.Error(err))
+			}
+			payload.UserCountBucket = ""
+		} else {
+			payload.UserCountBucket = bucketUpstream(int64(n))
+		}
+	}
+
 	// Schema v3: fixed-key per-protocol counter over cfg.Servers. Logs
 	// unknown values at debug level via the service logger (bucketed into
 	// "auto") so operators can spot mis-typed config without polluting the
diff --git a/internal/telemetry/telemetry_test.go b/internal/telemetry/telemetry_test.go
index 15425a12f..22ddf8f5a 100644
--- a/internal/telemetry/telemetry_test.go
+++ b/internal/telemetry/telemetry_test.go
@@ -312,16 +312,16 @@ func TestEnsureAnonymousID(t *testing.T) {
 // once the Spec 080 funnel/churn fields ship. This is a tripwire against
 // accidental downgrades.
 func TestSchemaVersionV7(t *testing.T) {
-	if SchemaVersion != 12 {
-		t.Fatalf("SchemaVersion = %d, want 12", SchemaVersion)
+	if SchemaVersion != 13 {
+		t.Fatalf("SchemaVersion = %d, want 13", SchemaVersion)
 	}
 
 	cfg := &config.Config{}
 	svc := New(cfg, "", "v1.0.0", "personal", zap.NewNop())
 	svc.SetRuntimeStats(&mockRuntimeStats{})
 	payload := svc.BuildPayload()
-	if payload.SchemaVersion != 12 {
-		t.Errorf("payload.SchemaVersion = %d, want 12", payload.SchemaVersion)
+	if payload.SchemaVersion != 13 {
+		t.Errorf("payload.SchemaVersion = %d, want 13", payload.SchemaVersion)
 	}
 }
 
diff --git a/internal/telemetry/tpa_funnel_v9_test.go b/internal/telemetry/tpa_funnel_v9_test.go
index 4824609df..9fc614381 100644
--- a/internal/telemetry/tpa_funnel_v9_test.go
+++ b/internal/telemetry/tpa_funnel_v9_test.go
@@ -260,7 +260,7 @@ func TestPayloadV9_TrustModeDistributionAndFunnelCounters(t *testing.T) {
 	}
 	js := string(data)
 	for _, required := range []string{
-		`"schema_version":12`,
+		`"schema_version":13`,
 		`"trust_mode_distribution":`,
 		`"tool_change_gate_scans":2`,
 		`"prompt_scans":1`,
diff --git a/internal/telemetry/tpa_scanner_test.go b/internal/telemetry/tpa_scanner_test.go
index 1177fbe33..fd46321b6 100644
--- a/internal/telemetry/tpa_scanner_test.go
+++ b/internal/telemetry/tpa_scanner_test.go
@@ -264,7 +264,7 @@ func TestPayloadV8_TPAScannerIncludedAndAnonymous(t *testing.T) {
 	js := string(data)
 
 	for _, required := range []string{
-		`"schema_version":12`,
+		`"schema_version":13`,
 		`"tpa_scanner":`,
 		`"scans_completed":2`,
 		`"scans_failed":1`,
diff --git a/native/macos/MCPProxy/MCPProxy/Settings/ConfigSettingsView.swift b/native/macos/MCPProxy/MCPProxy/Settings/ConfigSettingsView.swift
index d4e1a8aed..90eae4f41 100644
--- a/native/macos/MCPProxy/MCPProxy/Settings/ConfigSettingsView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Settings/ConfigSettingsView.swift
@@ -163,6 +163,27 @@ final class ConfigStore: ObservableObject {
         )
     }
 
+    /// Binding for a `listLines` textarea (fields.ts `listKind: 'lines'`): the
+    /// JSON value is a []string shown one entry per line. Writing splits on
+    /// newlines AND commas (a pasted "a,b" still yields two entries), trims,
+    /// and drops blank entries, so a cleared box is an empty list — never a
+    /// string the Go side cannot decode into []string. Clearing a key the core
+    /// never sent stores "unset" rather than [], so the row does not read as
+    /// dirty against an absent key (same tri-state as optionalStringBinding).
+    func linesBinding(_ key: String) -> Binding<String> {
+        Binding(
+            get: { linesText(self.value(key)) },
+            set: {
+                let list = parseLines($0)
+                if list.isEmpty, isBlankValue(configGet(self.original, key)) {
+                    self.setValue(key, nil)
+                } else {
+                    self.setValue(key, list)
+                }
+            }
+        )
+    }
+
     func doubleBinding(_ key: String) -> Binding<Double> {
         Binding(
             get: { coerceDouble(self.value(key)) ?? 0 },
@@ -190,6 +211,21 @@ func coerceString(_ v: Any?) -> String {
     default: return ""
     }
 }
+/// Render a []string as one entry per line; a scalar falls back to its string
+/// form so a hand-edited file never shows as blank.
+func linesText(_ v: Any?) -> String {
+    if let arr = v as? [Any] { return arr.map { coerceString($0) }.joined(separator: "\n") }
+    return coerceString(v)
+}
+
+/// Parse textarea text into a trimmed []string (mirrors textToList in
+/// fields.ts): newlines and commas both separate entries; blanks are dropped.
+func parseLines(_ text: String) -> [String] {
+    text.components(separatedBy: CharacterSet(charactersIn: "\n,"))
+        .map { $0.trimmingCharacters(in: .whitespaces) }
+        .filter { !$0.isEmpty }
+}
+
 func coerceDouble(_ v: Any?) -> Double? {
     switch v {
     case let n as NSNumber: return n.doubleValue
@@ -404,14 +440,17 @@ struct ConfigFieldRow: View {
             }
         case .textarea:
             // The instructions field: multi-line, and its placeholder is the
-            // live built-in default rather than an example.
+            // live built-in default rather than an example. A `listLines`
+            // field (trusted_proxies) binds a []string one entry per line and
+            // keeps its own example placeholder.
+            let text = field.listLines ? store.linesBinding(field.key) : store.optionalStringBinding(field.key)
             ZStack(alignment: .topLeading) {
-                TextEditor(text: store.optionalStringBinding(field.key))
+                TextEditor(text: text)
                     .font(.system(.callout, design: .monospaced))
                     .frame(minHeight: 120)
                     .overlay(RoundedRectangle(cornerRadius: 6).stroke(Color(nsColor: .separatorColor)))
-                if coerceString(store.value(field.key)).isEmpty {
-                    Text(store.defaultInstructions ?? field.placeholder ?? "")
+                if text.wrappedValue.isEmpty {
+                    Text(field.listLines ? (field.placeholder ?? "") : (store.defaultInstructions ?? field.placeholder ?? ""))
                         .font(.system(.caption, design: .monospaced))
                         .foregroundColor(.secondary)
                         .padding(.horizontal, 6).padding(.vertical, 10)
diff --git a/native/macos/MCPProxy/MCPProxy/Settings/SettingsCatalog.swift b/native/macos/MCPProxy/MCPProxy/Settings/SettingsCatalog.swift
index 96d22c288..e75bf20a0 100644
--- a/native/macos/MCPProxy/MCPProxy/Settings/SettingsCatalog.swift
+++ b/native/macos/MCPProxy/MCPProxy/Settings/SettingsCatalog.swift
@@ -38,6 +38,11 @@ struct ConfigField: Identifiable {
     // this is the real default (e.g. "30s"), so a blank field reads as
     // "inherit the default" rather than a generic example.
     var placeholder: String? = nil
+    // Mirrors `listKind: 'lines'` in fields.ts: the JSON value is a []string
+    // that the textarea shows one entry per line (Spec 107 `trusted_proxies`).
+    // The store's linesBinding does the join/split; a plain textarea stays a
+    // string field.
+    var listLines: Bool = false
     // Danger confirm: present a confirm dialog before saving. For toggles,
     // only when the new value == dangerConfirmValue (nil = always confirm).
     var dangerMessage: String? = nil
@@ -147,6 +152,18 @@ enum SettingsCatalog {
             placeholder: "127.0.0.1:8080",
             dangerMessage: "Binding to a non-loopback address (e.g. 0.0.0.0) exposes mcpproxy to your network. Make sure \u{201C}Require API key for MCP clients\u{201D} is enabled. Continue?"
         ),
+        // Spec 107 FR-027 (edition-neutral, hot-reloaded): forwarded headers
+        // are honoured only when the direct peer is in this list. Mirrors the
+        // fields.ts row so scripts/check-settings-parity.py stays green.
+        ConfigField(
+            key: "trusted_proxies",
+            label: "Trusted reverse proxies",
+            help: "One CIDR or IP address per line (e.g. 10.0.0.0/8). Forwarded headers (X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, X-Real-IP) are honoured only from these peers; leave empty when mcpproxy is not behind a proxy. Applies without a restart.",
+            control: .textarea,
+            optional: true,
+            placeholder: "10.0.0.0/8",
+            listLines: true
+        ),
     ]
 
     // ---- Section 2: General ----
diff --git a/native/macos/MCPProxy/MCPProxyTests/SettingsTrustedProxiesFieldTests.swift b/native/macos/MCPProxy/MCPProxyTests/SettingsTrustedProxiesFieldTests.swift
new file mode 100644
index 000000000..0718f7f5f
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxyTests/SettingsTrustedProxiesFieldTests.swift
@@ -0,0 +1,79 @@
+import XCTest
+@testable import MCPProxy
+
+/// Spec 107 FR-027 / T058: the edition-neutral `trusted_proxies` key is a
+/// []string in the config file and a one-entry-per-line textarea in the Web
+/// UI (`listKind: 'lines'`). The native catalogue must carry the same row
+/// (scripts/check-settings-parity.py) and must round-trip the ARRAY — a plain
+/// string binding would render the list as "" and save a string the core
+/// cannot decode into []string.
+final class SettingsTrustedProxiesFieldTests: XCTestCase {
+
+    private var field: ConfigField? {
+        SettingsCatalog.security.first { $0.key == "trusted_proxies" }
+    }
+
+    @MainActor
+    private func hydratedStore(_ cfg: [String: Any]) -> ConfigStore {
+        let store = ConfigStore(appState: AppState())
+        store.hydrate(from: cfg)
+        return store
+    }
+
+    func testRowExistsAsALinesTextareaInSecurity() {
+        XCTAssertNotNil(field, "trusted_proxies must be in the Security & Access section")
+        XCTAssertEqual(field?.control, .textarea)
+        XCTAssertTrue(field?.listLines ?? false, "the row must bind a []string, not a scalar")
+        XCTAssertTrue(field?.optional ?? false)
+        XCTAssertFalse(field?.restart ?? true, "trusted_proxies is hot-reloaded (FR-027)")
+    }
+
+    func testParseLinesSplitsOnNewlinesAndCommasAndDropsBlanks() {
+        XCTAssertEqual(parseLines("10.0.0.0/8\n 192.168.1.1 \n\n,fd00::/8,"),
+                       ["10.0.0.0/8", "192.168.1.1", "fd00::/8"])
+        XCTAssertEqual(parseLines("   \n  "), [])
+    }
+
+    func testLinesTextRendersOneEntryPerLine() {
+        XCTAssertEqual(linesText(["10.0.0.0/8", "fd00::/8"]), "10.0.0.0/8\nfd00::/8")
+        XCTAssertEqual(linesText(nil), "")
+        XCTAssertEqual(linesText(NSNull()), "")
+    }
+
+    @MainActor
+    func testBindingReadsTheArrayAndWritesAnArrayBack() {
+        let store = hydratedStore(["trusted_proxies": ["10.0.0.0/8"]])
+        let binding = store.linesBinding("trusted_proxies")
+        XCTAssertEqual(binding.wrappedValue, "10.0.0.0/8")
+        XCTAssertFalse(store.isDirty("trusted_proxies"))
+
+        binding.wrappedValue = "10.0.0.0/8\nfd00::/8"
+        XCTAssertEqual(store.value("trusted_proxies") as? [String], ["10.0.0.0/8", "fd00::/8"])
+        XCTAssertTrue(store.isDirty("trusted_proxies"))
+
+        // The PATCH payload carries the array, never a joined string.
+        let partial = buildPartial(["trusted_proxies": store.value("trusted_proxies") as Any], ["trusted_proxies"])
+        XCTAssertEqual(partial["trusted_proxies"] as? [String], ["10.0.0.0/8", "fd00::/8"])
+    }
+
+    /// Clearing a list the core DID send must save an empty list (trust
+    /// nobody), not "unset" — the Web UI sends [] for the same edit.
+    @MainActor
+    func testClearingAPresentListSavesAnEmptyList() {
+        let store = hydratedStore(["trusted_proxies": ["10.0.0.0/8"]])
+        store.linesBinding("trusted_proxies").wrappedValue = "\n"
+        XCTAssertEqual(store.value("trusted_proxies") as? [String], [])
+        XCTAssertTrue(store.isDirty("trusted_proxies"))
+    }
+
+    /// A key the core never sent must not read as dirty after the textarea is
+    /// touched and left blank (the same tri-state as the optional durations).
+    @MainActor
+    func testBlankOnAnAbsentKeyStaysUndirty() {
+        let store = hydratedStore(["listen": "127.0.0.1:8080"])
+        XCTAssertFalse(store.isDirty("trusted_proxies"))
+        store.linesBinding("trusted_proxies").wrappedValue = "  \n"
+        XCTAssertFalse(store.isDirty("trusted_proxies"))
+        XCTAssertTrue(store.dirtyKeys(in: SettingsCatalog.allFields).isEmpty)
+    }
+}
diff --git a/oas/docs.go b/oas/docs.go
index 10ba71894..4e816dfcb 100644
--- a/oas/docs.go
+++ b/oas/docs.go
@@ -6,7 +6,7 @@ import "github.com/swaggo/swag/v2"
 
 const docTemplate = `{
     "schemes": {{ marshal .Schemes }},
-    "components": {"schemas":{"config.ConcurrencyDefaults":{"description":"ServerConcurrencyDefaults is scope (b) of FR-020: the blanket per-server\ndefault set inherited by every server that does not override a setting.\nAbsent (the default) = no per-server limiting unless a server configures\nit explicitly. File/API-configured only — no env scheme (FR-022).","properties":{"max_concurrent_requests":{"type":"integer"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"}},"type":"object"},"config.Config":{"properties":{"activity_cleanup_interval_min":{"description":"Background cleanup interval in minutes (default: 60)","type":"integer"},"activity_max_records":{"description":"Max records before pruning (default: 100000)","type":"integer"},"activity_max_response_size":{"description":"Response truncation limit in bytes (default: 65536)","type":"integer"},"activity_max_size_mb":{"description":"ActivityMaxSizeMB caps the total activity-log size in MB before the\noldest records are pruned. Omit the key for the 256MB default; set it to\n0 to disable the size cap.","type":"integer"},"activity_retention_days":{"description":"Activity logging settings (RFC-003)","type":"integer"},"aggregate_upstream_prompts":{"description":"AggregateUpstreamPrompts, when true, aggregates every connected upstream\nserver's advertised MCP prompts into mcpproxy's own prompts/list\n(exposed as \"\u003cserver\u003e__\u003cprompt\u003e\"). OFF by default: users are safe by\ndefault and opt in deliberately. EnablePrompts still governs the built-in\nprompts + the prompts capability; this flag gates ONLY the upstream\naggregation performed by RefreshPrompts. Hot-reloadable.","type":"boolean"},"allow_private_registry_fetch":{"description":"AllowPrivateRegistryFetch opts out of the registry SSRF guard (MCP-1076,\nCWE-918). By default (false) registry fetches refuse any host that is — or\nresolves to — a non-routable address (loopback, RFC1918/CGNAT private,\nlink-local incl. the 169.254.169.254 cloud-metadata endpoint), so a\nmalicious or typo'd registry source cannot turn the daemon into a\nrequest-forgery vector against internal services.\n\nThis opt-out is BLANKET (all-or-nothing): setting it true disables the\nguard for EVERY non-routable range at once — loopback, RFC1918/CGNAT\nprivate, link-local AND the 169.254.169.254 cloud-metadata endpoint. There\nis no way to allow only loopback; enabling it for a localhost dev registry\nalso re-opens the cloud-metadata SSRF vector. Set true ONLY when you\nintentionally run a trusted registry mirror on an internal/private address,\nideally on a host with no cloud-metadata exposure. The change takes effect\nonly on daemon (re)start or config reload.","type":"boolean"},"allow_server_add":{"type":"boolean"},"allow_server_remove":{"type":"boolean"},"api_key":{"description":"Security settings","type":"string"},"call_tool_timeout":{"type":"string"},"check_server_repo":{"description":"Repository detection settings","type":"boolean"},"code_execution_max_parallel":{"description":"Default concurrency for call_tools() batches (1-32, default: 8)","type":"integer"},"code_execution_max_tool_calls":{"description":"Max tool calls per execution (0 = unlimited, default: 0)","type":"integer"},"code_execution_pool_size":{"description":"JavaScript runtime pool size (default: 10)","type":"integer"},"code_execution_timeout_ms":{"description":"Timeout in milliseconds (default: 120000, max: 600000)","type":"integer"},"data_dir":{"type":"string"},"debug_search":{"type":"boolean"},"direct_tool_response_mode":{"description":"DirectToolResponseMode selects the serialization of the DIRECT\nenumeration surface (Spec 102). Valid values: \"\" (= full), \"full\"\n(default: today's schema-bearing entries), \"deferred\" (description +\ncompact signature, with a minimal permissive input schema; upstream\ninputSchema and outputSchema are stripped and recovered on demand via\ndescribe_tool).\n\nDeliberately NOT an extension of tool_response_mode: reusing that axis\nwould silently change /mcp/all output for every deployment already\nrunning compact, which FR-015 forbids. Serialization-only — it never\nchanges WHICH tools are listed, only how (FR-008). Hot-reloadable.","type":"string"},"disable_management":{"type":"boolean"},"docker_isolation":{"$ref":"#/components/schemas/config.DockerIsolationConfig"},"docker_recovery":{"$ref":"#/components/schemas/config.DockerRecoveryConfig"},"enable_code_execution":{"description":"Code execution settings","type":"boolean"},"enable_prompts":{"description":"Prompts settings","type":"boolean"},"enable_socket":{"description":"Enable Unix socket/named pipe for local IPC (default: true)","type":"boolean"},"enable_tray":{"description":"Deprecated: EnableTray is unused and has no runtime effect. Kept for backward compatibility.","type":"boolean"},"environment":{"$ref":"#/components/schemas/secureenv.EnvConfig"},"features":{"$ref":"#/components/schemas/config.FeatureFlags"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned stdio upstream servers (MCP-2769). OFF by\ndefault: proxy URLs commonly embed credentials (http://user:pass@proxy), so\nforwarding them to every upstream is a credential-leak risk. When enabled,\nvalues are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"health_check_interval":{"description":"Discovery \u0026 health-check cadence (spec 074, #608). Both are *Duration\ntri-state pointers: nil = inherit the built-in default; a pointer to 0s =\nthe loop is disabled; a positive value = that interval. Defaults live only\nin the resolvers (ResolveHealthCheckInterval / ResolveToolDiscoveryInterval)\nso an unset key behaves exactly as before this feature (SC-005). Validated\nin Validate(): health-check ∈ {0} ∪ [5s,1h]; tool-discovery ∈ {0} ∪ [30s,24h].","type":"string"},"http_idle_timeout":{"description":"HTTPIdleTimeout caps how long an idle keep-alive connection is kept open.\nUnset = 180s. \"0s\" removes the dedicated idle deadline, but net/http then\nfalls back to ReadTimeout — idle is fully unbounded only when\nhttp_read_timeout is also \"0s\". Requires a restart.","type":"string"},"http_read_timeout":{"description":"HTTPReadTimeout caps how long reading a whole request (headers + body)\nmay take. Unset = 120s; \"0s\" disables it. Requires a restart.","type":"string"},"http_write_timeout":{"description":"HTTPWriteTimeout caps how long producing a whole response may take on\nnon-streaming endpoints (REST, Web UI, health). Unset = 120s; \"0s\"\ndisables it globally. MCP and SSE /events routes are exempt by design.","type":"string"},"init_timeout":{"description":"InitTimeout is the global default deadline for an upstream's MCP\n` + "`" + `initialize` + "`" + ` handshake (MCP-3322 / GH #760). *Duration tri-state: nil =\ninherit the built-in 30s default; a positive value = that deadline. A\nper-server InitTimeout overrides this. Resolved by ResolveInitTimeout;\nvalidated to {0} ∪ [1s, 30m] in Validate(). Servers doing legitimate\nfirst-run warmup (cache/index build) before answering ` + "`" + `initialize` + "`" + ` can\nraise this so they are not killed mid-startup.","type":"string"},"instructions":{"description":"Instructions text returned in the MCP initialize response to guide AI agents.\nWhen empty, a built-in default is used that explains retrieve_tools workflow.","type":"string"},"intent_declaration":{"$ref":"#/components/schemas/config.IntentDeclarationConfig"},"listen":{"type":"string"},"logging":{"$ref":"#/components/schemas/config.LogConfig"},"max_concurrent_requests":{"description":"Concurrency limits (spec 093, GH #955). Scope (a) of FR-020: the GLOBAL\nAGGREGATE limiter — one proxy-wide cap on concurrently running upstream\ntool calls, with its own bounded wait queue. Tri-state pointers: absent =\nthe limiter does not exist (default, zero behavior change); an explicit 0\nmax also disables it; positive = that cap. This scope is NEVER a\nper-server inheritance source — per-server values come from\nServerConcurrencyDefaults / the per-server overrides — but a server's\neffective concurrency is bounded by BOTH its own limiter and this one.\nResolved by ResolveGlobalConcurrency; hot-reloadable; overridable via\nMCPPROXY_MAX_CONCURRENT_REQUESTS / _QUEUE_SIZE / _QUEUE_TIMEOUT (FR-022).","type":"integer"},"max_result_size_chars":{"description":"MaxResultSizeChars is advertised on every tool as\n` + "`" + `_meta.anthropic/maxResultSizeChars` + "`" + `; it raises Claude Code's\ninline-response ceiling from 50k to up to 500k chars. Omit the key for\nthe 500000 default; set it to 0 to disable the annotation.","type":"integer"},"mcpServers":{"items":{"$ref":"#/components/schemas/config.ServerConfig"},"type":"array","uniqueItems":false},"oauth_expiry_warning_hours":{"description":"Health status settings","type":"number"},"observability":{"$ref":"#/components/schemas/config.ObservabilityConfig"},"output_sanitisation":{"$ref":"#/components/schemas/config.OutputSanitisationConfig"},"output_validation":{"$ref":"#/components/schemas/config.OutputValidationConfig"},"profiles":{"description":"Profiles are optional named, server-scoped views exposed at /mcp/p/\u003cname\u003e\n(Spec 057). Absent/empty is fully supported — /mcp is unchanged and configs\nwithout this key serialize byte-identically (SC-004).","items":{"$ref":"#/components/schemas/config.ProfileConfig"},"type":"array","uniqueItems":false},"quarantine_enabled":{"description":"QuarantineEnabled controls whether quarantine is active. It gates two\nthings together:\n  1. Server-level auto-quarantine for newly added servers (issue #370).\n     When true, servers added via the upstream_servers MCP tool or the\n     REST API default to quarantined=true; when false, they default to\n     quarantined=false. Explicit per-request values always win.\n  2. Tool-level quarantine (Spec 032): per-tool SHA-256 approval of\n     tool descriptions/schemas.\nWhen nil (default), quarantine is enabled (secure by default). Set to\nexplicit false to opt out of both. Per-server SkipQuarantine still\napplies for the tool-level check on individual servers.","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"read_only_mode":{"type":"boolean"},"registries":{"description":"Registries configuration for MCP server discovery","items":{"$ref":"#/components/schemas/config.RegistryEntry"},"type":"array","uniqueItems":false},"registries_locked":{"description":"RegistriesLocked is an enterprise stub knob (MCP-866): when true, runtime\nadditions of custom registries (e.g. ` + "`" + `registry add-source` + "`" + `, the REST/MCP\nadd-source surface) are rejected so an administrator can pin the discovery\nsources. Built-in defaults are unaffected. Documented but otherwise inert\nbeyond the add-source rejection.","type":"boolean"},"require_mcp_auth":{"description":"Require authentication on /mcp endpoint (default: false)","type":"boolean"},"reveal_secret_headers":{"description":"RevealSecretHeaders, when true, disables the redaction of the\nsecret-bearing server fields — sensitive header values (Authorization,\nX-API-Key, Cookie, …), env-var secrets, and URL query credentials — in\nresponses from the ` + "`" + `upstream_servers` + "`" + ` MCP tool, the ` + "`" + `/api/v1/servers` + "`" + `\nREST API, and the SSE event stream. It also lets URL secrets echoed\ninto last_error / health.detail through unscrubbed.\n\nDefault false — sensitive values are surfaced masked as\n` + "`" + `••••\u003clast2\u003e (\u003cN\u003e chars)` + "`" + ` (error strings use ` + "`" + `***REDACTED***` + "`" + `) so an\nMCP agent cannot read Bearer tokens / API keys / URL secrets out of\nanother upstream's config (PR #425, issue #872). ${env:…}/${keyring:…}\nreferences are labels, not secrets, and pass through unchanged.\n\nThe Web UI / macOS tray edit forms work without seeing the real\nvalues: PATCH /api/v1/servers/{id} deep-merges (omitted keys are\npreserved, see ` + "`" + `headers_remove` + "`" + ` / ` + "`" + `env_remove` + "`" + ` for explicit\ndeletes), so clients compute a diff and only send the keys that\nactually changed. Redacted-but-unchanged values never round-trip\n— the backend keeps the real string. Set this to true if a\ndownstream tool genuinely needs raw values in the response.","type":"boolean"},"routing_mode":{"description":"Routing mode (Spec 031): how MCP tools are exposed to clients\nValid values: \"retrieve_tools\" (default), \"direct\", \"code_execution\"","type":"string"},"security":{"$ref":"#/components/schemas/config.SecurityConfig"},"sensitive_data_detection":{"$ref":"#/components/schemas/config.SensitiveDataDetectionConfig"},"server_concurrency_defaults":{"$ref":"#/components/schemas/config.ConcurrencyDefaults"},"telemetry":{"$ref":"#/components/schemas/config.TelemetryConfig"},"tls":{"$ref":"#/components/schemas/config.TLSConfig"},"tokenizer":{"$ref":"#/components/schemas/config.TokenizerConfig"},"tool_call_max_records_per_server":{"description":"Calls retained per server (default: 1000)","type":"integer"},"tool_call_max_response_size":{"description":"Bounds for the per-server tool-call history behind GET /api/v1/tool-calls\n(#1176). It is a recent-debugging window, not an audit log — the activity\nlog is the durable record — and it kept every upstream response whole,\nper server, forever. A non-positive value means \"use the default\", not\n\"disable\": this store must never be unbounded again, so there is\ndeliberately no off switch.","type":"integer"},"tool_discovery_interval":{"type":"string"},"tool_response_limit":{"type":"integer"},"tool_response_mode":{"description":"Tool response mode (Spec 085): how retrieve_tools serializes results.\nValid values: \"\" (= full), \"full\" (default: today's schema-bearing\nentries), \"compact\" (signature + first-sentence entries). Orthogonal to\nrouting_mode — routing_mode selects the tool SURFACE, this selects the\nSERIALIZATION within the retrieve_tools surface. Serialization-only: it\nnever affects the query, ranking, or result set. Hot-reloadable.","type":"string"},"tool_response_session_risk_warning":{"description":"ToolResponseSessionRiskWarning controls whether the prose ` + "`" + `warning` + "`" + ` field\nis included in the ` + "`" + `session_risk` + "`" + ` object returned by ` + "`" + `retrieve_tools` + "`" + `.\nThe structured fields (level, lethal_trifecta, has_open_world_tools, etc.)\nare always included. Default: false (quiet for LLM clients) — see issue #406.\nMost tools lack annotations, so the MCP-spec defaults treat them as fully\npermissive across all three risk axes, which makes the prose warning fire\non almost every call and wastes tokens.","type":"boolean"},"tools_limit":{"type":"integer"},"toon_min_savings_pct":{"description":"ToonMinSavingsPct is the minimum byte-savings percentage (validated\n1-90; 0/unset → 15) the complete TOON emission (marker + hint + body)\nmust achieve over the exact passthrough emission for adaptive mode to\nencode a block. Byte savings approximate token savings for the tabular\npayload class; the spec-083 profiler reports true token deltas.\nGlobal-only (no per-server override, FR-001).","type":"integer"},"toon_output":{"description":"ToonOutput selects the TOON encoding mode for call_tool_* result text\nblocks (spec 084): \"off\" (default — responses byte-identical to\npre-feature behavior), \"adaptive\" (encode only tabular-uniform payloads\nthat beat compact JSON by ToonMinSavingsPct), or \"always\"\n(benchmark/debug only — encodes every JSON-parseable block and can\nINCREASE token cost). Per-server override: ServerConfig.ToonOutput.\nResolved by ResolveToonOutput; hot-reloadable.","type":"string"},"top_k":{"description":"Deprecated: TopK is superseded by ToolsLimit and has no runtime effect. Kept for backward compatibility.","type":"integer"},"tray_endpoint":{"description":"Tray endpoint override (unix:// or npipe://)","type":"string"},"trusted_hosts":{"description":"TrustedHosts lists non-loopback Host header values accepted on loopback\nlisteners (GH #898). DNS-rebinding protection rejects requests whose Host\nheader is not a loopback address when mcpproxy listens on loopback; a\nreverse proxy (nginx → 127.0.0.1) forwarding the public domain in Host\ntrips it. Entries are hostnames, case-insensitive; an entry without a\nport matches any port, with a port it must match exactly; a leading dot\n(\".example.com\") is a subdomain wildcard. The single entry \"*\" disables\nHost and Origin validation entirely. The same list also validates the\nOrigin header when present (MCP spec DNS-rebinding defense). Empty\n(default) keeps full protection. Env override: MCPPROXY_TRUSTED_HOSTS\n(comma-separated).","items":{"type":"string"},"type":"array","uniqueItems":false},"update_check":{"$ref":"#/components/schemas/config.UpdateCheckConfig"}},"type":"object"},"config.CustomPattern":{"properties":{"category":{"description":"Category (defaults to \"custom\")","type":"string"},"keywords":{"description":"Keywords to match (mutually exclusive with Regex)","items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"description":"Unique identifier for this pattern","type":"string"},"regex":{"description":"Regex pattern (mutually exclusive with Keywords)","type":"string"},"severity":{"description":"Risk level: critical, high, medium, low","type":"string"}},"type":"object"},"config.DeepScanConfig":{"description":"DeepScan is the opt-in \"deep scan\" layer (Spec 077 US3). It subsumes the\ndeprecated top-level scanner_fetch_package_source / scanner_disable_no_new_privileges\nkeys (migrated on load) and gates the heavy Docker-based scanners + source\nextraction. Disabled by default (FR-006): only the deterministic in-process\nbaseline scanner runs. A deep-scan failure NEVER changes the baseline verdict\n(FR-007/FR-008).","properties":{"disable_no_new_privileges":{"description":"DisableNoNewPrivileges, when true, omits the ` + "`" + `--security-opt\nno-new-privileges` + "`" + ` flag from scanner container runs (snap-docker/AppArmor\nescape hatch). Absorbs the deprecated top-level\nscanner_disable_no_new_privileges. Default false.","type":"boolean"},"enabled":{"description":"Enabled is the master opt-in for the heavy layer (FR-006). Default false.","type":"boolean"},"fetch_package_source":{"description":"FetchPackageSource controls whether the scanner fetches the PUBLISHED\nsource of package-runner servers (npx/uvx) — without executing it — when\nno local source is available. Absorbs the deprecated top-level\nscanner_fetch_package_source. Default (nil) is ENABLED within deep scan.","type":"boolean"},"scanners":{"description":"Scanners optionally restricts which deep scanners may run under the\numbrella (by scanner id). Empty ⇒ all enabled deep scanners are eligible.","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.DockerIsolationConfig":{"description":"Docker isolation settings","properties":{"cpu_limit":{"description":"CPU limit for containers","type":"string"},"default_images":{"additionalProperties":{"type":"string"},"description":"Map of runtime type to Docker image","type":"object"},"enable_cache_volume":{"description":"Mount shared cache volumes for faster restarts (default: true)","type":"boolean"},"enabled":{"description":"Global enable/disable for Docker isolation (legacy; superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments","items":{"type":"string"},"type":"array","uniqueItems":false},"log_driver":{"description":"Docker log driver (default: json-file)","type":"string"},"log_max_files":{"description":"Maximum number of log files (default: 3)","type":"string"},"log_max_size":{"description":"Maximum size of log files (default: 100m)","type":"string"},"memory_limit":{"description":"Memory limit for containers","type":"string"},"mode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"network_mode":{"description":"Docker network mode (default: bridge)","type":"string"},"registry":{"description":"Custom registry (defaults to docker.io)","type":"string"},"timeout":{"description":"Container startup timeout","type":"string"}},"type":"object"},"config.DockerRecoveryConfig":{"description":"Docker recovery settings","properties":{"enabled":{"description":"Enable Docker recovery monitoring (default: true)","type":"boolean"},"max_retries":{"description":"Maximum retry attempts (0 = unlimited)","type":"integer"},"notify_on_failure":{"description":"Show notification on recovery failure (default: true)","type":"boolean"},"notify_on_retry":{"description":"Show notification on each retry (default: false)","type":"boolean"},"notify_on_start":{"description":"Show notification when recovery starts (default: true)","type":"boolean"},"notify_on_success":{"description":"Show notification on successful recovery (default: true)","type":"boolean"},"persistent_state":{"description":"Save recovery state across restarts (default: true)","type":"boolean"}},"type":"object"},"config.FeatureFlags":{"description":"Deprecated: Features flags are unused and have no runtime effect. Kept for backward compatibility.","properties":{"enable_async_storage":{"type":"boolean"},"enable_caching":{"type":"boolean"},"enable_contract_tests":{"type":"boolean"},"enable_debug_logging":{"description":"Development features","type":"boolean"},"enable_docker_isolation":{"type":"boolean"},"enable_event_bus":{"type":"boolean"},"enable_health_checks":{"type":"boolean"},"enable_metrics":{"type":"boolean"},"enable_oauth":{"description":"Security features","type":"boolean"},"enable_observability":{"description":"Observability features","type":"boolean"},"enable_quarantine":{"type":"boolean"},"enable_runtime":{"description":"Runtime features","type":"boolean"},"enable_search":{"description":"Storage features","type":"boolean"},"enable_sse":{"type":"boolean"},"enable_tracing":{"type":"boolean"},"enable_tray":{"type":"boolean"},"enable_web_ui":{"description":"UI features","type":"boolean"}},"type":"object"},"config.IntentDeclarationConfig":{"description":"Intent declaration settings (Spec 018)","properties":{"strict_server_validation":{"description":"StrictServerValidation controls whether server annotation mismatches\ncause rejection (true) or just warnings (false).\nDefault: true (reject mismatches)","type":"boolean"}},"type":"object"},"config.IsolationConfig":{"description":"Per-server isolation settings","properties":{"enabled":{"description":"Enable Docker isolation for this server (nil = inherit global; legacy, superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments for this server","items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"description":"Custom Docker image (overrides default)","type":"string"},"log_driver":{"description":"Docker log driver override for this server","type":"string"},"log_max_files":{"description":"Maximum number of log files override","type":"string"},"log_max_size":{"description":"Maximum size of log files override","type":"string"},"mode":{"$ref":"#/components/schemas/config.IsolationMode"},"network_mode":{"description":"Custom network mode for this server","type":"string"},"working_dir":{"description":"Custom working directory in container","type":"string"}},"type":"object"},"config.IsolationMode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"config.LogConfig":{"description":"Logging configuration","properties":{"compress":{"type":"boolean"},"enable_console":{"type":"boolean"},"enable_file":{"type":"boolean"},"filename":{"type":"string"},"json_format":{"type":"boolean"},"level":{"type":"string"},"log_dir":{"description":"Custom log directory","type":"string"},"max_age":{"description":"days","type":"integer"},"max_backups":{"description":"number of backup files","type":"integer"},"max_size":{"description":"MB","type":"integer"}},"type":"object"},"config.MetricsExporterConfig":{"description":"Metrics gates the Prometheus /metrics scrape endpoint (MCP-32). Disabled\nby default — operators opt in for k8s/enterprise deployments.","properties":{"enabled":{"description":"Enabled exposes /metrics on the existing HTTP listener when true.","type":"boolean"}},"type":"object"},"config.OAuthConfig":{"description":"OAuth configuration (keep even when empty to signal OAuth requirement)","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"description":"Additional OAuth parameters (e.g., RFC 8707 resource)","type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_uri":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ObservabilityConfig":{"description":"Observability settings (Spec 069): usage aggregate cache/persistence cadence.","properties":{"metrics":{"$ref":"#/components/schemas/config.MetricsExporterConfig"},"tracing":{"$ref":"#/components/schemas/config.TracingExporterConfig"},"usage_cache_ttl":{"description":"UsageCacheTTL bounds the freshness of the usage endpoint's read cache for\nwide windows (FR-005). Default 5s.","type":"string"},"usage_persist_interval":{"description":"UsagePersistInterval is how often the actor-owned usage aggregate snapshot\nis flushed to storage. Default 30s.","type":"string"}},"type":"object"},"config.OutputSanitisationConfig":{"description":"Output sanitisation settings (Spec 054 Track B)","properties":{"max_redactions":{"description":"cap on redactions per response; default 100","type":"integer"},"response_action":{"description":"\"spotlight\" | \"redact\" | \"block\"; default \"spotlight\"","type":"string"},"spotlight_untrusted":{"description":"wrap untrusted output in spotlight markers; default true","type":"boolean"},"strip_classes":{"description":"classes to strip: ansi/c0c1/bidi/zero_width","items":{"type":"string"},"type":"array","uniqueItems":false},"strip_control_chars":{"description":"strip control-character classes; default false","type":"boolean"}},"type":"object"},"config.OutputValidationConfig":{"description":"Output-schema validation settings (Spec 056)","properties":{"max_bytes":{"description":"structured payload byte cap; default 5\u003c\u003c20","type":"integer"},"max_depth":{"description":"nesting depth cap; default 64","type":"integer"},"missing_structured_content":{"description":"\"allow\" | \"block\"; default \"allow\"","type":"string"},"mode":{"description":"\"off\" | \"warn\" | \"strict\"; default \"warn\"","type":"string"}},"type":"object"},"config.ProfileConfig":{"properties":{"name":{"description":"URL slug, validated","type":"string"},"servers":{"description":"references to mcpServers[].name","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.RegistryEntry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag for this registry (MCP-866):\nRegistryProvenanceOfficial for built-in defaults, RegistryProvenanceCustom\nfor user-added registries. It is authoritatively (re)computed by the\nregistries merge from whether the ID is a shipped default — a user cannot\nclaim \"official\" by writing it into their config.","type":"string"},"requires_key":{"description":"RequiresKey marks a registry that needs an API key to be queried. When\ntrue and no key is configured, the registry is skipped/marked unavailable\nrather than failing the whole search (FR-008).","type":"boolean"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"url":{"type":"string"}},"type":"object"},"config.SecurityConfig":{"description":"Security scanner settings (Spec 039)","properties":{"auto_baseline_scan":{"description":"AutoBaselineScan is the kill-switch for the AUTOMATIC, informational\nPass-1 baseline scan: the free in-process TPA scan mcpproxy runs for every\nnewly admitted server (any trust mode) and, once per installation, over\npre-existing servers that have never been scanned.\n\nInformational ONLY: the resulting verdict populates the security badge and\nthe scan summary, and NEVER gates quarantine or approval. The\ntrust_mode:\"scan\" admission gate is a separate path and is unaffected by\nthis flag.\n\nDefault (nil) is ENABLED. Set to false to suppress every automatic scan\n(manual scans keep working). Env override: MCPPROXY_AUTO_BASELINE_SCAN,\nwhich wins over this field on every path.","type":"boolean"},"deep_scan":{"$ref":"#/components/schemas/config.DeepScanConfig"},"integrity_check_interval":{"type":"string"},"integrity_check_on_restart":{"type":"boolean"},"runtime_read_only":{"type":"boolean"},"runtime_tmpfs_size":{"type":"string"},"scan_timeout_default":{"type":"string"},"scanner_disable_no_new_privileges":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.DisableNoNewPrivileges\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.IsDisableNoNewPrivileges. Cleared after migration.\n\nScannerDisableNoNewPrivileges, when true, omits the\n` + "`" + `--security-opt no-new-privileges` + "`" + ` flag from scanner container runs.\n\nBackground: snap-installed Docker on Ubuntu confines dockerd under the\n` + "`" + `snap.docker.dockerd` + "`" + ` AppArmor profile. When runc tries to transition\nthe container into the inner ` + "`" + `docker-default` + "`" + ` profile to exec the\nentrypoint, AppArmor refuses the transition because NO_NEW_PRIVS\nforbids privilege/profile changes on exec — the result is EPERM\n(\"operation not permitted\") and every scanner fails immediately.\n\nSet this to true ONLY on hosts hitting that incompatibility. Scanner\ncontainers still run with read-only rootfs, tmpfs /tmp, no-network by\ndefault, and read-only source mounts, so the marginal isolation loss\nis small. The preferred fix remains replacing snap docker with a\ndistro-packaged docker.","type":"boolean"},"scanner_fetch_package_source":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.FetchPackageSource\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.EffectiveFetchPackageSource. Cleared after migration.\n\nScannerFetchPackageSource controls whether the scanner fetches the\nPUBLISHED source of package-runner servers (npx/uvx) — without executing\nit — when no local source is available (no Docker container, no local\npackage cache, no working_dir). This is the primary quarantine/scan\ntarget: a quarantined-on-add server is never run locally, so without this\nthe scan degrades to tool-definitions-only (no real source-level\nanalysis). See MCP-2206.\n\nFetching uses ` + "`" + `npm pack --ignore-scripts` + "`" + ` (npm) and ` + "`" + `uv pip download` + "`" + ` /\n` + "`" + `pip download` + "`" + ` with ` + "`" + `--only-binary=:all:` + "`" + ` (Python), which only download +\nunpack archives and NEVER run install, build, or setup.py — a scanner must\nnot execute the untrusted code it is scanning. The Python\n` + "`" + `--only-binary=:all:` + "`" + ` flag is required because downloading an sdist would\ninvoke its build backend (setup.py); packages with no wheel fall back to\ntool-definitions-only instead. Extraction is hardened against path\ntraversal and decompression bombs.\n\nDefault (nil) is ENABLED. Set to false on air-gapped deployments to\nforbid the scanner's network egress; such servers then fall back to the\ntool-definitions-only scan with no regression.","type":"boolean"},"scanner_registry_url":{"type":"string"},"tpa_bundle_path":{"description":"TPABundlePath is the filesystem path to the tpa-db scanner-bundle.json\nthe offline TPA scanner runs (spec 086 FR-019: the signature-DB location\nMUST be configuration-driven, not hardcoded). Empty (the default) runs the\ncorpus embedded in this build.\n\nEnv override: MCPPROXY_TPA_BUNDLE_PATH. Hot-reloadable — the path is\nre-read on every config.reloaded event via\nscanner.Service.ApplySecurityConfig, so a corpus refresh needs no restart.\nA configured bundle that fails to read/parse/version-check/compile is\nREFUSED and the previously active corpus stays live (fail-closed, never\nfail-empty); the reason is logged and surfaced in the security overview's\nsignature_bundle.load_error.","type":"string"}},"type":"object"},"config.SensitiveDataDetectionConfig":{"description":"Sensitive data detection settings (Spec 026)","properties":{"categories":{"additionalProperties":{"type":"boolean"},"description":"Enable/disable specific detection categories","type":"object"},"custom_patterns":{"description":"User-defined detection patterns","items":{"$ref":"#/components/schemas/config.CustomPattern"},"type":"array","uniqueItems":false},"enabled":{"description":"Enable sensitive data detection (default: true)","type":"boolean"},"entropy_threshold":{"description":"Shannon entropy threshold for high-entropy detection (default: 4.5)","type":"number"},"max_payload_size_kb":{"description":"Max size to scan before truncating (default: 1024)","type":"integer"},"scan_requests":{"description":"Scan tool call arguments (default: true)","type":"boolean"},"scan_responses":{"description":"Scan tool responses (default: true)","type":"boolean"},"sensitive_keywords":{"description":"Keywords to flag","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ServerConfig":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve tool\nchanges/additions (disabling per-server rug-pull protection). Supersedes\nskip_quarantine. MCP-2930 only ACCEPTS, persists, and migrates this flag — it\nis NOT yet consulted at runtime; auto-approval is still governed by\nSkipQuarantine until the trust-baseline behavior change (MCP-2931) migrates the\nruntime consumers onto it.\nTri-state pointer (mirrors QuarantineEnabled): nil = unset (inherit/migrate\nfrom legacy skip_quarantine), explicit true/false = honored as-is so an\nexplicit auto_approve_tool_changes:false overrides a legacy skip_quarantine:true.\nRead via IsAutoApproveToolChanges().","type":"boolean"},"command":{"type":"string"},"created":{"type":"string"},"disabled_tools":{"description":"Denylist: these tools are hidden; mutually exclusive with enabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"enabled":{"type":"boolean"},"enabled_tools":{"description":"Allowlist: only these tools are exposed; mutually exclusive with disabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts overrides whether this server's advertised MCP prompts are\naggregated into mcpproxy's prompts/list. nil (default) inherits the\ndefault-aggregate behavior (included if the server advertises\nCapabilities.Prompts); false excludes it regardless of capability.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"description":"For HTTP servers","type":"object"},"health_check_interval":{"description":"Per-server discovery \u0026 health-check overrides (spec 074). Same *Duration\ntri-state as the global keys: nil = inherit the global value (or default),\npointer to 0s = disabled for this server, positive = that interval.\nHealthCheckInterval is fully wired into the per-server health loop;\nToolDiscoveryInterval is accepted/validated and round-trips for\nforward-compat, but the periodic index sweep is governed by the global\ncadence in this iteration (see spec 074 plan §C).","type":"string"},"init_timeout":{"description":"InitTimeout overrides the global init_timeout for this server's MCP\n` + "`" + `initialize` + "`" + ` handshake deadline (MCP-3322 / GH #760). *Duration tri-state:\nnil = inherit the global value (or 30s default), positive = that deadline.\nResolved by Config.ResolveInitTimeout; validated to {0} ∪ [1s, 30m]. Raise\nthis for upstreams that do legitimate first-run warmup (e.g. caching many\nchannels/users) before responding to ` + "`" + `initialize` + "`" + `.","type":"string"},"isolation":{"$ref":"#/components/schemas/config.IsolationConfig"},"launcher_wait_timeout":{"description":"LauncherWaitTimeout caps how long mcpproxy will wait for a locally-launched\nHTTP/SSE upstream's URL to become reachable after Spawn(). Only consulted\nwhen the server is configured with both Command and an HTTP/SSE URL — i.e.,\nmcpproxy starts the process AND connects via network. Stdio servers ignore\nthis field. Zero or unset → 30s default.","type":"string"},"max_concurrent_requests":{"description":"Per-server concurrency overrides — scope (c) of FR-020 (spec 093, #955).\nTri-state per setting, exactly like HealthCheckInterval: absent = inherit\nthe per-server default set (server_concurrency_defaults), explicit 0 =\ndisable that setting for this server (0 max = no per-server limiter at\nall; 0 queue_size = no pending capacity, shed immediately at the cap),\npositive = override. The global aggregate limiter is never inherited from\nhere — it applies on top, so effective concurrency is min(per-server,\nglobal). Resolved by Config.ResolveServerConcurrency.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/config.OAuthConfig"},"protocol":{"description":"stdio, http, sse, streamable-http, auto","type":"string"},"quarantined":{"description":"Security quarantine status","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets a disconnected server","type":"boolean"},"shared":{"description":"Server edition: shared with all users","type":"boolean"},"skip_quarantine":{"description":"SkipQuarantine is DEPRECATED (MCP-2930): use AutoApproveToolChanges instead.\nKept for back-compat parsing; on config load a legacy skip_quarantine:true is\nmigrated to auto_approve_tool_changes:true only when the new field is unset\n(see normalizeServerQuarantineFlags).","type":"boolean"},"source_registry_id":{"description":"SourceRegistryID records which registry this server was added from (empty\nfor manually-configured servers). MCP-866: surfaced in the approval /\nquarantine view so a reviewer can see a server's origin.","type":"string"},"source_registry_provenance":{"description":"SourceRegistryProvenance records the source registry's provenance at add\ntime (RegistryProvenanceOfficial / RegistryProvenanceCustom). It is purely\ninformational (MCP-1072) — surfaced so a reviewer can see a server's origin\n— and no longer gates quarantine or skip_quarantine.","type":"string"},"tool_discovery_interval":{"type":"string"},"toon_output":{"description":"ToonOutput overrides the global toon_output mode for this server's\ntools (spec 084, FR-001). Plain string, not a pointer: \"\"/absent =\ninherit the global value; \"off\"|\"adaptive\"|\"always\" = override (\"off\"\nis the explicit force-off). Resolved by Config.ResolveToonOutput.","type":"string"},"trust_mode":{"description":"TrustMode is the per-server trust tier: auto|scan|manual. Supersedes\nauto_approve_tool_changes (spec 086). An empty value is derived from the\nlegacy fields at load via normalizeServerQuarantineFlags; the single\nresolution point is EffectiveTrustMode(), which treats an empty or\nunrecognized value as manual (secure by default). Read via\nEffectiveTrustMode(), never the raw string.","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"working_dir":{"description":"Working directory for stdio servers","type":"string"}},"type":"object"},"config.TLSConfig":{"description":"TLS configuration","properties":{"certs_dir":{"description":"Directory for certificates","type":"string"},"enabled":{"description":"Enable HTTPS","type":"boolean"},"hsts":{"description":"Enable HTTP Strict Transport Security","type":"boolean"},"require_client_cert":{"description":"Enable mTLS","type":"boolean"}},"type":"object"},"config.TelemetryConfig":{"description":"Telemetry settings (Spec 036)","properties":{"anonymous_id":{"description":"Auto-generated UUIDv4","type":"string"},"anonymous_id_created_at":{"description":"Spec 042 (Tier 2) additions — all default-zero, all backwards-compatible.","type":"string"},"enabled":{"description":"Default: true (opt-out)","type":"boolean"},"endpoint":{"description":"Override for testing","type":"string"},"last_reported_version":{"description":"Upgrade funnel","type":"string"},"last_startup_outcome":{"description":"success|port_conflict|db_locked|...","type":"string"},"notice_shown":{"description":"First-run notice flag","type":"boolean"}},"type":"object"},"config.TokenizerConfig":{"description":"Tokenizer configuration for token counting","properties":{"default_model":{"description":"Default model for tokenization (e.g., \"gpt-4\")","type":"string"},"enabled":{"description":"Enable token counting","type":"boolean"},"encoding":{"description":"Default encoding (e.g., \"cl100k_base\")","type":"string"}},"type":"object"},"config.TracingExporterConfig":{"description":"Tracing gates the OpenTelemetry OTLP trace exporter (MCP-32). Disabled by\ndefault.","properties":{"enabled":{"description":"Enabled turns on OTLP trace export for tool calls and upstream hops.","type":"boolean"},"endpoint":{"description":"Endpoint is the collector address as host:port (no scheme), e.g.\n\"localhost:4318\" for http or \"localhost:4317\" for grpc.","type":"string"},"protocol":{"description":"Protocol selects the OTLP transport: \"http\" or \"grpc\".","type":"string"},"sample_rate":{"description":"SampleRate is the head-based trace sampling ratio in [0,1]. Default 0.1.\nOmit the key for the 0.1 default; set it to 0 to sample nothing.","type":"number"}},"type":"object"},"config.UpdateCheckConfig":{"description":"Update-check settings (Spec 079 FR-012): config-file control of the\nbackground upgrade-awareness checker (internal/updatecheck). nil =\nenabled on the stable channel (existing default behavior). The existing\nenvironment switches keep working and WIN over these keys (FR-014):\nMCPPROXY_DISABLE_AUTO_UPDATE=true force-disables even when\nenabled=true, and MCPPROXY_ALLOW_PRERELEASE_UPDATES=true force-selects\nthe rc channel even when channel=stable.","properties":{"channel":{"description":"Channel selects which releases are offered as updates: \"stable\"\n(default; prereleases never offered) or \"rc\" (prereleases included).\nEmpty resolves to stable. Validated in ValidateDetailed.\n\nNOTE: for a RELEASED build the running binary's own version is\nauthoritative and overrides this field — a stable build is never\noffered an RC (even with channel=rc), and an RC build always tracks the\nrc channel. This field only takes effect on dev/unstamped builds. See\ninternal/updatecheck.Checker.IncludePrereleases.","type":"string"},"enabled":{"description":"Enabled gates all update checking. Tri-state: nil/absent = enabled\n(default true, matching pre-079 behavior). When false, no network\ncheck is performed and no upgrade nudge appears on any surface\n(FR-015) — /api/v1/info omits the update object entirely.","type":"boolean"}},"type":"object"},"configimport.FailedServer":{"properties":{"details":{"type":"string"},"error":{"type":"string"},"name":{"type":"string"}},"type":"object"},"configimport.ImportSummary":{"properties":{"failed":{"type":"integer"},"imported":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"configimport.SkippedServer":{"properties":{"name":{"type":"string"},"reason":{"description":"\"already_exists\", \"filtered_out\", \"invalid_name\"","type":"string"}},"type":"object"},"connect.ConnectResult":{"description":"The full result; its action mirrors the top-level one","properties":{"action":{"description":"\"created\", \"updated\", \"already_exists\", \"removed\", \"not_found\"","type":"string"},"backup_path":{"type":"string"},"client":{"type":"string"},"config_path":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.APIResponse":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ActivityDetailResponse":{"properties":{"activity":{"$ref":"#/components/schemas/contracts.ActivityRecord"}},"type":"object"},"contracts.ActivityListResponse":{"properties":{"activities":{"items":{"$ref":"#/components/schemas/contracts.ActivityRecord"},"type":"array","uniqueItems":false},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.ActivityRecord":{"properties":{"arguments":{"description":"Tool call arguments","type":"object"},"detection_types":{"description":"List of detection types found","items":{"type":"string"},"type":"array","uniqueItems":false},"duration_ms":{"description":"Execution duration in milliseconds","type":"integer"},"error_message":{"description":"Error details if status is \"error\"","type":"string"},"has_sensitive_data":{"description":"Sensitive data detection fields (Spec 026)","type":"boolean"},"id":{"description":"Unique identifier (ULID format)","type":"string"},"max_severity":{"description":"Highest severity level detected (critical, high, medium, low)","type":"string"},"metadata":{"description":"Additional context-specific data","type":"object"},"parent_id":{"description":"Correlation id of the parent call (the code_execution whose sandbox issued this sub-call)","type":"string"},"request_bytes":{"description":"Byte sizes measured pre-truncation, mirroring storage.ActivityRecord\n(Spec 069 A1). They are the only cost signal a bodies-off export carries:\nwith payloads suppressed there is no text left to measure, so a consumer\naccounting for a record it cannot read has nothing else to go on. They are\nbyte LENGTHS, not token counts — the basis for an explicit estimate, never\na measured figure (spec 103, contracts/replay-input.md).\n\nZero means UNKNOWN, not free: legacy records predate the measurement and\ncode-execution sub-calls record both as zero. Hence omitempty — an absent\nkey tells a consumer to fall to exclusion accounting, whereas a present\nzero would read as a costless call and silently understate the workload.","type":"integer"},"request_id":{"description":"HTTP request ID for correlation","type":"string"},"response":{"description":"Tool response (potentially truncated)","type":"string"},"response_bytes":{"description":"Raw upstream response size in bytes before truncation","type":"integer"},"response_truncated":{"description":"True if response was truncated","type":"boolean"},"server_name":{"description":"Name of upstream MCP server","type":"string"},"session_id":{"description":"MCP transport session ID (regenerated on every reconnect)","type":"string"},"source":{"$ref":"#/components/schemas/contracts.ActivitySource"},"status":{"description":"Result status: \"success\", \"error\", \"blocked\", \"rejected\"","type":"string"},"timestamp":{"description":"When activity occurred","type":"string"},"tool_name":{"description":"Name of tool called","type":"string"},"type":{"$ref":"#/components/schemas/contracts.ActivityType"},"work_session_id":{"description":"Spec 082: one client, one project, across reconnects","type":"string"}},"type":"object"},"contracts.ActivitySource":{"description":"How activity was triggered: \"mcp\", \"cli\", \"api\"","type":"string","x-enum-varnames":["ActivitySourceMCP","ActivitySourceCLI","ActivitySourceAPI"]},"contracts.ActivitySummaryResponse":{"properties":{"blocked_count":{"description":"Count of blocked activities","type":"integer"},"call_count":{"description":"CallCount is how many of those records are CALLS THE USER MADE, as\ndefined once in storage.CountsAsCall and shared with the usage aggregate\nbehind the Usage tab (audit finding F1, #1046). TotalCount answers \"how\nmany rows does the Activity Log have\"; CallCount answers \"how many calls\nwere there\". They are different questions — quarantine auto-approvals,\nsystem start, security scans and management chatter are events, not calls\n— and printing either one under the other's label is how the same instance\ncame to report 51 calls on one screen and 19 on another.","type":"integer"},"call_error_count":{"description":"CallErrorCount is the failures within CallCount, so an error RATE computed\nfrom this response has one denominator. It is not ErrorCount: a policy\nblock is a failed call but carries status \"blocked\", and a shed call is an\nerror in neither sense because it never ran.","type":"integer"},"end_time":{"description":"End of the period (RFC3339)","type":"string"},"error_count":{"description":"Count of error activities","type":"integer"},"other_count":{"description":"OtherCount is every record whose status is outside the four-value\nvocabulary above, so that\n\n\tsuccess + error + blocked + rejected + other == total\n\nholds by construction. The status field is a CLOSED vocabulary for tool\ncalls, but the activity log is wider than tool calls: a quarantine change\nstores its ACTION there (\"approved\", \"auto_approved\"), a policy decision\nstores its DECISION (\"allow\"). Those rows were counted in the total and in\nnone of the four buckets, so the Activity Log's own status tiles summed to\nless than the denominator printed beside them — 15+4+0+0 under a \"42\"\n(audit finding F2, #1046). The residual now has a name and a tile.","type":"integer"},"period":{"description":"Time period (1h, 24h, 7d, 30d)","type":"string"},"rejected_count":{"description":"RejectedCount is the number of calls shed by a concurrency limiter before\nthey reached an upstream (spec 093). Counted separately from errors: it is\nproxy backpressure, not an upstream fault, and it is the signal an\noperator right-sizes max_concurrent_requests against.","type":"integer"},"start_time":{"description":"Start of the period (RFC3339)","type":"string"},"success_count":{"description":"Count of successful activities","type":"integer"},"top_servers":{"description":"Top servers by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopServer"},"type":"array","uniqueItems":false},"top_tools":{"description":"Top tools by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopTool"},"type":"array","uniqueItems":false},"total_count":{"description":"Total activity count","type":"integer"}},"type":"object"},"contracts.ActivityTopServer":{"properties":{"count":{"description":"Activity count","type":"integer"},"name":{"description":"Server name","type":"string"}},"type":"object"},"contracts.ActivityTopTool":{"properties":{"count":{"description":"Activity count","type":"integer"},"server":{"description":"Server name","type":"string"},"tool":{"description":"Tool name","type":"string"}},"type":"object"},"contracts.ActivityType":{"description":"Type of activity","type":"string","x-enum-varnames":["ActivityTypeToolCall","ActivityTypePolicyDecision","ActivityTypeQuarantineChange","ActivityTypeServerChange"]},"contracts.AddFromRegistryRequest":{"properties":{"enabled":{"description":"defaults to true when nil","type":"boolean"},"env":{"additionalProperties":{"type":"string"},"description":"overrides + required-input values","type":"object"},"name":{"description":"optional name override","type":"string"}},"type":"object"},"contracts.AddRegistrySourceRequest":{"properties":{"id":{"description":"derived from the host when empty","type":"string"},"name":{"description":"defaults to the id","type":"string"},"protocol":{"description":"defaults to modelcontextprotocol/registry","type":"string"},"url":{"description":"required https registry URL","type":"string"}},"type":"object"},"contracts.ConfigApplyResult":{"properties":{"applied_immediately":{"type":"boolean"},"changed_fields":{"items":{"type":"string"},"type":"array","uniqueItems":false},"requires_restart":{"type":"boolean"},"restart_reason":{"type":"string"},"success":{"type":"boolean"},"validation_errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DCRStatus":{"properties":{"attempted":{"type":"boolean"},"error":{"type":"string"},"status_code":{"type":"integer"},"success":{"type":"boolean"}},"type":"object"},"contracts.DeepScanDescriptor":{"description":"DeepScan reports the opt-in \"deep scan\" layer status (Spec 077 US3),\nSEPARATELY from the baseline verdict above. Always emitted on a computed\nsummary — when deep scan is off (the default) it reports enabled=false\nplus any enabled-but-skipped Docker scanners. It never influences Status.","properties":{"available":{"type":"boolean"},"enabled":{"type":"boolean"},"ran":{"type":"boolean"},"scanners_failed":{"items":{"$ref":"#/components/schemas/contracts.DeepScanScannerFailure"},"type":"array","uniqueItems":false},"skipped_scanners":{"description":"SkippedScanners lists Docker scanners the user enabled that are skipped\nbecause security.deep_scan.enabled is false (informational).","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DeepScanScannerFailure":{"properties":{"id":{"type":"string"},"reason":{"type":"string"}},"type":"object"},"contracts.DeprecatedConfigWarning":{"properties":{"field":{"type":"string"},"message":{"type":"string"},"replacement":{"type":"string"}},"type":"object"},"contracts.Diagnostic":{"description":"Spec 044 — structured diagnostic error and stable error code. Both\nare populated when the server is in a failed state and the error\nhas been classified by internal/diagnostics. Healthy servers omit\nthese fields.","properties":{"cause":{"type":"string"},"code":{"type":"string"},"detected_at":{"type":"string"},"docs_url":{"type":"string"},"fix_steps":{"items":{"$ref":"#/components/schemas/contracts.DiagnosticFixStep"},"type":"array","uniqueItems":false},"severity":{"type":"string"},"user_message":{"type":"string"}},"type":"object"},"contracts.DiagnosticFixStep":{"properties":{"command":{"type":"string"},"destructive":{"type":"boolean"},"fixer_key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"url":{"type":"string"}},"type":"object"},"contracts.Diagnostics":{"properties":{"deprecated_configs":{"description":"Deprecated config fields found","items":{"$ref":"#/components/schemas/contracts.DeprecatedConfigWarning"},"type":"array","uniqueItems":false},"docker_status":{"$ref":"#/components/schemas/contracts.DockerStatus"},"missing_secrets":{"description":"Renamed to avoid conflict","items":{"$ref":"#/components/schemas/contracts.MissingSecretInfo"},"type":"array","uniqueItems":false},"oauth_issues":{"description":"OAuth parameter mismatches","items":{"$ref":"#/components/schemas/contracts.OAuthIssue"},"type":"array","uniqueItems":false},"oauth_required":{"items":{"$ref":"#/components/schemas/contracts.OAuthRequirement"},"type":"array","uniqueItems":false},"runtime_warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false},"timestamp":{"type":"string"},"total_issues":{"type":"integer"},"upstream_errors":{"items":{"$ref":"#/components/schemas/contracts.UpstreamError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DockerStatus":{"properties":{"available":{"type":"boolean"},"error":{"type":"string"},"version":{"type":"string"}},"type":"object"},"contracts.EditRegistrySourceRequest":{"properties":{"name":{"description":"new display name","type":"string"},"servers_url":{"description":"explicit servers-collection URL","type":"string"},"url":{"description":"new base/servers https URL","type":"string"}},"type":"object"},"contracts.ErrorResponse":{"properties":{"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.FindingCounts":{"properties":{"dangerous":{"description":"Tool poisoning, active prompt injection","type":"integer"},"info":{"description":"Low-severity CVEs, informational","type":"integer"},"total":{"type":"integer"},"warning":{"description":"Rug pull, supply chain CVEs with exploits","type":"integer"}},"type":"object"},"contracts.GetConfigResponse":{"properties":{"config":{"description":"The configuration object","type":"object"},"config_path":{"description":"Path to config file","type":"string"}},"type":"object"},"contracts.GetRegistriesResponse":{"properties":{"registries":{"items":{"$ref":"#/components/schemas/contracts.Registry"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerLogsResponse":{"properties":{"count":{"type":"integer"},"logs":{"items":{"$ref":"#/components/schemas/contracts.LogEntry"},"type":"array","uniqueItems":false},"server_name":{"type":"string"}},"type":"object"},"contracts.GetServerToolCallsResponse":{"properties":{"server_name":{"type":"string"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerToolsResponse":{"properties":{"count":{"type":"integer"},"server_name":{"type":"string"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GetServersResponse":{"properties":{"servers":{"items":{"$ref":"#/components/schemas/contracts.Server"},"type":"array","uniqueItems":false},"stats":{"$ref":"#/components/schemas/contracts.ServerStats"}},"type":"object"},"contracts.GetSessionDetailResponse":{"properties":{"session":{"$ref":"#/components/schemas/contracts.MCPSession"}},"type":"object"},"contracts.GetSessionsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"sessions":{"items":{"$ref":"#/components/schemas/contracts.MCPSession"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetToolCallDetailResponse":{"properties":{"tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"}},"type":"object"},"contracts.GetToolCallsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GlobalToolsResponse":{"properties":{"failed_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"partial":{"type":"boolean"},"stats":{"$ref":"#/components/schemas/contracts.GlobalToolsStats"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GlobalToolsStats":{"properties":{"disabled":{"type":"integer"},"enabled":{"type":"integer"},"pending_approval":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.HealthStatus":{"description":"Unified health status calculated by the backend","properties":{"action":{"description":"Action is the suggested fix action: \"login\", \"restart\", \"enable\", \"approve\", \"view_logs\", \"set_secret\", \"configure\", \"edit_url\", or \"\" (none)","type":"string"},"admin_state":{"description":"AdminState indicates the admin state: \"enabled\", \"disabled\", or \"quarantined\"","type":"string"},"detail":{"description":"Detail is an optional longer explanation of the status","type":"string"},"level":{"description":"Level indicates the health level: \"healthy\", \"degraded\", or \"unhealthy\"","type":"string"},"summary":{"description":"Summary is a human-readable status message (e.g., \"Connected (5 tools)\")","type":"string"}},"type":"object"},"contracts.InfoEndpoints":{"description":"Available API endpoints","properties":{"http":{"description":"HTTP endpoint address (e.g., \"127.0.0.1:8080\")","type":"string"},"socket":{"description":"Unix socket path (empty if disabled)","type":"string"}},"type":"object"},"contracts.InfoResponse":{"properties":{"endpoints":{"$ref":"#/components/schemas/contracts.InfoEndpoints"},"launched_by":{"description":"LaunchedBy is the durable launch provenance of the running core (Spec\n092 FR-001a): \"tray\" when a tray spawned it, \"installer\" when the macOS\nPKG postinstall did, \"\" when user-launched or unknown. Always present\n(possibly empty) so a tray can distinguish \"old core, not mine\" from\n\"old core I may supersede\".","type":"string"},"listen_addr":{"description":"Listen address (e.g., \"127.0.0.1:8080\")","type":"string"},"pid":{"description":"PID is the operating-system process id of the running core (Spec 092\nFR-002). A tray that merely ATTACHED to a core holds no Process handle\nfor it, so without this there is no mechanism at all to stop a stale\ncore — the consent action would have nothing to act on and could only\nprint instructions. Paired with LaunchedBy it is what lets a newer tray\nsupersede a core an older tray started.","type":"integer"},"update":{"$ref":"#/components/schemas/contracts.UpdateInfo"},"update_policy":{"$ref":"#/components/schemas/contracts.UpdatePolicy"},"version":{"description":"Current MCPProxy version","type":"string"},"web_ui_url":{"description":"URL to access the web control panel","type":"string"}},"type":"object"},"contracts.IsolationConfig":{"properties":{"cpu_limit":{"type":"string"},"enabled":{"description":"Enabled is the EFFECTIVE isolation state for this server: whether its\nprocess is actually CONFINED, after the global setting, the per-server\noverride, the structural gates and the host's capabilities. It is NOT the\nraw per-server override — read EnabledOverride for that (GH #1142).\n\nREAD-ONLY. The write surfaces reject an ` + "`" + `enabled` + "`" + ` key precisely because\nit is derived: echoing it back would convert \"inherits the global\nsetting\" into a permanent explicit override. Write EnabledOverride.\n\nIt stays a non-pointer bool that is always present on the wire: the macOS\ntray decodes it as a non-optional Swift Bool, so omitting or nulling the\nkey would fail Codable for the whole server payload. Older clients that\nread this field now simply get a true answer.","type":"boolean"},"enabled_override":{"description":"EnabledOverride is the RAW per-server ` + "`" + `isolation.enabled` + "`" + ` override, as\npersisted. Absent means \"inherit the global setting\" — which is a\ndistinct state from an explicit false, and the distinction the reporting\nbug used to destroy.","type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"memory_limit":{"type":"string"},"mode_override":{"description":"ModeOverride is the RAW per-server ` + "`" + `isolation.mode` + "`" + ` override\n(\"docker\" | \"sandbox\" | \"none\"). Absent means \"inherit\".","type":"string"},"network_mode":{"type":"string"},"timeout":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.IsolationDefaults":{"description":"IsolationDefaults exposes the resolved baseline values that\nwould apply when no per-server override is set. Populated on\nlist/get responses; never consumed on PATCH requests.","properties":{"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"network_mode":{"type":"string"},"runtime_type":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.IsolationEffective":{"description":"IsolationEffective exposes the resolved isolation state (and the rule\nthat decided it) so clients can distinguish \"inherits global\" from an\nexplicit per-server choice. Read-only; never consumed on PATCH.","properties":{"global_mode":{"description":"GlobalMode is what \"inherit\" resolves to right now.","type":"string"},"inherited":{"description":"Inherited is true when the server sets neither ` + "`" + `isolation.enabled` + "`" + ` nor\n` + "`" + `isolation.mode` + "`" + `, so its state tracks the global setting.","type":"boolean"},"isolated":{"description":"Isolated reports whether the process is actually CONFINED. It is NOT\nsimply Mode != \"none\": \"sandbox\" on a host that cannot enforce Landlock\n(any non-Linux OS, or a kernel without the LSM) runs the server\nunconfined, and Source then says \"sandbox-unavailable\" (GH #1142).","type":"boolean"},"mode":{"description":"Mode is the effective isolation mode: \"docker\" | \"sandbox\" | \"none\" —\nexactly what the spawn path branches on.","type":"string"},"source":{"description":"Source names the deciding rule: \"global\", \"server-mode\",\n\"server-opt-out\", \"server-opt-in-ignored\", \"not-stdio\",\n\"already-docker\", \"sandbox-unavailable\" or \"unsupported-mode\".\nTreat an unrecognized value as \"global\".","type":"string"}},"type":"object"},"contracts.LogEntry":{"properties":{"fields":{"type":"object"},"level":{"type":"string"},"message":{"type":"string"},"server":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.MCPSession":{"properties":{"client_name":{"type":"string"},"client_version":{"type":"string"},"end_time":{"type":"string"},"experimental":{"items":{"type":"string"},"type":"array","uniqueItems":false},"has_roots":{"description":"MCP Client Capabilities","type":"boolean"},"has_sampling":{"type":"boolean"},"id":{"type":"string"},"last_activity":{"type":"string"},"start_time":{"type":"string"},"status":{"type":"string"},"tool_call_count":{"type":"integer"},"total_tokens":{"type":"integer"},"work_session_id":{"type":"string"},"workspace_name":{"description":"Workspace / work session (Spec 082). WorkspaceName is the project's\nbasename — the full local path is never exposed. WorkSessionID groups the\nreconnects that make up one stretch of user work.","type":"string"}},"type":"object"},"contracts.MetadataStatus":{"properties":{"authorization_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"error":{"type":"string"},"found":{"type":"boolean"},"url_checked":{"type":"string"}},"type":"object"},"contracts.MissingSecretInfo":{"properties":{"secret_name":{"type":"string"},"used_by":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.NPMPackageInfo":{"properties":{"exists":{"type":"boolean"},"install_cmd":{"type":"string"}},"type":"object"},"contracts.OAuthConfig":{"properties":{"auth_url":{"type":"string"},"client_id":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_port":{"type":"integer"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false},"token_expires_at":{"description":"When the OAuth token expires","type":"string"},"token_url":{"type":"string"},"token_valid":{"description":"Whether token is currently valid","type":"boolean"}},"type":"object"},"contracts.OAuthErrorDetails":{"description":"Structured discovery/failure details","properties":{"authorization_server_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"dcr_status":{"$ref":"#/components/schemas/contracts.DCRStatus"},"protected_resource_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"server_url":{"type":"string"}},"type":"object"},"contracts.OAuthFlowError":{"properties":{"correlation_id":{"description":"Flow tracking ID for log correlation","type":"string"},"debug_hint":{"description":"CLI command for log lookup","type":"string"},"details":{"$ref":"#/components/schemas/contracts.OAuthErrorDetails"},"error_code":{"description":"Machine-readable error code (e.g., OAUTH_NO_METADATA)","type":"string"},"error_type":{"description":"Category of OAuth runtime failure","type":"string"},"message":{"description":"Human-readable error description","type":"string"},"request_id":{"description":"HTTP request ID (from PR #237)","type":"string"},"server_name":{"description":"Server that failed OAuth","type":"string"},"success":{"description":"Always false","type":"boolean"},"suggestion":{"description":"Actionable remediation hint","type":"string"}},"type":"object"},"contracts.OAuthIssue":{"properties":{"documentation_url":{"type":"string"},"error":{"type":"string"},"issue":{"type":"string"},"missing_params":{"items":{"type":"string"},"type":"array","uniqueItems":false},"resolution":{"type":"string"},"server_name":{"type":"string"}},"type":"object"},"contracts.OAuthRequirement":{"properties":{"expires_at":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"state":{"type":"string"}},"type":"object"},"contracts.OAuthStartResponse":{"properties":{"auth_url":{"description":"Authorization URL (always included for manual use)","type":"string"},"browser_error":{"description":"Error message if browser launch failed","type":"string"},"browser_opened":{"description":"Whether browser launch succeeded","type":"boolean"},"correlation_id":{"description":"UUID for tracking this flow","type":"string"},"message":{"description":"Human-readable status message","type":"string"},"server_name":{"description":"Name of the server being authenticated","type":"string"},"success":{"description":"Always true for successful start","type":"boolean"}},"type":"object"},"contracts.PreflightPolicy":{"properties":{"exclude_destructive":{"type":"boolean"},"exclude_open_world":{"type":"boolean"},"read_only_only":{"type":"boolean"}},"type":"object"},"contracts.PreflightReason":{"type":"string","x-enum-varnames":["PreflightReasonServerInitializing","PreflightReasonServerUnhealthy","PreflightReasonServerDisabled","PreflightReasonServerQuarantined","PreflightReasonToolPendingApproval","PreflightReasonToolChanged","PreflightReasonToolBlockedByUser","PreflightReasonOAuthRequired","PreflightReasonHashMismatch","PreflightReasonServerNotInScope","PreflightReasonToolDeniedByConfig","PreflightReasonMissingAnnotation","PreflightReasonPolicyFiltered","PreflightReasonNotFound","PreflightReasonServerNotConfigured"]},"contracts.PreflightRequest":{"properties":{"policy":{"$ref":"#/components/schemas/contracts.PreflightPolicy"},"profile":{"description":"Profile evaluates under a named profile's server scope. Unknown: 400.","type":"string"},"tools":{"description":"Tools is 1..100 entries BEFORE dedup; duplicates are collapsed, and\nduplicate ids carrying different pins are a validation error.","items":{"$ref":"#/components/schemas/contracts.PreflightToolRef"},"type":"array","uniqueItems":false},"wait_ms":{"description":"WaitMS polls local state for up to this many milliseconds (cap 10000)\nwhile every failure is retryable-class.","type":"integer"}},"type":"object"},"contracts.PreflightResponse":{"properties":{"checked_at":{"type":"string"},"tools":{"description":"Tools are ordered by first occurrence of each unique id in the request.","items":{"$ref":"#/components/schemas/contracts.PreflightToolResult"},"type":"array","uniqueItems":false},"verdict":{"$ref":"#/components/schemas/contracts.PreflightVerdict"},"waited_ms":{"description":"WaitedMS is present when wait_ms was requested (0 when the wait\nsemaphore was exhausted and the request resolved immediately).","type":"integer"}},"type":"object"},"contracts.PreflightStatus":{"type":"string","x-enum-varnames":["PreflightStatusReady","PreflightStatusUnavailable"]},"contracts.PreflightToolRef":{"properties":{"id":{"description":"ID is a canonical \"\u003cserver\u003e:\u003ctool\u003e\" id. A malformed id is answered with a\nper-ID not_found carrying a format hint, never a request-level error.","type":"string"},"pin_hash":{"description":"PinHash is \"sha256/v{N}:{hex}\" — the schema version is embedded so a\nproxy-side hash-algorithm bump is distinguishable from upstream drift.","type":"string"}},"type":"object"},"contracts.PreflightToolResult":{"properties":{"action":{"type":"string"},"detail":{"type":"string"},"did_you_mean":{"description":"DidYouMean carries up to 3 nearest caller-visible ids on not_found. It\nnever crosses a scope boundary and never names a quarantined server's\ntools.","items":{"type":"string"},"type":"array","uniqueItems":false},"hash":{"description":"Hash is the tool's current pin (\"sha256/v{N}:{hex}\") — operator tier,\nready results only. Never disclosed to an agent token.","type":"string"},"id":{"type":"string"},"reason":{"$ref":"#/components/schemas/contracts.PreflightReason"},"remediation":{"type":"string"},"retryable":{"type":"boolean"},"status":{"$ref":"#/components/schemas/contracts.PreflightStatus"}},"type":"object"},"contracts.PreflightVerdict":{"type":"string","x-enum-varnames":["PreflightVerdictReady","PreflightVerdictDegradedRetryable","PreflightVerdictBlocked","PreflightVerdictUnknownIDs"]},"contracts.QuarantineStats":{"description":"Tool quarantine metrics for this server","properties":{"blocked_count":{"description":"Number of disabled (blocked) tools","type":"integer"},"changed_count":{"description":"Number of tools whose description/schema changed since approval","type":"integer"},"pending_count":{"description":"Number of newly discovered tools awaiting approval","type":"integer"}},"type":"object"},"contracts.RefreshRegistryResponse":{"properties":{"cleared":{"description":"number of cached entries dropped","type":"integer"},"registry_id":{"type":"string"}},"type":"object"},"contracts.Registry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag (MCP-866): \"official/trusted\" for built-in\ndefaults, \"custom/unverified\" for user-added registries.","type":"string"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"trusted":{"description":"Trusted indicates whether this is an official, shipped-by-default\nregistry. Trust is derived from membership in the default set, never\nfrom self-assertion in config.","type":"boolean"},"url":{"type":"string"}},"type":"object"},"contracts.RegistryCacheInfo":{"properties":{"age_seconds":{"type":"number"},"stale":{"type":"boolean"}},"type":"object"},"contracts.RegistryUnavailable":{"properties":{"reason":{"type":"string"}},"type":"object"},"contracts.ReplayToolCallRequest":{"properties":{"arguments":{"description":"Modified arguments for replay","type":"object"}},"type":"object"},"contracts.ReplayToolCallResponse":{"properties":{"error":{"description":"Error if replay failed","type":"string"},"new_call_id":{"description":"ID of the newly created call","type":"string"},"new_tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"replayed_from":{"description":"Original call ID","type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.RepositoryInfo":{"description":"Detected package info","properties":{"npm":{"$ref":"#/components/schemas/contracts.NPMPackageInfo"}},"type":"object"},"contracts.RepositoryServer":{"properties":{"connect_url":{"description":"Alternative connection URL","type":"string"},"created_at":{"type":"string"},"description":{"type":"string"},"id":{"type":"string"},"install_cmd":{"description":"Installation command","type":"string"},"name":{"type":"string"},"registry":{"description":"Which registry this came from","type":"string"},"repository_info":{"$ref":"#/components/schemas/contracts.RepositoryInfo"},"source_code_url":{"description":"Source repository URL","type":"string"},"updated_at":{"type":"string"},"url":{"description":"MCP endpoint for remote servers only","type":"string"}},"type":"object"},"contracts.SearchRegistryServersResponse":{"properties":{"cache":{"$ref":"#/components/schemas/contracts.RegistryCacheInfo"},"query":{"type":"string"},"registry_id":{"type":"string"},"servers":{"items":{"$ref":"#/components/schemas/contracts.RepositoryServer"},"type":"array","uniqueItems":false},"tag":{"type":"string"},"total":{"type":"integer"},"unavailable":{"$ref":"#/components/schemas/contracts.RegistryUnavailable"}},"type":"object"},"contracts.SearchResult":{"properties":{"matches":{"type":"integer"},"score":{"type":"number"},"snippet":{"type":"string"},"tool":{"$ref":"#/components/schemas/contracts.Tool"}},"type":"object"},"contracts.SearchToolsResponse":{"properties":{"query":{"type":"string"},"results":{"items":{"$ref":"#/components/schemas/contracts.SearchResult"},"type":"array","uniqueItems":false},"took":{"type":"string"},"total":{"type":"integer"}},"type":"object"},"contracts.SecurityScanSummary":{"description":"Latest security scan results summary","properties":{"deep_scan":{"$ref":"#/components/schemas/contracts.DeepScanDescriptor"},"finding_counts":{"$ref":"#/components/schemas/contracts.FindingCounts"},"last_scan_at":{"type":"string"},"risk_score":{"description":"0-100","type":"integer"},"scanners_failed":{"type":"integer"},"scanners_run":{"description":"Scanner coverage for the primary (baseline) scan pass — informational only.\nSpec 077 US3 (FR-008/FR-014): Status is derived SOLELY from the\ndeterministic baseline findings; a failed Docker deep scanner no longer\ndowngrades a clean verdict. That failure is surfaced via DeepScan instead.","type":"integer"},"scanners_total":{"type":"integer"},"status":{"description":"\"clean\", \"warnings\", \"dangerous\", \"failed\", \"not_scanned\", \"scanning\"","type":"string"}},"type":"object"},"contracts.Server":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"authenticated":{"description":"OAuth authentication status","type":"boolean"},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges mirrors config.ServerConfig.AutoApproveToolChanges\n(MCP-2930): the per-server intent to auto-approve new/changed tools past\nthe trust baseline. Tri-state *bool — nil means \"never set\" (omitted from\nthe payload), so the Web UI toggle (MCP-2932) can distinguish unset from\nan explicit false. Read-only on the GET path; PATCH/POST accept it via\nAddServerRequest.","type":"boolean"},"command":{"type":"string"},"connected":{"type":"boolean"},"connected_at":{"type":"string"},"connecting":{"type":"boolean"},"created":{"type":"string"},"diagnostic":{"$ref":"#/components/schemas/contracts.Diagnostic"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"error_code":{"type":"string"},"expose_prompts":{"description":"ExposePrompts mirrors config.ServerConfig.ExposePrompts (F9): the per-server\nprompt-aggregation override. Tri-state *bool — nil/omitted means \"inherit\ndefault aggregation\". Surfaced on GET so a caller that PATCHed the override\ncan read it back; PATCH/POST accept it via AddServerRequest.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"health":{"$ref":"#/components/schemas/contracts.HealthStatus"},"id":{"type":"string"},"init_timeout":{"description":"InitTimeout mirrors config.ServerConfig.InitTimeout (MCP-3322 / GH #760):\nthe per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override. Serialized as\na duration string (e.g. \"120s\"); nil/omitted means \"inherit the global\ndefault\". Surfaced on the GET path so clients can read back a configured\noverride; PATCH/POST accept it via AddServerRequest.","type":"string"},"isolation":{"$ref":"#/components/schemas/contracts.IsolationConfig"},"isolation_defaults":{"$ref":"#/components/schemas/contracts.IsolationDefaults"},"isolation_effective":{"$ref":"#/components/schemas/contracts.IsolationEffective"},"last_error":{"type":"string"},"last_reconnect_at":{"type":"string"},"last_retry_time":{"type":"string"},"max_concurrent_requests":{"description":"Spec 093 (GH #955) — per-server concurrency overrides, scope (c) of\nFR-020. Each setting is tri-state: nil (omitted) means \"inherit\nserver_concurrency_defaults\", 0 disables that setting for this server,\npositive overrides it. Surfaced on the GET path so a caller can read back\nwhat it set; PATCH/POST accept them via AddServerRequest. The effective\nconcurrency for a server is additionally bounded by the global aggregate\nlimiter, which is NOT an inheritance source for these fields.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/contracts.OAuthConfig"},"oauth_status":{"description":"OAuth status: \"authenticated\", \"expired\", \"error\", \"none\"","type":"string"},"protocol":{"type":"string"},"quarantine":{"$ref":"#/components/schemas/contracts.QuarantineStats"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_count":{"type":"integer"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets this disconnected server","type":"boolean"},"retry_count":{"type":"integer"},"retry_stopped":{"description":"RetryStopped reports that automatic reconnection has been given up for\ngood because the failure is deterministic and unrecoverable — a missing\nbinary, an image without the interpreter, an unparseable config (GH\n#1145). It is NOT ordinary exponential backoff, which keeps retrying;\nnothing will happen until the user fixes the config or restarts the\nserver. RetryStoppedCode is the stable MCPX_* code that proved it and\nRetryStoppedReason the catalog message explaining how to fix it. All three\nare omitted for servers that are healthy or still retrying.","type":"boolean"},"retry_stopped_code":{"type":"string"},"retry_stopped_reason":{"type":"string"},"security_scan":{"$ref":"#/components/schemas/contracts.SecurityScanSummary"},"should_retry":{"type":"boolean"},"source_registry_id":{"description":"MCP-901 — registry provenance of an upstream that was added from a\nregistry. SourceRegistryID names the source registry (empty for\nmanually-configured servers); SourceRegistryProvenance is the trust tag\nrecorded at add time (\"official/trusted\" or \"custom/unverified\"). Both\nare projected from config.ServerConfig so the approval/quarantine view\ncan render an \"added from \u003cregistry\u003e · unverified\" origin badge. Optional\nand omitted when empty — clients that pre-date this treat them as absent.","type":"string"},"source_registry_provenance":{"type":"string"},"status":{"type":"string"},"token_expires_at":{"description":"When the OAuth token expires (ISO 8601)","type":"string"},"tool_count":{"type":"integer"},"tool_list_token_size":{"description":"Token size for this server's tools","type":"integer"},"trust_mode":{"description":"TrustMode mirrors config.ServerConfig.TrustMode (spec 086): the per-server\ntrust tier (\"auto\"/\"scan\"/\"manual\"). Surfaced on the GET path so clients can\nread back the persisted mode; PATCH/POST accept it via AddServerRequest.\nOmitted when empty (server predates the field / relies on legacy flags).","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"user_logged_out":{"description":"True if user explicitly logged out (prevents auto-reconnection)","type":"boolean"},"working_dir":{"type":"string"}},"type":"object"},"contracts.ServerActionResponse":{"properties":{"action":{"type":"string"},"async":{"type":"boolean"},"server":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ServerStats":{"properties":{"connected_servers":{"type":"integer"},"docker_containers":{"type":"integer"},"quarantined_servers":{"type":"integer"},"token_metrics":{"$ref":"#/components/schemas/contracts.ServerTokenMetrics"},"total_servers":{"type":"integer"},"total_tools":{"type":"integer"}},"type":"object"},"contracts.ServerTokenMetrics":{"properties":{"average_query_result_size":{"description":"Typical retrieve_tools output (tokens)","type":"integer"},"per_server_tool_list_sizes":{"additionalProperties":{"type":"integer"},"description":"Token size per server","type":"object"},"saved_tokens":{"description":"Difference","type":"integer"},"saved_tokens_percentage":{"description":"Percentage saved","type":"number"},"total_server_tool_list_size":{"description":"All upstream tools combined (tokens)","type":"integer"}},"type":"object"},"contracts.SuccessResponse":{"properties":{"data":{"type":"object"},"success":{"type":"boolean"}},"type":"object"},"contracts.TokenMetrics":{"description":"Token usage metrics (nil for older records)","properties":{"encoding":{"description":"Encoding used (e.g., cl100k_base)","type":"string"},"estimated_cost":{"description":"Optional cost estimate","type":"number"},"input_tokens":{"description":"Tokens in the request","type":"integer"},"model":{"description":"Model used for tokenization","type":"string"},"output_tokens":{"description":"Tokens in the response","type":"integer"},"total_tokens":{"description":"Total tokens (input + output)","type":"integer"},"truncated_tokens":{"description":"Tokens removed by truncation","type":"integer"},"was_truncated":{"description":"Whether response was truncated","type":"boolean"}},"type":"object"},"contracts.Tool":{"properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"approval_status":{"type":"string"},"config_denied":{"description":"ConfigDenied is true when the tool is denied by the server's static\nenabled_tools / disabled_tools config. The user cannot override this toggle.","type":"boolean"},"description":{"type":"string"},"disabled":{"description":"Disabled mirrors ToolApprovalRecord.Disabled so per-tool enable state is\navailable without a second round-trip to the approvals endpoint. Absent\nin the JSON when false (default) to keep responses compact.","type":"boolean"},"hash":{"description":"Hash is the tool's current stored hash rendered in the preflight pin\nformat \"sha256/v{N}:{hex}\" (Spec 098 FR-011), where N is the approval\nrecord's HashSchemaVersion. It is the authoring surface for\n` + "`" + `POST /api/v1/preflight` + "`" + ` pins and ` + "`" + `mcpproxy tools preflight --pin` + "`" + `:\ncopy the value straight into a pin.\n\nDisclosure is OPERATOR TIER ONLY — same rule as the preflight per-tool\nresult. The field is omitted for agent-token callers and for tools with\nno stored hash (no approval record yet, or a record written before\nhashes existed).","type":"string"},"held_reason":{"description":"HeldReason, HeldVerdict and HeldSignals mirror the same-named fields on\nstorage.ToolApprovalRecord: the offline-scan evidence that made\ntrust_mode: scan hold this tool for review (spec 086 FR-018). HeldSignals\nnames the matched deterministic check ids, e.g.\n\"tpa.TPA-2026-0001.hidden_instruction\", so a reviewer can see WHY the tool\nis held. All three are omitted for tools that are not held by the scan gate\n(including every record written before the field existed).","type":"string"},"held_signals":{"items":{"type":"string"},"type":"array","uniqueItems":false},"held_verdict":{"type":"string"},"last_used":{"type":"string"},"name":{"type":"string"},"schema":{"type":"object"},"server_name":{"type":"string"},"usage":{"type":"integer"}},"type":"object"},"contracts.ToolAnnotation":{"description":"Tool behavior hints snapshot","properties":{"destructiveHint":{"type":"boolean"},"idempotentHint":{"type":"boolean"},"openWorldHint":{"type":"boolean"},"readOnlyHint":{"type":"boolean"},"title":{"type":"string"}},"type":"object"},"contracts.ToolCallRecord":{"description":"The new tool call record","properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"arguments":{"description":"Tool arguments","type":"object"},"arguments_truncated":{"description":"ArgumentsTruncated marks Arguments as a placeholder rather than the\narguments the tool was called with. Replaying such a record without\nsupplying arguments explicitly is refused.","type":"boolean"},"config_path":{"description":"Active config file path","type":"string"},"duration":{"description":"Duration in nanoseconds","type":"integer"},"error":{"description":"Error message (failure only)","type":"string"},"execution_type":{"description":"\"direct\" or \"code_execution\"","type":"string"},"id":{"description":"Unique identifier","type":"string"},"mcp_client_name":{"description":"MCP client name from InitializeRequest","type":"string"},"mcp_client_version":{"description":"MCP client version","type":"string"},"mcp_session_id":{"description":"MCP session identifier","type":"string"},"metrics":{"$ref":"#/components/schemas/contracts.TokenMetrics"},"parent_call_id":{"description":"Links nested calls to parent code_execution","type":"string"},"request_id":{"description":"Request correlation ID","type":"string"},"response":{"description":"Tool response (success only)","type":"object"},"response_bytes":{"description":"Marshalled response size before truncation","type":"integer"},"response_truncated":{"description":"ResponseTruncated and ResponseBytes describe a STORAGE-side cut (#1176):\nthe caller received the response whole, and only the persisted copy was\nshortened to tool_call_max_response_size. When ResponseTruncated is true\nthe Response object carries {truncated, original_bytes, preview, note}\ninstead of the upstream result, and ResponseBytes is its size before the\ncut.","type":"boolean"},"server_id":{"description":"Server identity hash","type":"string"},"server_name":{"description":"Human-readable server name","type":"string"},"timestamp":{"description":"When the call was made","type":"string"},"tool_name":{"description":"Tool name (without server prefix)","type":"string"}},"type":"object"},"contracts.UpdateInfo":{"description":"Update information (if available)","properties":{"available":{"description":"Whether an update is available","type":"boolean"},"behind_summary":{"description":"Spec 079 FR-002 — how far behind the running build is. All four are\nadditive (FR-021) and absent when the delta could not be resolved, in\nwhich case every surface renders its pre-delta wording.","type":"string"},"check_error":{"description":"Error message if update check failed","type":"string"},"checked_at":{"description":"When the update check was performed","type":"string"},"install_channel":{"description":"Detected install channel (homebrew, dmg, deb, rpm, docker, go-install, windows-installer, tarball, unknown) — Spec 079 FR-008","type":"string"},"is_prerelease":{"description":"Whether the latest version is a prerelease","type":"boolean"},"latest_version":{"description":"Latest version available (e.g., \"v1.2.3\")","type":"string"},"nudges_suppressed":{"description":"UI surfaces must stay quiet (CI / non-interactive context); machine-readable fields still report the facts — Spec 079 FR-019","type":"boolean"},"release_url":{"description":"URL to the release page","type":"string"},"releases_behind":{"description":"Releases on the offered channel between the running and offered versions","type":"integer"},"releases_behind_saturated":{"description":"ReleasesBehind is a lower bound: the running build predates the scanned release window","type":"boolean"},"update_command":{"description":"One-line update command for the channel; only set when an update is available and the channel has one — Spec 079 FR-009","type":"string"},"weeks_behind":{"description":"Whole weeks between the two releases' publish dates; 0 is a real value, absent means unknown","type":"integer"}},"type":"object"},"contracts.UpdatePolicy":{"description":"UpdatePolicy is the effective, hot-reloadable update policy (Spec 092\nFR-015). Always present: the ` + "`" + `update` + "`" + ` object above is omitted both when\nupdate checking is disabled AND when no check has produced a result\nyet, so its absence cannot tell a client whether it is allowed to run\nits own (e.g. Sparkle feed) check. This field states the answer.","properties":{"channel":{"description":"Channel is the tracked release channel: \"stable\" or \"rc\".","type":"string"},"enabled":{"description":"Enabled is the effective automatic-check kill switch: update_check.enabled\nwith MCPPROXY_DISABLE_AUTO_UPDATE=true winning over it. A user-initiated\n\"Check for Updates\" stays available regardless.","type":"boolean"},"nudges_suppressed":{"description":"NudgesSuppressed asks UI surfaces to stay quiet (CI / non-interactive)\nwhile machine-readable fields keep reporting the facts.","type":"boolean"}},"type":"object"},"contracts.UpstreamError":{"properties":{"error_message":{"type":"string"},"server_name":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.UsageAggregateResponse":{"properties":{"freshness_ms":{"description":"age of the underlying snapshot in ms","type":"integer"},"generated_at":{"type":"string"},"other":{"$ref":"#/components/schemas/contracts.UsageOtherBucket"},"timeline":{"items":{"$ref":"#/components/schemas/contracts.UsageTimeBucket"},"type":"array","uniqueItems":false},"token_source":{"description":"\"bytes\" (size-based proxy, FR-006)","type":"string"},"tokens_saved":{"description":"echoed from ServerTokenMetrics (FR-007)","type":"integer"},"tokens_saved_percentage":{"type":"number"},"tools":{"items":{"$ref":"#/components/schemas/contracts.UsageToolStat"},"type":"array","uniqueItems":false},"total_calls":{"description":"TotalCalls and TotalErrors are the headline counts for the window: the sum\nof the timeline this same response carries, so the tiles and the histogram\nunder them cannot disagree. They are NOT the sum of Tools — that list is\nlifetime-cumulative, upstream-only and truncated to top-N, and summing it\nclient-side is what made the Usage tab print a third number for the same\n24 hours (audit finding F1, #1046). The population is\nstorage.CountsAsCall, shared with ActivitySummaryResponse.CallCount.\n\nTwo bounds on how exactly this matches the Activity Log's own count.\nBoth are bounded and disclosed, unlike the population mismatch they\nreplace, which was unbounded and silent:\n\n  - Window granularity is the timeline's: whole hour buckets, so the span\n    is the requested window rounded up to a bucket edge.\n  - This response is served from a snapshot behind a short read cache\n    (observability.usage_cache_ttl, 5s by default) so the endpoint never\n    scans the activity log per request, while the summary endpoint counts\n    live. Calls that land inside that window appear on the Activity Log\n    first. FreshnessMs and GeneratedAt say how old the figures are, and\n    the Usage tab prints it (\"Updated 3s ago\").","type":"integer"},"total_errors":{"type":"integer"},"window":{"type":"string"}},"type":"object"},"contracts.UsageOtherBucket":{"description":"present only when the list was truncated to top-N","properties":{"calls":{"type":"integer"},"tools_folded":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageTimeBucket":{"properties":{"calls":{"type":"integer"},"errors":{"type":"integer"},"start":{"type":"string"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageToolStat":{"properties":{"avg_req_bytes":{"description":"null when no sized request calls","type":"integer"},"avg_resp_bytes":{"description":"null when sized_calls == 0 (only legacy 0-byte calls)","type":"integer"},"blocked":{"type":"integer"},"calls":{"type":"integer"},"error_rate":{"type":"number"},"errors":{"type":"integer"},"last_used":{"type":"string"},"p50_exceeds":{"type":"boolean"},"p50_ms":{"description":"P50Ms and P95Ms are read off a fixed latency histogram, so they are BUCKET\nBOUNDS, not measured durations: the true percentile is at or below the\nvalue, and a client must render it as a bound (\"≤ 5 ms\"). P50Exceeds /\nP95Exceeds flip that reading for the unbounded overflow bucket, where the\nvalue is the last bound and the truth is above it (\"\u003e 10 s\").","type":"integer"},"p95_exceeds":{"type":"boolean"},"p95_ms":{"type":"integer"},"rejected":{"description":"spec 093: shed by a concurrency limit; never executed, so excluded from calls/latency","type":"integer"},"server":{"type":"string"},"sized_calls":{"description":"calls with known response size (basis for avg_resp_bytes)","type":"integer"},"tool":{"type":"string"},"total_req_bytes":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.ValidateConfigResponse":{"properties":{"errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false},"valid":{"type":"boolean"}},"type":"object"},"contracts.ValidationError":{"properties":{"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"data":{"properties":{"data":{"$ref":"#/components/schemas/contracts.InfoResponse"}},"type":"object"},"httpapi.AddServerRequest":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve\nnew/changed tools past the trust baseline (MCP-2930). Tri-state *bool:\na nil pointer means \"leave unchanged\" on PATCH; a present value\n(including false) is applied. Mirrors config.ServerConfig's *bool\nsemantics — do NOT collapse to a plain bool, or an omitted field would\nsilently reset a previously-set value.","type":"boolean"},"command":{"type":"string"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts is the per-server override for prompt aggregation (F9):\nwhether this server's advertised MCP prompts are merged into mcpproxy's\nprompts/list. Tri-state *bool mirroring config.ServerConfig.ExposePrompts —\na nil pointer means \"leave unchanged\" on PATCH (and \"inherit the default\naggregate behavior\" on create); a present value (including false) is applied.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"init_timeout":{"description":"InitTimeout is the per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override\n(MCP-3322 / GH #760), serialized as a duration string (e.g. \"120s\"). A nil\npointer means \"leave unchanged\" on PATCH; a present value is applied.\nMirrors config.ServerConfig.InitTimeout's *Duration tri-state.","type":"string"},"isolation":{"$ref":"#/components/schemas/httpapi.IsolationRequest"},"max_concurrent_requests":{"description":"MaxConcurrentRequests / QueueSize / QueueTimeout are the per-server\nconcurrency overrides (spec 093 / GH #955, FR-020 scope (c)). Each is\ntri-state: a nil pointer means \"leave unchanged\" on PATCH and \"inherit\nserver_concurrency_defaults\" on create; an explicit 0 disables that\nsetting for this server; a positive value overrides it. Do NOT collapse\nthem to plain values — an omitted field would then silently reset a\nconfigured limit.","type":"integer"},"name":{"type":"string"},"protocol":{"type":"string"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"type":"boolean"},"trust_mode":{"description":"TrustMode is the per-server trust tier (spec 086): \"auto\", \"scan\", or\n\"manual\". Empty means \"leave unchanged\" on PATCH (and inherit the migrated\ndefault on create). A non-empty value is applied to ServerConfig.TrustMode\nand resolved by EffectiveTrustMode (an unrecognized value fails closed to\nmanual). This is the REST seam for changing the trust tier via\nPOST/PATCH /api/v1/servers.","type":"string"},"url":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.CanonicalConfigPath":{"properties":{"description":{"description":"Brief description","type":"string"},"exists":{"description":"Whether the file exists","type":"boolean"},"format":{"description":"Format identifier (e.g., \"claude_desktop\")","type":"string"},"name":{"description":"Display name (e.g., \"Claude Desktop\")","type":"string"},"os":{"description":"Operating system (darwin, windows, linux)","type":"string"},"path":{"description":"Full path to the config file","type":"string"}},"type":"object"},"httpapi.CanonicalConfigPathsResponse":{"properties":{"os":{"description":"Current operating system","type":"string"},"paths":{"description":"List of canonical config paths","items":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPath"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ConnectConflictResponse":{"properties":{"action":{"description":"already_exists | precondition_failed","type":"string"},"data":{"$ref":"#/components/schemas/connect.ConnectResult"},"error":{"description":"Human-readable message","type":"string"},"success":{"description":"Always false","type":"boolean"}},"type":"object"},"httpapi.ConnectRequest":{"properties":{"force":{"description":"Overwrite existing entry","type":"boolean"},"precondition_token":{"description":"PreconditionToken is the opaque token from the preview this write was\nconfirmed against (Spec 091 FR-005). When present, the core rechecks it\nat write time and responds 409 with action \"precondition_failed\" —\nwriting nothing — if the config or the entry MCPProxy would write has\ndrifted since; the caller then re-previews instead of retrying. Absent\nmeans exactly the pre-091 behavior. A replace-classified flow sends this\nTOGETHER with force=true: the token, not the absence of force, is the\noverwrite safety.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.ImportFromPathRequest":{"properties":{"format":{"description":"Optional format hint","type":"string"},"path":{"description":"File path to import from","type":"string"},"rename":{"additionalProperties":{"type":"string"},"description":"Rename maps a server name → new name. Applied after parsing so the\ncaller can disambiguate cross-source name collisions (Spec 046 v2 —\ne.g. \"mcpproxy\" → \"mcpproxy_claude_code\"). Keys are matched against\neither the raw source name (OriginalName) or the sanitized name shown\nin the preview (Server.Name); these differ for names that need\nsanitizing (e.g. \"Figma Desktop\" → \"Figma_Desktop\"). Keys not present\nin the imported set are ignored.","type":"object"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportRequest":{"properties":{"content":{"description":"Raw JSON or TOML content","type":"string"},"format":{"description":"Optional format hint","type":"string"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportResponse":{"properties":{"failed":{"items":{"$ref":"#/components/schemas/configimport.FailedServer"},"type":"array","uniqueItems":false},"format":{"type":"string"},"format_name":{"type":"string"},"imported":{"items":{"$ref":"#/components/schemas/httpapi.ImportedServerResponse"},"type":"array","uniqueItems":false},"skipped":{"items":{"$ref":"#/components/schemas/configimport.SkippedServer"},"type":"array","uniqueItems":false},"summary":{"$ref":"#/components/schemas/configimport.ImportSummary"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportedServerResponse":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"command":{"type":"string"},"fields_skipped":{"items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"type":"string"},"original_name":{"type":"string"},"protocol":{"type":"string"},"source_format":{"type":"string"},"url":{"type":"string"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.IsolationRequest":{"description":"Isolation carries per-server Docker isolation overrides (enabled,\nmode_override, image, network_mode, extra_args, working_dir). A nil\npointer means \"do not touch isolation config\". A present object is\napplied field-by-field ON TOP of the persisted overrides, so omitting a\nfield leaves it alone; clear an individual override by sending it\nexplicitly (` + "`" + `\"enabled\": null` + "`" + `, ` + "`" + `\"image\": \"\"` + "`" + `).","properties":{"enabled":{"description":"Enabled exists ONLY to detect and reject an echoed-back read. It is the\neffective state on the read surface and is never writable; see validate().","type":"boolean"},"enabled_override":{"description":"EnabledOverride is the tri-state per-server override — the RAW value, the\nsame one reads return as ` + "`" + `enabled_override` + "`" + `. It has THREE meaningful wire\nstates, and collapsing them is what silently un-isolated servers\n(GH #1142):\n  - absent          → leave the persisted override untouched\n  - null            → clear the override, back to inheriting the global\n  - true / false    → set an explicit opt-in / opt-out","type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"mode_override":{"description":"ModeOverride sets ` + "`" + `isolation.mode` + "`" + ` (\"docker\" | \"sandbox\" | \"none\").\nnil leaves the persisted value alone; an empty string clears it. An\nunrecognized value is rejected with a 400 rather than persisted.","type":"string"},"network_mode":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.OnboardingMarkRequest":{"properties":{"connect_step_status":{"description":"ConnectStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value. The stored enum is wider (Spec 080\nFR-001): a \"skipped\" request for a previously untouched connect step\nis upgraded server-side to \"completed_external\" when the install\nshows positive evidence of an external connection (Spec 080 FR-002).\n\"completed_external\" is NOT accepted from clients — it must never be\npersisted without that server-verified evidence (edge case: \"never\nguess completed_external without positive evidence\").","type":"string"},"engaged":{"description":"Engaged marks the wizard as engaged (completed or explicitly skipped).\nOnce true, the wizard does not auto-show again.","type":"boolean"},"mark_shown":{"description":"MarkShown records the wizard's first display time if not already set.","type":"boolean"},"server_step_status":{"description":"ServerStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value.","type":"string"}},"type":"object"},"httpapi.SetActiveProfileRequest":{"properties":{"active_profile":{"type":"string"},"profile":{"type":"string"}},"type":"object"},"httpapi.UndoConnectRequest":{"properties":{"backup_name":{"description":"BackupName is the bare filename (filepath.Base) of the backup returned as\nbackup_path by the preceding connect — a name, never a path. Undo resolves\nthe full path server-side by joining it with the client's own config\ndirectory, so a client-supplied value can never contribute a directory\ncomponent (traversal is impossible by construction). Empty means the\nconnect created the file (no prior file existed), so undo removes it.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.UpdateFailureRequest":{"properties":{"stage":{"description":"Stage is the failure stage of the update session.","enum":["appcast","download","install","other"],"type":"string"}},"type":"object"},"management.BulkOperationResult":{"properties":{"errors":{"additionalProperties":{"type":"string"},"description":"Map of server name to error message","type":"object"},"failed":{"description":"Number of failed operations","type":"integer"},"successful":{"description":"Number of successful operations","type":"integer"},"total":{"description":"Total servers processed","type":"integer"}},"type":"object"},"observability.HealthResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"observability.HealthStatus":{"properties":{"error":{"type":"string"},"latency":{"type":"string"},"name":{"type":"string"},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"}},"type":"object"},"observability.ReadinessResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"ready\" or \"not_ready\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"secureenv.EnvConfig":{"description":"Environment configuration for secure variable filtering","properties":{"allowed_system_vars":{"items":{"type":"string"},"type":"array","uniqueItems":false},"custom_vars":{"additionalProperties":{"type":"string"},"type":"object"},"enhance_path":{"description":"Enable PATH enhancement for Launchd scenarios","type":"boolean"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned upstream servers (MCP-2769). It is OFF by\ndefault and deliberately kept out of the AllowedSystemVars default list:\nproxy URLs frequently carry credentials (http://user:pass@proxy), so\nforwarding them to every stdio upstream is a credential-leak risk. When\nenabled, values are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"inherit_system_safe":{"type":"boolean"}},"type":"object"},"telemetry.FeedbackContext":{"properties":{"arch":{"type":"string"},"connected_server_count":{"type":"integer"},"edition":{"type":"string"},"os":{"type":"string"},"routing_mode":{"type":"string"},"server_count":{"type":"integer"},"version":{"type":"string"}},"type":"object"},"telemetry.FeedbackRequest":{"properties":{"category":{"description":"bug, feature, other","type":"string"},"context":{"$ref":"#/components/schemas/telemetry.FeedbackContext"},"email":{"type":"string"},"message":{"type":"string"}},"type":"object"},"telemetry.FeedbackResponse":{"properties":{"error":{"type":"string"},"issue_url":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"description":"API key authentication via query parameter. Use ?apikey=your-key","in":"query","name":"apikey","type":"apiKey"}}},
+    "components": {"schemas":{"config.ConcurrencyDefaults":{"description":"ServerConcurrencyDefaults is scope (b) of FR-020: the blanket per-server\ndefault set inherited by every server that does not override a setting.\nAbsent (the default) = no per-server limiting unless a server configures\nit explicitly. File/API-configured only — no env scheme (FR-022).","properties":{"max_concurrent_requests":{"type":"integer"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"}},"type":"object"},"config.Config":{"properties":{"activity_cleanup_interval_min":{"description":"Background cleanup interval in minutes (default: 60)","type":"integer"},"activity_max_records":{"description":"Max records before pruning (default: 100000)","type":"integer"},"activity_max_response_size":{"description":"Response truncation limit in bytes (default: 65536)","type":"integer"},"activity_max_size_mb":{"description":"ActivityMaxSizeMB caps the total activity-log size in MB before the\noldest records are pruned. Omit the key for the 256MB default; set it to\n0 to disable the size cap.","type":"integer"},"activity_retention_days":{"description":"Activity logging settings (RFC-003)","type":"integer"},"aggregate_upstream_prompts":{"description":"AggregateUpstreamPrompts, when true, aggregates every connected upstream\nserver's advertised MCP prompts into mcpproxy's own prompts/list\n(exposed as \"\u003cserver\u003e__\u003cprompt\u003e\"). OFF by default: users are safe by\ndefault and opt in deliberately. EnablePrompts still governs the built-in\nprompts + the prompts capability; this flag gates ONLY the upstream\naggregation performed by RefreshPrompts. Hot-reloadable.","type":"boolean"},"allow_private_registry_fetch":{"description":"AllowPrivateRegistryFetch opts out of the registry SSRF guard (MCP-1076,\nCWE-918). By default (false) registry fetches refuse any host that is — or\nresolves to — a non-routable address (loopback, RFC1918/CGNAT private,\nlink-local incl. the 169.254.169.254 cloud-metadata endpoint), so a\nmalicious or typo'd registry source cannot turn the daemon into a\nrequest-forgery vector against internal services.\n\nThis opt-out is BLANKET (all-or-nothing): setting it true disables the\nguard for EVERY non-routable range at once — loopback, RFC1918/CGNAT\nprivate, link-local AND the 169.254.169.254 cloud-metadata endpoint. There\nis no way to allow only loopback; enabling it for a localhost dev registry\nalso re-opens the cloud-metadata SSRF vector. Set true ONLY when you\nintentionally run a trusted registry mirror on an internal/private address,\nideally on a host with no cloud-metadata exposure. The change takes effect\nonly on daemon (re)start or config reload.","type":"boolean"},"allow_server_add":{"type":"boolean"},"allow_server_remove":{"type":"boolean"},"api_key":{"description":"Security settings","type":"string"},"call_tool_timeout":{"type":"string"},"check_server_repo":{"description":"Repository detection settings","type":"boolean"},"code_execution_max_parallel":{"description":"Default concurrency for call_tools() batches (1-32, default: 8)","type":"integer"},"code_execution_max_tool_calls":{"description":"Max tool calls per execution (0 = unlimited, default: 0)","type":"integer"},"code_execution_pool_size":{"description":"JavaScript runtime pool size (default: 10)","type":"integer"},"code_execution_timeout_ms":{"description":"Timeout in milliseconds (default: 120000, max: 600000)","type":"integer"},"data_dir":{"type":"string"},"debug_search":{"type":"boolean"},"direct_tool_response_mode":{"description":"DirectToolResponseMode selects the serialization of the DIRECT\nenumeration surface (Spec 102). Valid values: \"\" (= full), \"full\"\n(default: today's schema-bearing entries), \"deferred\" (description +\ncompact signature, with a minimal permissive input schema; upstream\ninputSchema and outputSchema are stripped and recovered on demand via\ndescribe_tool).\n\nDeliberately NOT an extension of tool_response_mode: reusing that axis\nwould silently change /mcp/all output for every deployment already\nrunning compact, which FR-015 forbids. Serialization-only — it never\nchanges WHICH tools are listed, only how (FR-008). Hot-reloadable.","type":"string"},"disable_management":{"type":"boolean"},"docker_isolation":{"$ref":"#/components/schemas/config.DockerIsolationConfig"},"docker_recovery":{"$ref":"#/components/schemas/config.DockerRecoveryConfig"},"enable_code_execution":{"description":"Code execution settings","type":"boolean"},"enable_prompts":{"description":"Prompts settings","type":"boolean"},"enable_socket":{"description":"Enable Unix socket/named pipe for local IPC (default: true)","type":"boolean"},"enable_tray":{"description":"Deprecated: EnableTray is unused and has no runtime effect. Kept for backward compatibility.","type":"boolean"},"environment":{"$ref":"#/components/schemas/secureenv.EnvConfig"},"features":{"$ref":"#/components/schemas/config.FeatureFlags"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned stdio upstream servers (MCP-2769). OFF by\ndefault: proxy URLs commonly embed credentials (http://user:pass@proxy), so\nforwarding them to every upstream is a credential-leak risk. When enabled,\nvalues are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"health_check_interval":{"description":"Discovery \u0026 health-check cadence (spec 074, #608). Both are *Duration\ntri-state pointers: nil = inherit the built-in default; a pointer to 0s =\nthe loop is disabled; a positive value = that interval. Defaults live only\nin the resolvers (ResolveHealthCheckInterval / ResolveToolDiscoveryInterval)\nso an unset key behaves exactly as before this feature (SC-005). Validated\nin Validate(): health-check ∈ {0} ∪ [5s,1h]; tool-discovery ∈ {0} ∪ [30s,24h].","type":"string"},"http_idle_timeout":{"description":"HTTPIdleTimeout caps how long an idle keep-alive connection is kept open.\nUnset = 180s. \"0s\" removes the dedicated idle deadline, but net/http then\nfalls back to ReadTimeout — idle is fully unbounded only when\nhttp_read_timeout is also \"0s\". Requires a restart.","type":"string"},"http_read_timeout":{"description":"HTTPReadTimeout caps how long reading a whole request (headers + body)\nmay take. Unset = 120s; \"0s\" disables it. Requires a restart.","type":"string"},"http_write_timeout":{"description":"HTTPWriteTimeout caps how long producing a whole response may take on\nnon-streaming endpoints (REST, Web UI, health). Unset = 120s; \"0s\"\ndisables it globally. MCP and SSE /events routes are exempt by design.","type":"string"},"init_timeout":{"description":"InitTimeout is the global default deadline for an upstream's MCP\n` + "`" + `initialize` + "`" + ` handshake (MCP-3322 / GH #760). *Duration tri-state: nil =\ninherit the built-in 30s default; a positive value = that deadline. A\nper-server InitTimeout overrides this. Resolved by ResolveInitTimeout;\nvalidated to {0} ∪ [1s, 30m] in Validate(). Servers doing legitimate\nfirst-run warmup (cache/index build) before answering ` + "`" + `initialize` + "`" + ` can\nraise this so they are not killed mid-startup.","type":"string"},"instructions":{"description":"Instructions text returned in the MCP initialize response to guide AI agents.\nWhen empty, a built-in default is used that explains retrieve_tools workflow.","type":"string"},"intent_declaration":{"$ref":"#/components/schemas/config.IntentDeclarationConfig"},"listen":{"type":"string"},"logging":{"$ref":"#/components/schemas/config.LogConfig"},"max_concurrent_requests":{"description":"Concurrency limits (spec 093, GH #955). Scope (a) of FR-020: the GLOBAL\nAGGREGATE limiter — one proxy-wide cap on concurrently running upstream\ntool calls, with its own bounded wait queue. Tri-state pointers: absent =\nthe limiter does not exist (default, zero behavior change); an explicit 0\nmax also disables it; positive = that cap. This scope is NEVER a\nper-server inheritance source — per-server values come from\nServerConcurrencyDefaults / the per-server overrides — but a server's\neffective concurrency is bounded by BOTH its own limiter and this one.\nResolved by ResolveGlobalConcurrency; hot-reloadable; overridable via\nMCPPROXY_MAX_CONCURRENT_REQUESTS / _QUEUE_SIZE / _QUEUE_TIMEOUT (FR-022).","type":"integer"},"max_result_size_chars":{"description":"MaxResultSizeChars is advertised on every tool as\n` + "`" + `_meta.anthropic/maxResultSizeChars` + "`" + `; it raises Claude Code's\ninline-response ceiling from 50k to up to 500k chars. Omit the key for\nthe 500000 default; set it to 0 to disable the annotation.","type":"integer"},"mcpServers":{"items":{"$ref":"#/components/schemas/config.ServerConfig"},"type":"array","uniqueItems":false},"oauth_expiry_warning_hours":{"description":"Health status settings","type":"number"},"observability":{"$ref":"#/components/schemas/config.ObservabilityConfig"},"output_sanitisation":{"$ref":"#/components/schemas/config.OutputSanitisationConfig"},"output_validation":{"$ref":"#/components/schemas/config.OutputValidationConfig"},"profiles":{"description":"Profiles are optional named, server-scoped views exposed at /mcp/p/\u003cname\u003e\n(Spec 057). Absent/empty is fully supported — /mcp is unchanged and configs\nwithout this key serialize byte-identically (SC-004).","items":{"$ref":"#/components/schemas/config.ProfileConfig"},"type":"array","uniqueItems":false},"quarantine_enabled":{"description":"QuarantineEnabled controls whether quarantine is active. It gates two\nthings together:\n  1. Server-level auto-quarantine for newly added servers (issue #370).\n     When true, servers added via the upstream_servers MCP tool or the\n     REST API default to quarantined=true; when false, they default to\n     quarantined=false. Explicit per-request values always win.\n  2. Tool-level quarantine (Spec 032): per-tool SHA-256 approval of\n     tool descriptions/schemas.\nWhen nil (default), quarantine is enabled (secure by default). Set to\nexplicit false to opt out of both. Per-server SkipQuarantine still\napplies for the tool-level check on individual servers.","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"read_only_mode":{"type":"boolean"},"registries":{"description":"Registries configuration for MCP server discovery","items":{"$ref":"#/components/schemas/config.RegistryEntry"},"type":"array","uniqueItems":false},"registries_locked":{"description":"RegistriesLocked is an enterprise stub knob (MCP-866): when true, runtime\nadditions of custom registries (e.g. ` + "`" + `registry add-source` + "`" + `, the REST/MCP\nadd-source surface) are rejected so an administrator can pin the discovery\nsources. Built-in defaults are unaffected. Documented but otherwise inert\nbeyond the add-source rejection.","type":"boolean"},"require_mcp_auth":{"description":"Require authentication on /mcp endpoint (default: false)","type":"boolean"},"reveal_secret_headers":{"description":"RevealSecretHeaders, when true, disables the redaction of the\nsecret-bearing server fields — sensitive header values (Authorization,\nX-API-Key, Cookie, …), env-var secrets, and URL query credentials — in\nresponses from the ` + "`" + `upstream_servers` + "`" + ` MCP tool, the ` + "`" + `/api/v1/servers` + "`" + `\nREST API, and the SSE event stream. It also lets URL secrets echoed\ninto last_error / health.detail through unscrubbed.\n\nDefault false — sensitive values are surfaced masked as\n` + "`" + `••••\u003clast2\u003e (\u003cN\u003e chars)` + "`" + ` (error strings use ` + "`" + `***REDACTED***` + "`" + `) so an\nMCP agent cannot read Bearer tokens / API keys / URL secrets out of\nanother upstream's config (PR #425, issue #872). ${env:…}/${keyring:…}\nreferences are labels, not secrets, and pass through unchanged.\n\nThe Web UI / macOS tray edit forms work without seeing the real\nvalues: PATCH /api/v1/servers/{id} deep-merges (omitted keys are\npreserved, see ` + "`" + `headers_remove` + "`" + ` / ` + "`" + `env_remove` + "`" + ` for explicit\ndeletes), so clients compute a diff and only send the keys that\nactually changed. Redacted-but-unchanged values never round-trip\n— the backend keeps the real string. Set this to true if a\ndownstream tool genuinely needs raw values in the response.","type":"boolean"},"routing_mode":{"description":"Routing mode (Spec 031): how MCP tools are exposed to clients\nValid values: \"retrieve_tools\" (default), \"direct\", \"code_execution\"","type":"string"},"security":{"$ref":"#/components/schemas/config.SecurityConfig"},"sensitive_data_detection":{"$ref":"#/components/schemas/config.SensitiveDataDetectionConfig"},"server_concurrency_defaults":{"$ref":"#/components/schemas/config.ConcurrencyDefaults"},"telemetry":{"$ref":"#/components/schemas/config.TelemetryConfig"},"tls":{"$ref":"#/components/schemas/config.TLSConfig"},"tokenizer":{"$ref":"#/components/schemas/config.TokenizerConfig"},"tool_call_max_records_per_server":{"description":"Calls retained per server (default: 1000)","type":"integer"},"tool_call_max_response_size":{"description":"Bounds for the per-server tool-call history behind GET /api/v1/tool-calls\n(#1176). It is a recent-debugging window, not an audit log — the activity\nlog is the durable record — and it kept every upstream response whole,\nper server, forever. A non-positive value means \"use the default\", not\n\"disable\": this store must never be unbounded again, so there is\ndeliberately no off switch.","type":"integer"},"tool_discovery_interval":{"type":"string"},"tool_response_limit":{"type":"integer"},"tool_response_mode":{"description":"Tool response mode (Spec 085): how retrieve_tools serializes results.\nValid values: \"\" (= full), \"full\" (default: today's schema-bearing\nentries), \"compact\" (signature + first-sentence entries). Orthogonal to\nrouting_mode — routing_mode selects the tool SURFACE, this selects the\nSERIALIZATION within the retrieve_tools surface. Serialization-only: it\nnever affects the query, ranking, or result set. Hot-reloadable.","type":"string"},"tool_response_session_risk_warning":{"description":"ToolResponseSessionRiskWarning controls whether the prose ` + "`" + `warning` + "`" + ` field\nis included in the ` + "`" + `session_risk` + "`" + ` object returned by ` + "`" + `retrieve_tools` + "`" + `.\nThe structured fields (level, lethal_trifecta, has_open_world_tools, etc.)\nare always included. Default: false (quiet for LLM clients) — see issue #406.\nMost tools lack annotations, so the MCP-spec defaults treat them as fully\npermissive across all three risk axes, which makes the prose warning fire\non almost every call and wastes tokens.","type":"boolean"},"tools_limit":{"type":"integer"},"toon_min_savings_pct":{"description":"ToonMinSavingsPct is the minimum byte-savings percentage (validated\n1-90; 0/unset → 15) the complete TOON emission (marker + hint + body)\nmust achieve over the exact passthrough emission for adaptive mode to\nencode a block. Byte savings approximate token savings for the tabular\npayload class; the spec-083 profiler reports true token deltas.\nGlobal-only (no per-server override, FR-001).","type":"integer"},"toon_output":{"description":"ToonOutput selects the TOON encoding mode for call_tool_* result text\nblocks (spec 084): \"off\" (default — responses byte-identical to\npre-feature behavior), \"adaptive\" (encode only tabular-uniform payloads\nthat beat compact JSON by ToonMinSavingsPct), or \"always\"\n(benchmark/debug only — encodes every JSON-parseable block and can\nINCREASE token cost). Per-server override: ServerConfig.ToonOutput.\nResolved by ResolveToonOutput; hot-reloadable.","type":"string"},"top_k":{"description":"Deprecated: TopK is superseded by ToolsLimit and has no runtime effect. Kept for backward compatibility.","type":"integer"},"tray_endpoint":{"description":"Tray endpoint override (unix:// or npipe://)","type":"string"},"trusted_hosts":{"description":"TrustedHosts lists non-loopback Host header values accepted on loopback\nlisteners (GH #898). DNS-rebinding protection rejects requests whose Host\nheader is not a loopback address when mcpproxy listens on loopback; a\nreverse proxy (nginx → 127.0.0.1) forwarding the public domain in Host\ntrips it. Entries are hostnames, case-insensitive; an entry without a\nport matches any port, with a port it must match exactly; a leading dot\n(\".example.com\") is a subdomain wildcard. The single entry \"*\" disables\nHost and Origin validation entirely. The same list also validates the\nOrigin header when present (MCP spec DNS-rebinding defense). Empty\n(default) keeps full protection. Env override: MCPPROXY_TRUSTED_HOSTS\n(comma-separated).","items":{"type":"string"},"type":"array","uniqueItems":false},"trusted_proxies":{"description":"TrustedProxies lists the CIDRs or IP addresses whose X-Forwarded-For /\nX-Real-IP / X-Forwarded-Proto / X-Forwarded-Host headers are believed\n(Spec 107 FR-027). Empty (default) trusts nobody. Edition-neutral, live\n(hot-reloadable). Env override: MCPPROXY_TRUSTED_PROXIES (comma-separated).\nThe one reader is ForwardedHeaders; validation is validateTrustedProxies.","items":{"type":"string"},"type":"array","uniqueItems":false},"update_check":{"$ref":"#/components/schemas/config.UpdateCheckConfig"}},"type":"object"},"config.CustomPattern":{"properties":{"category":{"description":"Category (defaults to \"custom\")","type":"string"},"keywords":{"description":"Keywords to match (mutually exclusive with Regex)","items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"description":"Unique identifier for this pattern","type":"string"},"regex":{"description":"Regex pattern (mutually exclusive with Keywords)","type":"string"},"severity":{"description":"Risk level: critical, high, medium, low","type":"string"}},"type":"object"},"config.DeepScanConfig":{"description":"DeepScan is the opt-in \"deep scan\" layer (Spec 077 US3). It subsumes the\ndeprecated top-level scanner_fetch_package_source / scanner_disable_no_new_privileges\nkeys (migrated on load) and gates the heavy Docker-based scanners + source\nextraction. Disabled by default (FR-006): only the deterministic in-process\nbaseline scanner runs. A deep-scan failure NEVER changes the baseline verdict\n(FR-007/FR-008).","properties":{"disable_no_new_privileges":{"description":"DisableNoNewPrivileges, when true, omits the ` + "`" + `--security-opt\nno-new-privileges` + "`" + ` flag from scanner container runs (snap-docker/AppArmor\nescape hatch). Absorbs the deprecated top-level\nscanner_disable_no_new_privileges. Default false.","type":"boolean"},"enabled":{"description":"Enabled is the master opt-in for the heavy layer (FR-006). Default false.","type":"boolean"},"fetch_package_source":{"description":"FetchPackageSource controls whether the scanner fetches the PUBLISHED\nsource of package-runner servers (npx/uvx) — without executing it — when\nno local source is available. Absorbs the deprecated top-level\nscanner_fetch_package_source. Default (nil) is ENABLED within deep scan.","type":"boolean"},"scanners":{"description":"Scanners optionally restricts which deep scanners may run under the\numbrella (by scanner id). Empty ⇒ all enabled deep scanners are eligible.","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.DockerIsolationConfig":{"description":"Docker isolation settings","properties":{"cpu_limit":{"description":"CPU limit for containers","type":"string"},"default_images":{"additionalProperties":{"type":"string"},"description":"Map of runtime type to Docker image","type":"object"},"enable_cache_volume":{"description":"Mount shared cache volumes for faster restarts (default: true)","type":"boolean"},"enabled":{"description":"Global enable/disable for Docker isolation (legacy; superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments","items":{"type":"string"},"type":"array","uniqueItems":false},"log_driver":{"description":"Docker log driver (default: json-file)","type":"string"},"log_max_files":{"description":"Maximum number of log files (default: 3)","type":"string"},"log_max_size":{"description":"Maximum size of log files (default: 100m)","type":"string"},"memory_limit":{"description":"Memory limit for containers","type":"string"},"mode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"network_mode":{"description":"Docker network mode (default: bridge)","type":"string"},"registry":{"description":"Custom registry (defaults to docker.io)","type":"string"},"timeout":{"description":"Container startup timeout","type":"string"}},"type":"object"},"config.DockerRecoveryConfig":{"description":"Docker recovery settings","properties":{"enabled":{"description":"Enable Docker recovery monitoring (default: true)","type":"boolean"},"max_retries":{"description":"Maximum retry attempts (0 = unlimited)","type":"integer"},"notify_on_failure":{"description":"Show notification on recovery failure (default: true)","type":"boolean"},"notify_on_retry":{"description":"Show notification on each retry (default: false)","type":"boolean"},"notify_on_start":{"description":"Show notification when recovery starts (default: true)","type":"boolean"},"notify_on_success":{"description":"Show notification on successful recovery (default: true)","type":"boolean"},"persistent_state":{"description":"Save recovery state across restarts (default: true)","type":"boolean"}},"type":"object"},"config.FeatureFlags":{"description":"Deprecated: Features flags are unused and have no runtime effect. Kept for backward compatibility.","properties":{"enable_async_storage":{"type":"boolean"},"enable_caching":{"type":"boolean"},"enable_contract_tests":{"type":"boolean"},"enable_debug_logging":{"description":"Development features","type":"boolean"},"enable_docker_isolation":{"type":"boolean"},"enable_event_bus":{"type":"boolean"},"enable_health_checks":{"type":"boolean"},"enable_metrics":{"type":"boolean"},"enable_oauth":{"description":"Security features","type":"boolean"},"enable_observability":{"description":"Observability features","type":"boolean"},"enable_quarantine":{"type":"boolean"},"enable_runtime":{"description":"Runtime features","type":"boolean"},"enable_search":{"description":"Storage features","type":"boolean"},"enable_sse":{"type":"boolean"},"enable_tracing":{"type":"boolean"},"enable_tray":{"type":"boolean"},"enable_web_ui":{"description":"UI features","type":"boolean"}},"type":"object"},"config.IntentDeclarationConfig":{"description":"Intent declaration settings (Spec 018)","properties":{"strict_server_validation":{"description":"StrictServerValidation controls whether server annotation mismatches\ncause rejection (true) or just warnings (false).\nDefault: true (reject mismatches)","type":"boolean"}},"type":"object"},"config.IsolationConfig":{"description":"Per-server isolation settings","properties":{"enabled":{"description":"Enable Docker isolation for this server (nil = inherit global; legacy, superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments for this server","items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"description":"Custom Docker image (overrides default)","type":"string"},"log_driver":{"description":"Docker log driver override for this server","type":"string"},"log_max_files":{"description":"Maximum number of log files override","type":"string"},"log_max_size":{"description":"Maximum size of log files override","type":"string"},"mode":{"$ref":"#/components/schemas/config.IsolationMode"},"network_mode":{"description":"Custom network mode for this server","type":"string"},"working_dir":{"description":"Custom working directory in container","type":"string"}},"type":"object"},"config.IsolationMode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"config.LogConfig":{"description":"Logging configuration","properties":{"compress":{"type":"boolean"},"enable_console":{"type":"boolean"},"enable_file":{"type":"boolean"},"filename":{"type":"string"},"json_format":{"type":"boolean"},"level":{"type":"string"},"log_dir":{"description":"Custom log directory","type":"string"},"max_age":{"description":"days","type":"integer"},"max_backups":{"description":"number of backup files","type":"integer"},"max_size":{"description":"MB","type":"integer"}},"type":"object"},"config.MetricsExporterConfig":{"description":"Metrics gates the Prometheus /metrics scrape endpoint (MCP-32). Disabled\nby default — operators opt in for k8s/enterprise deployments.","properties":{"enabled":{"description":"Enabled exposes /metrics on the existing HTTP listener when true.","type":"boolean"}},"type":"object"},"config.OAuthConfig":{"description":"OAuth configuration (keep even when empty to signal OAuth requirement)","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"description":"Additional OAuth parameters (e.g., RFC 8707 resource)","type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_uri":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ObservabilityConfig":{"description":"Observability settings (Spec 069): usage aggregate cache/persistence cadence.","properties":{"metrics":{"$ref":"#/components/schemas/config.MetricsExporterConfig"},"tracing":{"$ref":"#/components/schemas/config.TracingExporterConfig"},"usage_cache_ttl":{"description":"UsageCacheTTL bounds the freshness of the usage endpoint's read cache for\nwide windows (FR-005). Default 5s.","type":"string"},"usage_persist_interval":{"description":"UsagePersistInterval is how often the actor-owned usage aggregate snapshot\nis flushed to storage. Default 30s.","type":"string"}},"type":"object"},"config.OutputSanitisationConfig":{"description":"Output sanitisation settings (Spec 054 Track B)","properties":{"max_redactions":{"description":"cap on redactions per response; default 100","type":"integer"},"response_action":{"description":"\"spotlight\" | \"redact\" | \"block\"; default \"spotlight\"","type":"string"},"spotlight_untrusted":{"description":"wrap untrusted output in spotlight markers; default true","type":"boolean"},"strip_classes":{"description":"classes to strip: ansi/c0c1/bidi/zero_width","items":{"type":"string"},"type":"array","uniqueItems":false},"strip_control_chars":{"description":"strip control-character classes; default false","type":"boolean"}},"type":"object"},"config.OutputValidationConfig":{"description":"Output-schema validation settings (Spec 056)","properties":{"max_bytes":{"description":"structured payload byte cap; default 5\u003c\u003c20","type":"integer"},"max_depth":{"description":"nesting depth cap; default 64","type":"integer"},"missing_structured_content":{"description":"\"allow\" | \"block\"; default \"allow\"","type":"string"},"mode":{"description":"\"off\" | \"warn\" | \"strict\"; default \"warn\"","type":"string"}},"type":"object"},"config.ProfileConfig":{"properties":{"name":{"description":"URL slug, validated","type":"string"},"servers":{"description":"references to mcpServers[].name","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.RegistryEntry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag for this registry (MCP-866):\nRegistryProvenanceOfficial for built-in defaults, RegistryProvenanceCustom\nfor user-added registries. It is authoritatively (re)computed by the\nregistries merge from whether the ID is a shipped default — a user cannot\nclaim \"official\" by writing it into their config.","type":"string"},"requires_key":{"description":"RequiresKey marks a registry that needs an API key to be queried. When\ntrue and no key is configured, the registry is skipped/marked unavailable\nrather than failing the whole search (FR-008).","type":"boolean"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"url":{"type":"string"}},"type":"object"},"config.SecurityConfig":{"description":"Security scanner settings (Spec 039)","properties":{"auto_baseline_scan":{"description":"AutoBaselineScan is the kill-switch for the AUTOMATIC, informational\nPass-1 baseline scan: the free in-process TPA scan mcpproxy runs for every\nnewly admitted server (any trust mode) and, once per installation, over\npre-existing servers that have never been scanned.\n\nInformational ONLY: the resulting verdict populates the security badge and\nthe scan summary, and NEVER gates quarantine or approval. The\ntrust_mode:\"scan\" admission gate is a separate path and is unaffected by\nthis flag.\n\nDefault (nil) is ENABLED. Set to false to suppress every automatic scan\n(manual scans keep working). Env override: MCPPROXY_AUTO_BASELINE_SCAN,\nwhich wins over this field on every path.","type":"boolean"},"deep_scan":{"$ref":"#/components/schemas/config.DeepScanConfig"},"integrity_check_interval":{"type":"string"},"integrity_check_on_restart":{"type":"boolean"},"runtime_read_only":{"type":"boolean"},"runtime_tmpfs_size":{"type":"string"},"scan_timeout_default":{"type":"string"},"scanner_disable_no_new_privileges":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.DisableNoNewPrivileges\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.IsDisableNoNewPrivileges. Cleared after migration.\n\nScannerDisableNoNewPrivileges, when true, omits the\n` + "`" + `--security-opt no-new-privileges` + "`" + ` flag from scanner container runs.\n\nBackground: snap-installed Docker on Ubuntu confines dockerd under the\n` + "`" + `snap.docker.dockerd` + "`" + ` AppArmor profile. When runc tries to transition\nthe container into the inner ` + "`" + `docker-default` + "`" + ` profile to exec the\nentrypoint, AppArmor refuses the transition because NO_NEW_PRIVS\nforbids privilege/profile changes on exec — the result is EPERM\n(\"operation not permitted\") and every scanner fails immediately.\n\nSet this to true ONLY on hosts hitting that incompatibility. Scanner\ncontainers still run with read-only rootfs, tmpfs /tmp, no-network by\ndefault, and read-only source mounts, so the marginal isolation loss\nis small. The preferred fix remains replacing snap docker with a\ndistro-packaged docker.","type":"boolean"},"scanner_fetch_package_source":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.FetchPackageSource\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.EffectiveFetchPackageSource. Cleared after migration.\n\nScannerFetchPackageSource controls whether the scanner fetches the\nPUBLISHED source of package-runner servers (npx/uvx) — without executing\nit — when no local source is available (no Docker container, no local\npackage cache, no working_dir). This is the primary quarantine/scan\ntarget: a quarantined-on-add server is never run locally, so without this\nthe scan degrades to tool-definitions-only (no real source-level\nanalysis). See MCP-2206.\n\nFetching uses ` + "`" + `npm pack --ignore-scripts` + "`" + ` (npm) and ` + "`" + `uv pip download` + "`" + ` /\n` + "`" + `pip download` + "`" + ` with ` + "`" + `--only-binary=:all:` + "`" + ` (Python), which only download +\nunpack archives and NEVER run install, build, or setup.py — a scanner must\nnot execute the untrusted code it is scanning. The Python\n` + "`" + `--only-binary=:all:` + "`" + ` flag is required because downloading an sdist would\ninvoke its build backend (setup.py); packages with no wheel fall back to\ntool-definitions-only instead. Extraction is hardened against path\ntraversal and decompression bombs.\n\nDefault (nil) is ENABLED. Set to false on air-gapped deployments to\nforbid the scanner's network egress; such servers then fall back to the\ntool-definitions-only scan with no regression.","type":"boolean"},"scanner_registry_url":{"type":"string"},"tpa_bundle_path":{"description":"TPABundlePath is the filesystem path to the tpa-db scanner-bundle.json\nthe offline TPA scanner runs (spec 086 FR-019: the signature-DB location\nMUST be configuration-driven, not hardcoded). Empty (the default) runs the\ncorpus embedded in this build.\n\nEnv override: MCPPROXY_TPA_BUNDLE_PATH. Hot-reloadable — the path is\nre-read on every config.reloaded event via\nscanner.Service.ApplySecurityConfig, so a corpus refresh needs no restart.\nA configured bundle that fails to read/parse/version-check/compile is\nREFUSED and the previously active corpus stays live (fail-closed, never\nfail-empty); the reason is logged and surfaced in the security overview's\nsignature_bundle.load_error.","type":"string"}},"type":"object"},"config.SensitiveDataDetectionConfig":{"description":"Sensitive data detection settings (Spec 026)","properties":{"categories":{"additionalProperties":{"type":"boolean"},"description":"Enable/disable specific detection categories","type":"object"},"custom_patterns":{"description":"User-defined detection patterns","items":{"$ref":"#/components/schemas/config.CustomPattern"},"type":"array","uniqueItems":false},"enabled":{"description":"Enable sensitive data detection (default: true)","type":"boolean"},"entropy_threshold":{"description":"Shannon entropy threshold for high-entropy detection (default: 4.5)","type":"number"},"max_payload_size_kb":{"description":"Max size to scan before truncating (default: 1024)","type":"integer"},"scan_requests":{"description":"Scan tool call arguments (default: true)","type":"boolean"},"scan_responses":{"description":"Scan tool responses (default: true)","type":"boolean"},"sensitive_keywords":{"description":"Keywords to flag","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ServerConfig":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve tool\nchanges/additions (disabling per-server rug-pull protection). Supersedes\nskip_quarantine. MCP-2930 only ACCEPTS, persists, and migrates this flag — it\nis NOT yet consulted at runtime; auto-approval is still governed by\nSkipQuarantine until the trust-baseline behavior change (MCP-2931) migrates the\nruntime consumers onto it.\nTri-state pointer (mirrors QuarantineEnabled): nil = unset (inherit/migrate\nfrom legacy skip_quarantine), explicit true/false = honored as-is so an\nexplicit auto_approve_tool_changes:false overrides a legacy skip_quarantine:true.\nRead via IsAutoApproveToolChanges().","type":"boolean"},"command":{"type":"string"},"created":{"type":"string"},"disabled_tools":{"description":"Denylist: these tools are hidden; mutually exclusive with enabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"enabled":{"type":"boolean"},"enabled_tools":{"description":"Allowlist: only these tools are exposed; mutually exclusive with disabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts overrides whether this server's advertised MCP prompts are\naggregated into mcpproxy's prompts/list. nil (default) inherits the\ndefault-aggregate behavior (included if the server advertises\nCapabilities.Prompts); false excludes it regardless of capability.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"description":"For HTTP servers","type":"object"},"health_check_interval":{"description":"Per-server discovery \u0026 health-check overrides (spec 074). Same *Duration\ntri-state as the global keys: nil = inherit the global value (or default),\npointer to 0s = disabled for this server, positive = that interval.\nHealthCheckInterval is fully wired into the per-server health loop;\nToolDiscoveryInterval is accepted/validated and round-trips for\nforward-compat, but the periodic index sweep is governed by the global\ncadence in this iteration (see spec 074 plan §C).","type":"string"},"init_timeout":{"description":"InitTimeout overrides the global init_timeout for this server's MCP\n` + "`" + `initialize` + "`" + ` handshake deadline (MCP-3322 / GH #760). *Duration tri-state:\nnil = inherit the global value (or 30s default), positive = that deadline.\nResolved by Config.ResolveInitTimeout; validated to {0} ∪ [1s, 30m]. Raise\nthis for upstreams that do legitimate first-run warmup (e.g. caching many\nchannels/users) before responding to ` + "`" + `initialize` + "`" + `.","type":"string"},"isolation":{"$ref":"#/components/schemas/config.IsolationConfig"},"launcher_wait_timeout":{"description":"LauncherWaitTimeout caps how long mcpproxy will wait for a locally-launched\nHTTP/SSE upstream's URL to become reachable after Spawn(). Only consulted\nwhen the server is configured with both Command and an HTTP/SSE URL — i.e.,\nmcpproxy starts the process AND connects via network. Stdio servers ignore\nthis field. Zero or unset → 30s default.","type":"string"},"max_concurrent_requests":{"description":"Per-server concurrency overrides — scope (c) of FR-020 (spec 093, #955).\nTri-state per setting, exactly like HealthCheckInterval: absent = inherit\nthe per-server default set (server_concurrency_defaults), explicit 0 =\ndisable that setting for this server (0 max = no per-server limiter at\nall; 0 queue_size = no pending capacity, shed immediately at the cap),\npositive = override. The global aggregate limiter is never inherited from\nhere — it applies on top, so effective concurrency is min(per-server,\nglobal). Resolved by Config.ResolveServerConcurrency.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/config.OAuthConfig"},"protocol":{"description":"stdio, http, sse, streamable-http, auto","type":"string"},"quarantined":{"description":"Security quarantine status","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets a disconnected server","type":"boolean"},"shared":{"description":"Server edition: shared with all users","type":"boolean"},"skip_quarantine":{"description":"SkipQuarantine is DEPRECATED (MCP-2930): use AutoApproveToolChanges instead.\nKept for back-compat parsing; on config load a legacy skip_quarantine:true is\nmigrated to auto_approve_tool_changes:true only when the new field is unset\n(see normalizeServerQuarantineFlags).","type":"boolean"},"source_registry_id":{"description":"SourceRegistryID records which registry this server was added from (empty\nfor manually-configured servers). MCP-866: surfaced in the approval /\nquarantine view so a reviewer can see a server's origin.","type":"string"},"source_registry_provenance":{"description":"SourceRegistryProvenance records the source registry's provenance at add\ntime (RegistryProvenanceOfficial / RegistryProvenanceCustom). It is purely\ninformational (MCP-1072) — surfaced so a reviewer can see a server's origin\n— and no longer gates quarantine or skip_quarantine.","type":"string"},"tool_discovery_interval":{"type":"string"},"toon_output":{"description":"ToonOutput overrides the global toon_output mode for this server's\ntools (spec 084, FR-001). Plain string, not a pointer: \"\"/absent =\ninherit the global value; \"off\"|\"adaptive\"|\"always\" = override (\"off\"\nis the explicit force-off). Resolved by Config.ResolveToonOutput.","type":"string"},"trust_mode":{"description":"TrustMode is the per-server trust tier: auto|scan|manual. Supersedes\nauto_approve_tool_changes (spec 086). An empty value is derived from the\nlegacy fields at load via normalizeServerQuarantineFlags; the single\nresolution point is EffectiveTrustMode(), which treats an empty or\nunrecognized value as manual (secure by default). Read via\nEffectiveTrustMode(), never the raw string.","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"working_dir":{"description":"Working directory for stdio servers","type":"string"}},"type":"object"},"config.TLSConfig":{"description":"TLS configuration","properties":{"certs_dir":{"description":"Directory for certificates","type":"string"},"enabled":{"description":"Enable HTTPS","type":"boolean"},"hsts":{"description":"Enable HTTP Strict Transport Security","type":"boolean"},"require_client_cert":{"description":"Enable mTLS","type":"boolean"}},"type":"object"},"config.TelemetryConfig":{"description":"Telemetry settings (Spec 036)","properties":{"anonymous_id":{"description":"Auto-generated UUIDv4","type":"string"},"anonymous_id_created_at":{"description":"Spec 042 (Tier 2) additions — all default-zero, all backwards-compatible.","type":"string"},"enabled":{"description":"Default: true (opt-out)","type":"boolean"},"endpoint":{"description":"Override for testing","type":"string"},"last_reported_version":{"description":"Upgrade funnel","type":"string"},"last_startup_outcome":{"description":"success|port_conflict|db_locked|...","type":"string"},"notice_shown":{"description":"First-run notice flag","type":"boolean"}},"type":"object"},"config.TokenizerConfig":{"description":"Tokenizer configuration for token counting","properties":{"default_model":{"description":"Default model for tokenization (e.g., \"gpt-4\")","type":"string"},"enabled":{"description":"Enable token counting","type":"boolean"},"encoding":{"description":"Default encoding (e.g., \"cl100k_base\")","type":"string"}},"type":"object"},"config.TracingExporterConfig":{"description":"Tracing gates the OpenTelemetry OTLP trace exporter (MCP-32). Disabled by\ndefault.","properties":{"enabled":{"description":"Enabled turns on OTLP trace export for tool calls and upstream hops.","type":"boolean"},"endpoint":{"description":"Endpoint is the collector address as host:port (no scheme), e.g.\n\"localhost:4318\" for http or \"localhost:4317\" for grpc.","type":"string"},"protocol":{"description":"Protocol selects the OTLP transport: \"http\" or \"grpc\".","type":"string"},"sample_rate":{"description":"SampleRate is the head-based trace sampling ratio in [0,1]. Default 0.1.\nOmit the key for the 0.1 default; set it to 0 to sample nothing.","type":"number"}},"type":"object"},"config.UpdateCheckConfig":{"description":"Update-check settings (Spec 079 FR-012): config-file control of the\nbackground upgrade-awareness checker (internal/updatecheck). nil =\nenabled on the stable channel (existing default behavior). The existing\nenvironment switches keep working and WIN over these keys (FR-014):\nMCPPROXY_DISABLE_AUTO_UPDATE=true force-disables even when\nenabled=true, and MCPPROXY_ALLOW_PRERELEASE_UPDATES=true force-selects\nthe rc channel even when channel=stable.","properties":{"channel":{"description":"Channel selects which releases are offered as updates: \"stable\"\n(default; prereleases never offered) or \"rc\" (prereleases included).\nEmpty resolves to stable. Validated in ValidateDetailed.\n\nNOTE: for a RELEASED build the running binary's own version is\nauthoritative and overrides this field — a stable build is never\noffered an RC (even with channel=rc), and an RC build always tracks the\nrc channel. This field only takes effect on dev/unstamped builds. See\ninternal/updatecheck.Checker.IncludePrereleases.","type":"string"},"enabled":{"description":"Enabled gates all update checking. Tri-state: nil/absent = enabled\n(default true, matching pre-079 behavior). When false, no network\ncheck is performed and no upgrade nudge appears on any surface\n(FR-015) — /api/v1/info omits the update object entirely.","type":"boolean"}},"type":"object"},"configimport.FailedServer":{"properties":{"details":{"type":"string"},"error":{"type":"string"},"name":{"type":"string"}},"type":"object"},"configimport.ImportSummary":{"properties":{"failed":{"type":"integer"},"imported":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"configimport.SkippedServer":{"properties":{"name":{"type":"string"},"reason":{"description":"\"already_exists\", \"filtered_out\", \"invalid_name\"","type":"string"}},"type":"object"},"connect.ConnectResult":{"description":"The full result; its action mirrors the top-level one","properties":{"action":{"description":"\"created\", \"updated\", \"already_exists\", \"removed\", \"not_found\"","type":"string"},"backup_path":{"type":"string"},"client":{"type":"string"},"config_path":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.APIResponse":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ActivityDetailResponse":{"properties":{"activity":{"$ref":"#/components/schemas/contracts.ActivityRecord"}},"type":"object"},"contracts.ActivityListResponse":{"properties":{"activities":{"items":{"$ref":"#/components/schemas/contracts.ActivityRecord"},"type":"array","uniqueItems":false},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.ActivityRecord":{"properties":{"arguments":{"description":"Tool call arguments","type":"object"},"detection_types":{"description":"List of detection types found","items":{"type":"string"},"type":"array","uniqueItems":false},"duration_ms":{"description":"Execution duration in milliseconds","type":"integer"},"error_message":{"description":"Error details if status is \"error\"","type":"string"},"has_sensitive_data":{"description":"Sensitive data detection fields (Spec 026)","type":"boolean"},"id":{"description":"Unique identifier (ULID format)","type":"string"},"max_severity":{"description":"Highest severity level detected (critical, high, medium, low)","type":"string"},"metadata":{"description":"Additional context-specific data","type":"object"},"parent_id":{"description":"Correlation id of the parent call (the code_execution whose sandbox issued this sub-call)","type":"string"},"request_bytes":{"description":"Byte sizes measured pre-truncation, mirroring storage.ActivityRecord\n(Spec 069 A1). They are the only cost signal a bodies-off export carries:\nwith payloads suppressed there is no text left to measure, so a consumer\naccounting for a record it cannot read has nothing else to go on. They are\nbyte LENGTHS, not token counts — the basis for an explicit estimate, never\na measured figure (spec 103, contracts/replay-input.md).\n\nZero means UNKNOWN, not free: legacy records predate the measurement and\ncode-execution sub-calls record both as zero. Hence omitempty — an absent\nkey tells a consumer to fall to exclusion accounting, whereas a present\nzero would read as a costless call and silently understate the workload.","type":"integer"},"request_id":{"description":"HTTP request ID for correlation","type":"string"},"response":{"description":"Tool response (potentially truncated)","type":"string"},"response_bytes":{"description":"Raw upstream response size in bytes before truncation","type":"integer"},"response_truncated":{"description":"True if response was truncated","type":"boolean"},"server_name":{"description":"Name of upstream MCP server","type":"string"},"session_id":{"description":"MCP transport session ID (regenerated on every reconnect)","type":"string"},"source":{"$ref":"#/components/schemas/contracts.ActivitySource"},"status":{"description":"Result status: \"success\", \"error\", \"blocked\", \"rejected\"","type":"string"},"timestamp":{"description":"When activity occurred","type":"string"},"tool_name":{"description":"Name of tool called","type":"string"},"type":{"$ref":"#/components/schemas/contracts.ActivityType"},"work_session_id":{"description":"Spec 082: one client, one project, across reconnects","type":"string"}},"type":"object"},"contracts.ActivitySource":{"description":"How activity was triggered: \"mcp\", \"cli\", \"api\"","type":"string","x-enum-varnames":["ActivitySourceMCP","ActivitySourceCLI","ActivitySourceAPI"]},"contracts.ActivitySummaryResponse":{"properties":{"blocked_count":{"description":"Count of blocked activities","type":"integer"},"call_count":{"description":"CallCount is how many of those records are CALLS THE USER MADE, as\ndefined once in storage.CountsAsCall and shared with the usage aggregate\nbehind the Usage tab (audit finding F1, #1046). TotalCount answers \"how\nmany rows does the Activity Log have\"; CallCount answers \"how many calls\nwere there\". They are different questions — quarantine auto-approvals,\nsystem start, security scans and management chatter are events, not calls\n— and printing either one under the other's label is how the same instance\ncame to report 51 calls on one screen and 19 on another.","type":"integer"},"call_error_count":{"description":"CallErrorCount is the failures within CallCount, so an error RATE computed\nfrom this response has one denominator. It is not ErrorCount: a policy\nblock is a failed call but carries status \"blocked\", and a shed call is an\nerror in neither sense because it never ran.","type":"integer"},"end_time":{"description":"End of the period (RFC3339)","type":"string"},"error_count":{"description":"Count of error activities","type":"integer"},"other_count":{"description":"OtherCount is every record whose status is outside the four-value\nvocabulary above, so that\n\n\tsuccess + error + blocked + rejected + other == total\n\nholds by construction. The status field is a CLOSED vocabulary for tool\ncalls, but the activity log is wider than tool calls: a quarantine change\nstores its ACTION there (\"approved\", \"auto_approved\"), a policy decision\nstores its DECISION (\"allow\"). Those rows were counted in the total and in\nnone of the four buckets, so the Activity Log's own status tiles summed to\nless than the denominator printed beside them — 15+4+0+0 under a \"42\"\n(audit finding F2, #1046). The residual now has a name and a tile.","type":"integer"},"period":{"description":"Time period (1h, 24h, 7d, 30d)","type":"string"},"rejected_count":{"description":"RejectedCount is the number of calls shed by a concurrency limiter before\nthey reached an upstream (spec 093). Counted separately from errors: it is\nproxy backpressure, not an upstream fault, and it is the signal an\noperator right-sizes max_concurrent_requests against.","type":"integer"},"start_time":{"description":"Start of the period (RFC3339)","type":"string"},"success_count":{"description":"Count of successful activities","type":"integer"},"top_servers":{"description":"Top servers by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopServer"},"type":"array","uniqueItems":false},"top_tools":{"description":"Top tools by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopTool"},"type":"array","uniqueItems":false},"total_count":{"description":"Total activity count","type":"integer"}},"type":"object"},"contracts.ActivityTopServer":{"properties":{"count":{"description":"Activity count","type":"integer"},"name":{"description":"Server name","type":"string"}},"type":"object"},"contracts.ActivityTopTool":{"properties":{"count":{"description":"Activity count","type":"integer"},"server":{"description":"Server name","type":"string"},"tool":{"description":"Tool name","type":"string"}},"type":"object"},"contracts.ActivityType":{"description":"Type of activity","type":"string","x-enum-varnames":["ActivityTypeToolCall","ActivityTypePolicyDecision","ActivityTypeQuarantineChange","ActivityTypeServerChange"]},"contracts.AddFromRegistryRequest":{"properties":{"enabled":{"description":"defaults to true when nil","type":"boolean"},"env":{"additionalProperties":{"type":"string"},"description":"overrides + required-input values","type":"object"},"name":{"description":"optional name override","type":"string"}},"type":"object"},"contracts.AddRegistrySourceRequest":{"properties":{"id":{"description":"derived from the host when empty","type":"string"},"name":{"description":"defaults to the id","type":"string"},"protocol":{"description":"defaults to modelcontextprotocol/registry","type":"string"},"url":{"description":"required https registry URL","type":"string"}},"type":"object"},"contracts.ConfigApplyResult":{"properties":{"applied_immediately":{"type":"boolean"},"changed_fields":{"items":{"type":"string"},"type":"array","uniqueItems":false},"requires_restart":{"type":"boolean"},"restart_reason":{"type":"string"},"success":{"type":"boolean"},"validation_errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DCRStatus":{"properties":{"attempted":{"type":"boolean"},"error":{"type":"string"},"status_code":{"type":"integer"},"success":{"type":"boolean"}},"type":"object"},"contracts.DeepScanDescriptor":{"description":"DeepScan reports the opt-in \"deep scan\" layer status (Spec 077 US3),\nSEPARATELY from the baseline verdict above. Always emitted on a computed\nsummary — when deep scan is off (the default) it reports enabled=false\nplus any enabled-but-skipped Docker scanners. It never influences Status.","properties":{"available":{"type":"boolean"},"enabled":{"type":"boolean"},"ran":{"type":"boolean"},"scanners_failed":{"items":{"$ref":"#/components/schemas/contracts.DeepScanScannerFailure"},"type":"array","uniqueItems":false},"skipped_scanners":{"description":"SkippedScanners lists Docker scanners the user enabled that are skipped\nbecause security.deep_scan.enabled is false (informational).","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DeepScanScannerFailure":{"properties":{"id":{"type":"string"},"reason":{"type":"string"}},"type":"object"},"contracts.DeprecatedConfigWarning":{"properties":{"field":{"type":"string"},"message":{"type":"string"},"replacement":{"type":"string"}},"type":"object"},"contracts.Diagnostic":{"description":"Spec 044 — structured diagnostic error and stable error code. Both\nare populated when the server is in a failed state and the error\nhas been classified by internal/diagnostics. Healthy servers omit\nthese fields.","properties":{"cause":{"type":"string"},"code":{"type":"string"},"detected_at":{"type":"string"},"docs_url":{"type":"string"},"fix_steps":{"items":{"$ref":"#/components/schemas/contracts.DiagnosticFixStep"},"type":"array","uniqueItems":false},"severity":{"type":"string"},"user_message":{"type":"string"}},"type":"object"},"contracts.DiagnosticFixStep":{"properties":{"command":{"type":"string"},"destructive":{"type":"boolean"},"fixer_key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"url":{"type":"string"}},"type":"object"},"contracts.Diagnostics":{"properties":{"deprecated_configs":{"description":"Deprecated config fields found","items":{"$ref":"#/components/schemas/contracts.DeprecatedConfigWarning"},"type":"array","uniqueItems":false},"docker_status":{"$ref":"#/components/schemas/contracts.DockerStatus"},"missing_secrets":{"description":"Renamed to avoid conflict","items":{"$ref":"#/components/schemas/contracts.MissingSecretInfo"},"type":"array","uniqueItems":false},"oauth_issues":{"description":"OAuth parameter mismatches","items":{"$ref":"#/components/schemas/contracts.OAuthIssue"},"type":"array","uniqueItems":false},"oauth_required":{"items":{"$ref":"#/components/schemas/contracts.OAuthRequirement"},"type":"array","uniqueItems":false},"runtime_warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false},"timestamp":{"type":"string"},"total_issues":{"type":"integer"},"upstream_errors":{"items":{"$ref":"#/components/schemas/contracts.UpstreamError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DockerStatus":{"properties":{"available":{"type":"boolean"},"error":{"type":"string"},"version":{"type":"string"}},"type":"object"},"contracts.EditRegistrySourceRequest":{"properties":{"name":{"description":"new display name","type":"string"},"servers_url":{"description":"explicit servers-collection URL","type":"string"},"url":{"description":"new base/servers https URL","type":"string"}},"type":"object"},"contracts.ErrorResponse":{"properties":{"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.FindingCounts":{"properties":{"dangerous":{"description":"Tool poisoning, active prompt injection","type":"integer"},"info":{"description":"Low-severity CVEs, informational","type":"integer"},"total":{"type":"integer"},"warning":{"description":"Rug pull, supply chain CVEs with exploits","type":"integer"}},"type":"object"},"contracts.GetConfigResponse":{"properties":{"config":{"description":"The configuration object","type":"object"},"config_path":{"description":"Path to config file","type":"string"}},"type":"object"},"contracts.GetRegistriesResponse":{"properties":{"registries":{"items":{"$ref":"#/components/schemas/contracts.Registry"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerLogsResponse":{"properties":{"count":{"type":"integer"},"logs":{"items":{"$ref":"#/components/schemas/contracts.LogEntry"},"type":"array","uniqueItems":false},"server_name":{"type":"string"}},"type":"object"},"contracts.GetServerToolCallsResponse":{"properties":{"server_name":{"type":"string"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerToolsResponse":{"properties":{"count":{"type":"integer"},"server_name":{"type":"string"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GetServersResponse":{"properties":{"servers":{"items":{"$ref":"#/components/schemas/contracts.Server"},"type":"array","uniqueItems":false},"stats":{"$ref":"#/components/schemas/contracts.ServerStats"}},"type":"object"},"contracts.GetSessionDetailResponse":{"properties":{"session":{"$ref":"#/components/schemas/contracts.MCPSession"}},"type":"object"},"contracts.GetSessionsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"sessions":{"items":{"$ref":"#/components/schemas/contracts.MCPSession"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetToolCallDetailResponse":{"properties":{"tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"}},"type":"object"},"contracts.GetToolCallsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GlobalToolsResponse":{"properties":{"failed_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"partial":{"type":"boolean"},"stats":{"$ref":"#/components/schemas/contracts.GlobalToolsStats"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GlobalToolsStats":{"properties":{"disabled":{"type":"integer"},"enabled":{"type":"integer"},"pending_approval":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.HealthStatus":{"description":"Unified health status calculated by the backend","properties":{"action":{"description":"Action is the suggested fix action: \"login\", \"restart\", \"enable\", \"approve\", \"view_logs\", \"set_secret\", \"configure\", \"edit_url\", or \"\" (none)","type":"string"},"admin_state":{"description":"AdminState indicates the admin state: \"enabled\", \"disabled\", or \"quarantined\"","type":"string"},"detail":{"description":"Detail is an optional longer explanation of the status","type":"string"},"level":{"description":"Level indicates the health level: \"healthy\", \"degraded\", or \"unhealthy\"","type":"string"},"summary":{"description":"Summary is a human-readable status message (e.g., \"Connected (5 tools)\")","type":"string"}},"type":"object"},"contracts.InfoEndpoints":{"description":"Available API endpoints","properties":{"http":{"description":"HTTP endpoint address (e.g., \"127.0.0.1:8080\")","type":"string"},"socket":{"description":"Unix socket path (empty if disabled)","type":"string"}},"type":"object"},"contracts.InfoResponse":{"properties":{"endpoints":{"$ref":"#/components/schemas/contracts.InfoEndpoints"},"launched_by":{"description":"LaunchedBy is the durable launch provenance of the running core (Spec\n092 FR-001a): \"tray\" when a tray spawned it, \"installer\" when the macOS\nPKG postinstall did, \"\" when user-launched or unknown. Always present\n(possibly empty) so a tray can distinguish \"old core, not mine\" from\n\"old core I may supersede\".","type":"string"},"listen_addr":{"description":"Listen address (e.g., \"127.0.0.1:8080\")","type":"string"},"pid":{"description":"PID is the operating-system process id of the running core (Spec 092\nFR-002). A tray that merely ATTACHED to a core holds no Process handle\nfor it, so without this there is no mechanism at all to stop a stale\ncore — the consent action would have nothing to act on and could only\nprint instructions. Paired with LaunchedBy it is what lets a newer tray\nsupersede a core an older tray started.","type":"integer"},"update":{"$ref":"#/components/schemas/contracts.UpdateInfo"},"update_policy":{"$ref":"#/components/schemas/contracts.UpdatePolicy"},"version":{"description":"Current MCPProxy version","type":"string"},"web_ui_url":{"description":"URL to access the web control panel","type":"string"}},"type":"object"},"contracts.IsolationConfig":{"properties":{"cpu_limit":{"type":"string"},"enabled":{"description":"Enabled is the EFFECTIVE isolation state for this server: whether its\nprocess is actually CONFINED, after the global setting, the per-server\noverride, the structural gates and the host's capabilities. It is NOT the\nraw per-server override — read EnabledOverride for that (GH #1142).\n\nREAD-ONLY. The write surfaces reject an ` + "`" + `enabled` + "`" + ` key precisely because\nit is derived: echoing it back would convert \"inherits the global\nsetting\" into a permanent explicit override. Write EnabledOverride.\n\nIt stays a non-pointer bool that is always present on the wire: the macOS\ntray decodes it as a non-optional Swift Bool, so omitting or nulling the\nkey would fail Codable for the whole server payload. Older clients that\nread this field now simply get a true answer.","type":"boolean"},"enabled_override":{"description":"EnabledOverride is the RAW per-server ` + "`" + `isolation.enabled` + "`" + ` override, as\npersisted. Absent means \"inherit the global setting\" — which is a\ndistinct state from an explicit false, and the distinction the reporting\nbug used to destroy.","type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"memory_limit":{"type":"string"},"mode_override":{"description":"ModeOverride is the RAW per-server ` + "`" + `isolation.mode` + "`" + ` override\n(\"docker\" | \"sandbox\" | \"none\"). Absent means \"inherit\".","type":"string"},"network_mode":{"type":"string"},"timeout":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.IsolationDefaults":{"description":"IsolationDefaults exposes the resolved baseline values that\nwould apply when no per-server override is set. Populated on\nlist/get responses; never consumed on PATCH requests.","properties":{"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"network_mode":{"type":"string"},"runtime_type":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.IsolationEffective":{"description":"IsolationEffective exposes the resolved isolation state (and the rule\nthat decided it) so clients can distinguish \"inherits global\" from an\nexplicit per-server choice. Read-only; never consumed on PATCH.","properties":{"global_mode":{"description":"GlobalMode is what \"inherit\" resolves to right now.","type":"string"},"inherited":{"description":"Inherited is true when the server sets neither ` + "`" + `isolation.enabled` + "`" + ` nor\n` + "`" + `isolation.mode` + "`" + `, so its state tracks the global setting.","type":"boolean"},"isolated":{"description":"Isolated reports whether the process is actually CONFINED. It is NOT\nsimply Mode != \"none\": \"sandbox\" on a host that cannot enforce Landlock\n(any non-Linux OS, or a kernel without the LSM) runs the server\nunconfined, and Source then says \"sandbox-unavailable\" (GH #1142).","type":"boolean"},"mode":{"description":"Mode is the effective isolation mode: \"docker\" | \"sandbox\" | \"none\" —\nexactly what the spawn path branches on.","type":"string"},"source":{"description":"Source names the deciding rule: \"global\", \"server-mode\",\n\"server-opt-out\", \"server-opt-in-ignored\", \"not-stdio\",\n\"already-docker\", \"sandbox-unavailable\" or \"unsupported-mode\".\nTreat an unrecognized value as \"global\".","type":"string"}},"type":"object"},"contracts.LogEntry":{"properties":{"fields":{"type":"object"},"level":{"type":"string"},"message":{"type":"string"},"server":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.MCPSession":{"properties":{"client_name":{"type":"string"},"client_version":{"type":"string"},"end_time":{"type":"string"},"experimental":{"items":{"type":"string"},"type":"array","uniqueItems":false},"has_roots":{"description":"MCP Client Capabilities","type":"boolean"},"has_sampling":{"type":"boolean"},"id":{"type":"string"},"last_activity":{"type":"string"},"start_time":{"type":"string"},"status":{"type":"string"},"tool_call_count":{"type":"integer"},"total_tokens":{"type":"integer"},"work_session_id":{"type":"string"},"workspace_name":{"description":"Workspace / work session (Spec 082). WorkspaceName is the project's\nbasename — the full local path is never exposed. WorkSessionID groups the\nreconnects that make up one stretch of user work.","type":"string"}},"type":"object"},"contracts.MetadataStatus":{"properties":{"authorization_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"error":{"type":"string"},"found":{"type":"boolean"},"url_checked":{"type":"string"}},"type":"object"},"contracts.MissingSecretInfo":{"properties":{"secret_name":{"type":"string"},"used_by":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.NPMPackageInfo":{"properties":{"exists":{"type":"boolean"},"install_cmd":{"type":"string"}},"type":"object"},"contracts.OAuthConfig":{"properties":{"auth_url":{"type":"string"},"client_id":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_port":{"type":"integer"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false},"token_expires_at":{"description":"When the OAuth token expires","type":"string"},"token_url":{"type":"string"},"token_valid":{"description":"Whether token is currently valid","type":"boolean"}},"type":"object"},"contracts.OAuthErrorDetails":{"description":"Structured discovery/failure details","properties":{"authorization_server_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"dcr_status":{"$ref":"#/components/schemas/contracts.DCRStatus"},"protected_resource_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"server_url":{"type":"string"}},"type":"object"},"contracts.OAuthFlowError":{"properties":{"correlation_id":{"description":"Flow tracking ID for log correlation","type":"string"},"debug_hint":{"description":"CLI command for log lookup","type":"string"},"details":{"$ref":"#/components/schemas/contracts.OAuthErrorDetails"},"error_code":{"description":"Machine-readable error code (e.g., OAUTH_NO_METADATA)","type":"string"},"error_type":{"description":"Category of OAuth runtime failure","type":"string"},"message":{"description":"Human-readable error description","type":"string"},"request_id":{"description":"HTTP request ID (from PR #237)","type":"string"},"server_name":{"description":"Server that failed OAuth","type":"string"},"success":{"description":"Always false","type":"boolean"},"suggestion":{"description":"Actionable remediation hint","type":"string"}},"type":"object"},"contracts.OAuthIssue":{"properties":{"documentation_url":{"type":"string"},"error":{"type":"string"},"issue":{"type":"string"},"missing_params":{"items":{"type":"string"},"type":"array","uniqueItems":false},"resolution":{"type":"string"},"server_name":{"type":"string"}},"type":"object"},"contracts.OAuthRequirement":{"properties":{"expires_at":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"state":{"type":"string"}},"type":"object"},"contracts.OAuthStartResponse":{"properties":{"auth_url":{"description":"Authorization URL (always included for manual use)","type":"string"},"browser_error":{"description":"Error message if browser launch failed","type":"string"},"browser_opened":{"description":"Whether browser launch succeeded","type":"boolean"},"correlation_id":{"description":"UUID for tracking this flow","type":"string"},"message":{"description":"Human-readable status message","type":"string"},"server_name":{"description":"Name of the server being authenticated","type":"string"},"success":{"description":"Always true for successful start","type":"boolean"}},"type":"object"},"contracts.PreflightPolicy":{"properties":{"exclude_destructive":{"type":"boolean"},"exclude_open_world":{"type":"boolean"},"read_only_only":{"type":"boolean"}},"type":"object"},"contracts.PreflightReason":{"type":"string","x-enum-varnames":["PreflightReasonServerInitializing","PreflightReasonServerUnhealthy","PreflightReasonServerDisabled","PreflightReasonServerQuarantined","PreflightReasonToolPendingApproval","PreflightReasonToolChanged","PreflightReasonToolBlockedByUser","PreflightReasonOAuthRequired","PreflightReasonHashMismatch","PreflightReasonServerNotInScope","PreflightReasonToolDeniedByConfig","PreflightReasonMissingAnnotation","PreflightReasonPolicyFiltered","PreflightReasonNotFound","PreflightReasonServerNotConfigured"]},"contracts.PreflightRequest":{"properties":{"policy":{"$ref":"#/components/schemas/contracts.PreflightPolicy"},"profile":{"description":"Profile evaluates under a named profile's server scope. Unknown: 400.","type":"string"},"tools":{"description":"Tools is 1..100 entries BEFORE dedup; duplicates are collapsed, and\nduplicate ids carrying different pins are a validation error.","items":{"$ref":"#/components/schemas/contracts.PreflightToolRef"},"type":"array","uniqueItems":false},"wait_ms":{"description":"WaitMS polls local state for up to this many milliseconds (cap 10000)\nwhile every failure is retryable-class.","type":"integer"}},"type":"object"},"contracts.PreflightResponse":{"properties":{"checked_at":{"type":"string"},"tools":{"description":"Tools are ordered by first occurrence of each unique id in the request.","items":{"$ref":"#/components/schemas/contracts.PreflightToolResult"},"type":"array","uniqueItems":false},"verdict":{"$ref":"#/components/schemas/contracts.PreflightVerdict"},"waited_ms":{"description":"WaitedMS is present when wait_ms was requested (0 when the wait\nsemaphore was exhausted and the request resolved immediately).","type":"integer"}},"type":"object"},"contracts.PreflightStatus":{"type":"string","x-enum-varnames":["PreflightStatusReady","PreflightStatusUnavailable"]},"contracts.PreflightToolRef":{"properties":{"id":{"description":"ID is a canonical \"\u003cserver\u003e:\u003ctool\u003e\" id. A malformed id is answered with a\nper-ID not_found carrying a format hint, never a request-level error.","type":"string"},"pin_hash":{"description":"PinHash is \"sha256/v{N}:{hex}\" — the schema version is embedded so a\nproxy-side hash-algorithm bump is distinguishable from upstream drift.","type":"string"}},"type":"object"},"contracts.PreflightToolResult":{"properties":{"action":{"type":"string"},"detail":{"type":"string"},"did_you_mean":{"description":"DidYouMean carries up to 3 nearest caller-visible ids on not_found. It\nnever crosses a scope boundary and never names a quarantined server's\ntools.","items":{"type":"string"},"type":"array","uniqueItems":false},"hash":{"description":"Hash is the tool's current pin (\"sha256/v{N}:{hex}\") — operator tier,\nready results only. Never disclosed to an agent token.","type":"string"},"id":{"type":"string"},"reason":{"$ref":"#/components/schemas/contracts.PreflightReason"},"remediation":{"type":"string"},"retryable":{"type":"boolean"},"status":{"$ref":"#/components/schemas/contracts.PreflightStatus"}},"type":"object"},"contracts.PreflightVerdict":{"type":"string","x-enum-varnames":["PreflightVerdictReady","PreflightVerdictDegradedRetryable","PreflightVerdictBlocked","PreflightVerdictUnknownIDs"]},"contracts.QuarantineStats":{"description":"Tool quarantine metrics for this server","properties":{"blocked_count":{"description":"Number of disabled (blocked) tools","type":"integer"},"changed_count":{"description":"Number of tools whose description/schema changed since approval","type":"integer"},"pending_count":{"description":"Number of newly discovered tools awaiting approval","type":"integer"}},"type":"object"},"contracts.RefreshRegistryResponse":{"properties":{"cleared":{"description":"number of cached entries dropped","type":"integer"},"registry_id":{"type":"string"}},"type":"object"},"contracts.Registry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag (MCP-866): \"official/trusted\" for built-in\ndefaults, \"custom/unverified\" for user-added registries.","type":"string"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"trusted":{"description":"Trusted indicates whether this is an official, shipped-by-default\nregistry. Trust is derived from membership in the default set, never\nfrom self-assertion in config.","type":"boolean"},"url":{"type":"string"}},"type":"object"},"contracts.RegistryCacheInfo":{"properties":{"age_seconds":{"type":"number"},"stale":{"type":"boolean"}},"type":"object"},"contracts.RegistryUnavailable":{"properties":{"reason":{"type":"string"}},"type":"object"},"contracts.ReplayToolCallRequest":{"properties":{"arguments":{"description":"Modified arguments for replay","type":"object"}},"type":"object"},"contracts.ReplayToolCallResponse":{"properties":{"error":{"description":"Error if replay failed","type":"string"},"new_call_id":{"description":"ID of the newly created call","type":"string"},"new_tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"replayed_from":{"description":"Original call ID","type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.RepositoryInfo":{"description":"Detected package info","properties":{"npm":{"$ref":"#/components/schemas/contracts.NPMPackageInfo"}},"type":"object"},"contracts.RepositoryServer":{"properties":{"connect_url":{"description":"Alternative connection URL","type":"string"},"created_at":{"type":"string"},"description":{"type":"string"},"id":{"type":"string"},"install_cmd":{"description":"Installation command","type":"string"},"name":{"type":"string"},"registry":{"description":"Which registry this came from","type":"string"},"repository_info":{"$ref":"#/components/schemas/contracts.RepositoryInfo"},"source_code_url":{"description":"Source repository URL","type":"string"},"updated_at":{"type":"string"},"url":{"description":"MCP endpoint for remote servers only","type":"string"}},"type":"object"},"contracts.SearchRegistryServersResponse":{"properties":{"cache":{"$ref":"#/components/schemas/contracts.RegistryCacheInfo"},"query":{"type":"string"},"registry_id":{"type":"string"},"servers":{"items":{"$ref":"#/components/schemas/contracts.RepositoryServer"},"type":"array","uniqueItems":false},"tag":{"type":"string"},"total":{"type":"integer"},"unavailable":{"$ref":"#/components/schemas/contracts.RegistryUnavailable"}},"type":"object"},"contracts.SearchResult":{"properties":{"matches":{"type":"integer"},"score":{"type":"number"},"snippet":{"type":"string"},"tool":{"$ref":"#/components/schemas/contracts.Tool"}},"type":"object"},"contracts.SearchToolsResponse":{"properties":{"query":{"type":"string"},"results":{"items":{"$ref":"#/components/schemas/contracts.SearchResult"},"type":"array","uniqueItems":false},"took":{"type":"string"},"total":{"type":"integer"}},"type":"object"},"contracts.SecurityScanSummary":{"description":"Latest security scan results summary","properties":{"deep_scan":{"$ref":"#/components/schemas/contracts.DeepScanDescriptor"},"finding_counts":{"$ref":"#/components/schemas/contracts.FindingCounts"},"last_scan_at":{"type":"string"},"risk_score":{"description":"0-100","type":"integer"},"scanners_failed":{"type":"integer"},"scanners_run":{"description":"Scanner coverage for the primary (baseline) scan pass — informational only.\nSpec 077 US3 (FR-008/FR-014): Status is derived SOLELY from the\ndeterministic baseline findings; a failed Docker deep scanner no longer\ndowngrades a clean verdict. That failure is surfaced via DeepScan instead.","type":"integer"},"scanners_total":{"type":"integer"},"status":{"description":"\"clean\", \"warnings\", \"dangerous\", \"failed\", \"not_scanned\", \"scanning\"","type":"string"}},"type":"object"},"contracts.Server":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"authenticated":{"description":"OAuth authentication status","type":"boolean"},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges mirrors config.ServerConfig.AutoApproveToolChanges\n(MCP-2930): the per-server intent to auto-approve new/changed tools past\nthe trust baseline. Tri-state *bool — nil means \"never set\" (omitted from\nthe payload), so the Web UI toggle (MCP-2932) can distinguish unset from\nan explicit false. Read-only on the GET path; PATCH/POST accept it via\nAddServerRequest.","type":"boolean"},"command":{"type":"string"},"connected":{"type":"boolean"},"connected_at":{"type":"string"},"connecting":{"type":"boolean"},"created":{"type":"string"},"diagnostic":{"$ref":"#/components/schemas/contracts.Diagnostic"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"error_code":{"type":"string"},"expose_prompts":{"description":"ExposePrompts mirrors config.ServerConfig.ExposePrompts (F9): the per-server\nprompt-aggregation override. Tri-state *bool — nil/omitted means \"inherit\ndefault aggregation\". Surfaced on GET so a caller that PATCHed the override\ncan read it back; PATCH/POST accept it via AddServerRequest.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"health":{"$ref":"#/components/schemas/contracts.HealthStatus"},"id":{"type":"string"},"init_timeout":{"description":"InitTimeout mirrors config.ServerConfig.InitTimeout (MCP-3322 / GH #760):\nthe per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override. Serialized as\na duration string (e.g. \"120s\"); nil/omitted means \"inherit the global\ndefault\". Surfaced on the GET path so clients can read back a configured\noverride; PATCH/POST accept it via AddServerRequest.","type":"string"},"isolation":{"$ref":"#/components/schemas/contracts.IsolationConfig"},"isolation_defaults":{"$ref":"#/components/schemas/contracts.IsolationDefaults"},"isolation_effective":{"$ref":"#/components/schemas/contracts.IsolationEffective"},"last_error":{"type":"string"},"last_reconnect_at":{"type":"string"},"last_retry_time":{"type":"string"},"max_concurrent_requests":{"description":"Spec 093 (GH #955) — per-server concurrency overrides, scope (c) of\nFR-020. Each setting is tri-state: nil (omitted) means \"inherit\nserver_concurrency_defaults\", 0 disables that setting for this server,\npositive overrides it. Surfaced on the GET path so a caller can read back\nwhat it set; PATCH/POST accept them via AddServerRequest. The effective\nconcurrency for a server is additionally bounded by the global aggregate\nlimiter, which is NOT an inheritance source for these fields.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/contracts.OAuthConfig"},"oauth_status":{"description":"OAuth status: \"authenticated\", \"expired\", \"error\", \"none\"","type":"string"},"protocol":{"type":"string"},"quarantine":{"$ref":"#/components/schemas/contracts.QuarantineStats"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_count":{"type":"integer"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets this disconnected server","type":"boolean"},"retry_count":{"type":"integer"},"retry_stopped":{"description":"RetryStopped reports that automatic reconnection has been given up for\ngood because the failure is deterministic and unrecoverable — a missing\nbinary, an image without the interpreter, an unparseable config (GH\n#1145). It is NOT ordinary exponential backoff, which keeps retrying;\nnothing will happen until the user fixes the config or restarts the\nserver. RetryStoppedCode is the stable MCPX_* code that proved it and\nRetryStoppedReason the catalog message explaining how to fix it. All three\nare omitted for servers that are healthy or still retrying.","type":"boolean"},"retry_stopped_code":{"type":"string"},"retry_stopped_reason":{"type":"string"},"security_scan":{"$ref":"#/components/schemas/contracts.SecurityScanSummary"},"should_retry":{"type":"boolean"},"source_registry_id":{"description":"MCP-901 — registry provenance of an upstream that was added from a\nregistry. SourceRegistryID names the source registry (empty for\nmanually-configured servers); SourceRegistryProvenance is the trust tag\nrecorded at add time (\"official/trusted\" or \"custom/unverified\"). Both\nare projected from config.ServerConfig so the approval/quarantine view\ncan render an \"added from \u003cregistry\u003e · unverified\" origin badge. Optional\nand omitted when empty — clients that pre-date this treat them as absent.","type":"string"},"source_registry_provenance":{"type":"string"},"status":{"type":"string"},"token_expires_at":{"description":"When the OAuth token expires (ISO 8601)","type":"string"},"tool_count":{"type":"integer"},"tool_list_token_size":{"description":"Token size for this server's tools","type":"integer"},"trust_mode":{"description":"TrustMode mirrors config.ServerConfig.TrustMode (spec 086): the per-server\ntrust tier (\"auto\"/\"scan\"/\"manual\"). Surfaced on the GET path so clients can\nread back the persisted mode; PATCH/POST accept it via AddServerRequest.\nOmitted when empty (server predates the field / relies on legacy flags).","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"user_logged_out":{"description":"True if user explicitly logged out (prevents auto-reconnection)","type":"boolean"},"working_dir":{"type":"string"}},"type":"object"},"contracts.ServerActionResponse":{"properties":{"action":{"type":"string"},"async":{"type":"boolean"},"server":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ServerStats":{"properties":{"connected_servers":{"type":"integer"},"docker_containers":{"type":"integer"},"quarantined_servers":{"type":"integer"},"token_metrics":{"$ref":"#/components/schemas/contracts.ServerTokenMetrics"},"total_servers":{"type":"integer"},"total_tools":{"type":"integer"}},"type":"object"},"contracts.ServerTokenMetrics":{"properties":{"average_query_result_size":{"description":"Typical retrieve_tools output (tokens)","type":"integer"},"per_server_tool_list_sizes":{"additionalProperties":{"type":"integer"},"description":"Token size per server","type":"object"},"saved_tokens":{"description":"Difference","type":"integer"},"saved_tokens_percentage":{"description":"Percentage saved","type":"number"},"total_server_tool_list_size":{"description":"All upstream tools combined (tokens)","type":"integer"}},"type":"object"},"contracts.SuccessResponse":{"properties":{"data":{"type":"object"},"success":{"type":"boolean"}},"type":"object"},"contracts.TokenMetrics":{"description":"Token usage metrics (nil for older records)","properties":{"encoding":{"description":"Encoding used (e.g., cl100k_base)","type":"string"},"estimated_cost":{"description":"Optional cost estimate","type":"number"},"input_tokens":{"description":"Tokens in the request","type":"integer"},"model":{"description":"Model used for tokenization","type":"string"},"output_tokens":{"description":"Tokens in the response","type":"integer"},"total_tokens":{"description":"Total tokens (input + output)","type":"integer"},"truncated_tokens":{"description":"Tokens removed by truncation","type":"integer"},"was_truncated":{"description":"Whether response was truncated","type":"boolean"}},"type":"object"},"contracts.Tool":{"properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"approval_status":{"type":"string"},"config_denied":{"description":"ConfigDenied is true when the tool is denied by the server's static\nenabled_tools / disabled_tools config. The user cannot override this toggle.","type":"boolean"},"description":{"type":"string"},"disabled":{"description":"Disabled mirrors ToolApprovalRecord.Disabled so per-tool enable state is\navailable without a second round-trip to the approvals endpoint. Absent\nin the JSON when false (default) to keep responses compact.","type":"boolean"},"hash":{"description":"Hash is the tool's current stored hash rendered in the preflight pin\nformat \"sha256/v{N}:{hex}\" (Spec 098 FR-011), where N is the approval\nrecord's HashSchemaVersion. It is the authoring surface for\n` + "`" + `POST /api/v1/preflight` + "`" + ` pins and ` + "`" + `mcpproxy tools preflight --pin` + "`" + `:\ncopy the value straight into a pin.\n\nDisclosure is OPERATOR TIER ONLY — same rule as the preflight per-tool\nresult. The field is omitted for agent-token callers and for tools with\nno stored hash (no approval record yet, or a record written before\nhashes existed).","type":"string"},"held_reason":{"description":"HeldReason, HeldVerdict and HeldSignals mirror the same-named fields on\nstorage.ToolApprovalRecord: the offline-scan evidence that made\ntrust_mode: scan hold this tool for review (spec 086 FR-018). HeldSignals\nnames the matched deterministic check ids, e.g.\n\"tpa.TPA-2026-0001.hidden_instruction\", so a reviewer can see WHY the tool\nis held. All three are omitted for tools that are not held by the scan gate\n(including every record written before the field existed).","type":"string"},"held_signals":{"items":{"type":"string"},"type":"array","uniqueItems":false},"held_verdict":{"type":"string"},"last_used":{"type":"string"},"name":{"type":"string"},"schema":{"type":"object"},"server_name":{"type":"string"},"usage":{"type":"integer"}},"type":"object"},"contracts.ToolAnnotation":{"description":"Tool behavior hints snapshot","properties":{"destructiveHint":{"type":"boolean"},"idempotentHint":{"type":"boolean"},"openWorldHint":{"type":"boolean"},"readOnlyHint":{"type":"boolean"},"title":{"type":"string"}},"type":"object"},"contracts.ToolCallRecord":{"description":"The new tool call record","properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"arguments":{"description":"Tool arguments","type":"object"},"arguments_truncated":{"description":"ArgumentsTruncated marks Arguments as a placeholder rather than the\narguments the tool was called with. Replaying such a record without\nsupplying arguments explicitly is refused.","type":"boolean"},"config_path":{"description":"Active config file path","type":"string"},"duration":{"description":"Duration in nanoseconds","type":"integer"},"error":{"description":"Error message (failure only)","type":"string"},"execution_type":{"description":"\"direct\" or \"code_execution\"","type":"string"},"id":{"description":"Unique identifier","type":"string"},"mcp_client_name":{"description":"MCP client name from InitializeRequest","type":"string"},"mcp_client_version":{"description":"MCP client version","type":"string"},"mcp_session_id":{"description":"MCP session identifier","type":"string"},"metrics":{"$ref":"#/components/schemas/contracts.TokenMetrics"},"parent_call_id":{"description":"Links nested calls to parent code_execution","type":"string"},"request_id":{"description":"Request correlation ID","type":"string"},"response":{"description":"Tool response (success only)","type":"object"},"response_bytes":{"description":"Marshalled response size before truncation","type":"integer"},"response_truncated":{"description":"ResponseTruncated and ResponseBytes describe a STORAGE-side cut (#1176):\nthe caller received the response whole, and only the persisted copy was\nshortened to tool_call_max_response_size. When ResponseTruncated is true\nthe Response object carries {truncated, original_bytes, preview, note}\ninstead of the upstream result, and ResponseBytes is its size before the\ncut.","type":"boolean"},"server_id":{"description":"Server identity hash","type":"string"},"server_name":{"description":"Human-readable server name","type":"string"},"timestamp":{"description":"When the call was made","type":"string"},"tool_name":{"description":"Tool name (without server prefix)","type":"string"}},"type":"object"},"contracts.UpdateInfo":{"description":"Update information (if available)","properties":{"available":{"description":"Whether an update is available","type":"boolean"},"behind_summary":{"description":"Spec 079 FR-002 — how far behind the running build is. All four are\nadditive (FR-021) and absent when the delta could not be resolved, in\nwhich case every surface renders its pre-delta wording.","type":"string"},"check_error":{"description":"Error message if update check failed","type":"string"},"checked_at":{"description":"When the update check was performed","type":"string"},"install_channel":{"description":"Detected install channel (homebrew, dmg, deb, rpm, docker, go-install, windows-installer, tarball, unknown) — Spec 079 FR-008","type":"string"},"is_prerelease":{"description":"Whether the latest version is a prerelease","type":"boolean"},"latest_version":{"description":"Latest version available (e.g., \"v1.2.3\")","type":"string"},"nudges_suppressed":{"description":"UI surfaces must stay quiet (CI / non-interactive context); machine-readable fields still report the facts — Spec 079 FR-019","type":"boolean"},"release_url":{"description":"URL to the release page","type":"string"},"releases_behind":{"description":"Releases on the offered channel between the running and offered versions","type":"integer"},"releases_behind_saturated":{"description":"ReleasesBehind is a lower bound: the running build predates the scanned release window","type":"boolean"},"update_command":{"description":"One-line update command for the channel; only set when an update is available and the channel has one — Spec 079 FR-009","type":"string"},"weeks_behind":{"description":"Whole weeks between the two releases' publish dates; 0 is a real value, absent means unknown","type":"integer"}},"type":"object"},"contracts.UpdatePolicy":{"description":"UpdatePolicy is the effective, hot-reloadable update policy (Spec 092\nFR-015). Always present: the ` + "`" + `update` + "`" + ` object above is omitted both when\nupdate checking is disabled AND when no check has produced a result\nyet, so its absence cannot tell a client whether it is allowed to run\nits own (e.g. Sparkle feed) check. This field states the answer.","properties":{"channel":{"description":"Channel is the tracked release channel: \"stable\" or \"rc\".","type":"string"},"enabled":{"description":"Enabled is the effective automatic-check kill switch: update_check.enabled\nwith MCPPROXY_DISABLE_AUTO_UPDATE=true winning over it. A user-initiated\n\"Check for Updates\" stays available regardless.","type":"boolean"},"nudges_suppressed":{"description":"NudgesSuppressed asks UI surfaces to stay quiet (CI / non-interactive)\nwhile machine-readable fields keep reporting the facts.","type":"boolean"}},"type":"object"},"contracts.UpstreamError":{"properties":{"error_message":{"type":"string"},"server_name":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.UsageAggregateResponse":{"properties":{"freshness_ms":{"description":"age of the underlying snapshot in ms","type":"integer"},"generated_at":{"type":"string"},"other":{"$ref":"#/components/schemas/contracts.UsageOtherBucket"},"timeline":{"items":{"$ref":"#/components/schemas/contracts.UsageTimeBucket"},"type":"array","uniqueItems":false},"token_source":{"description":"\"bytes\" (size-based proxy, FR-006)","type":"string"},"tokens_saved":{"description":"echoed from ServerTokenMetrics (FR-007)","type":"integer"},"tokens_saved_percentage":{"type":"number"},"tools":{"items":{"$ref":"#/components/schemas/contracts.UsageToolStat"},"type":"array","uniqueItems":false},"total_calls":{"description":"TotalCalls and TotalErrors are the headline counts for the window: the sum\nof the timeline this same response carries, so the tiles and the histogram\nunder them cannot disagree. They are NOT the sum of Tools — that list is\nlifetime-cumulative, upstream-only and truncated to top-N, and summing it\nclient-side is what made the Usage tab print a third number for the same\n24 hours (audit finding F1, #1046). The population is\nstorage.CountsAsCall, shared with ActivitySummaryResponse.CallCount.\n\nTwo bounds on how exactly this matches the Activity Log's own count.\nBoth are bounded and disclosed, unlike the population mismatch they\nreplace, which was unbounded and silent:\n\n  - Window granularity is the timeline's: whole hour buckets, so the span\n    is the requested window rounded up to a bucket edge.\n  - This response is served from a snapshot behind a short read cache\n    (observability.usage_cache_ttl, 5s by default) so the endpoint never\n    scans the activity log per request, while the summary endpoint counts\n    live. Calls that land inside that window appear on the Activity Log\n    first. FreshnessMs and GeneratedAt say how old the figures are, and\n    the Usage tab prints it (\"Updated 3s ago\").","type":"integer"},"total_errors":{"type":"integer"},"window":{"type":"string"}},"type":"object"},"contracts.UsageOtherBucket":{"description":"present only when the list was truncated to top-N","properties":{"calls":{"type":"integer"},"tools_folded":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageTimeBucket":{"properties":{"calls":{"type":"integer"},"errors":{"type":"integer"},"start":{"type":"string"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageToolStat":{"properties":{"avg_req_bytes":{"description":"null when no sized request calls","type":"integer"},"avg_resp_bytes":{"description":"null when sized_calls == 0 (only legacy 0-byte calls)","type":"integer"},"blocked":{"type":"integer"},"calls":{"type":"integer"},"error_rate":{"type":"number"},"errors":{"type":"integer"},"last_used":{"type":"string"},"p50_exceeds":{"type":"boolean"},"p50_ms":{"description":"P50Ms and P95Ms are read off a fixed latency histogram, so they are BUCKET\nBOUNDS, not measured durations: the true percentile is at or below the\nvalue, and a client must render it as a bound (\"≤ 5 ms\"). P50Exceeds /\nP95Exceeds flip that reading for the unbounded overflow bucket, where the\nvalue is the last bound and the truth is above it (\"\u003e 10 s\").","type":"integer"},"p95_exceeds":{"type":"boolean"},"p95_ms":{"type":"integer"},"rejected":{"description":"spec 093: shed by a concurrency limit; never executed, so excluded from calls/latency","type":"integer"},"server":{"type":"string"},"sized_calls":{"description":"calls with known response size (basis for avg_resp_bytes)","type":"integer"},"tool":{"type":"string"},"total_req_bytes":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.ValidateConfigResponse":{"properties":{"errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false},"valid":{"type":"boolean"}},"type":"object"},"contracts.ValidationError":{"properties":{"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"data":{"properties":{"data":{"$ref":"#/components/schemas/contracts.InfoResponse"}},"type":"object"},"httpapi.AddServerRequest":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve\nnew/changed tools past the trust baseline (MCP-2930). Tri-state *bool:\na nil pointer means \"leave unchanged\" on PATCH; a present value\n(including false) is applied. Mirrors config.ServerConfig's *bool\nsemantics — do NOT collapse to a plain bool, or an omitted field would\nsilently reset a previously-set value.","type":"boolean"},"command":{"type":"string"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts is the per-server override for prompt aggregation (F9):\nwhether this server's advertised MCP prompts are merged into mcpproxy's\nprompts/list. Tri-state *bool mirroring config.ServerConfig.ExposePrompts —\na nil pointer means \"leave unchanged\" on PATCH (and \"inherit the default\naggregate behavior\" on create); a present value (including false) is applied.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"init_timeout":{"description":"InitTimeout is the per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override\n(MCP-3322 / GH #760), serialized as a duration string (e.g. \"120s\"). A nil\npointer means \"leave unchanged\" on PATCH; a present value is applied.\nMirrors config.ServerConfig.InitTimeout's *Duration tri-state.","type":"string"},"isolation":{"$ref":"#/components/schemas/httpapi.IsolationRequest"},"max_concurrent_requests":{"description":"MaxConcurrentRequests / QueueSize / QueueTimeout are the per-server\nconcurrency overrides (spec 093 / GH #955, FR-020 scope (c)). Each is\ntri-state: a nil pointer means \"leave unchanged\" on PATCH and \"inherit\nserver_concurrency_defaults\" on create; an explicit 0 disables that\nsetting for this server; a positive value overrides it. Do NOT collapse\nthem to plain values — an omitted field would then silently reset a\nconfigured limit.","type":"integer"},"name":{"type":"string"},"protocol":{"type":"string"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"type":"boolean"},"trust_mode":{"description":"TrustMode is the per-server trust tier (spec 086): \"auto\", \"scan\", or\n\"manual\". Empty means \"leave unchanged\" on PATCH (and inherit the migrated\ndefault on create). A non-empty value is applied to ServerConfig.TrustMode\nand resolved by EffectiveTrustMode (an unrecognized value fails closed to\nmanual). This is the REST seam for changing the trust tier via\nPOST/PATCH /api/v1/servers.","type":"string"},"url":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.CanonicalConfigPath":{"properties":{"description":{"description":"Brief description","type":"string"},"exists":{"description":"Whether the file exists","type":"boolean"},"format":{"description":"Format identifier (e.g., \"claude_desktop\")","type":"string"},"name":{"description":"Display name (e.g., \"Claude Desktop\")","type":"string"},"os":{"description":"Operating system (darwin, windows, linux)","type":"string"},"path":{"description":"Full path to the config file","type":"string"}},"type":"object"},"httpapi.CanonicalConfigPathsResponse":{"properties":{"os":{"description":"Current operating system","type":"string"},"paths":{"description":"List of canonical config paths","items":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPath"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ConnectConflictResponse":{"properties":{"action":{"description":"already_exists | precondition_failed","type":"string"},"data":{"$ref":"#/components/schemas/connect.ConnectResult"},"error":{"description":"Human-readable message","type":"string"},"success":{"description":"Always false","type":"boolean"}},"type":"object"},"httpapi.ConnectRequest":{"properties":{"force":{"description":"Overwrite existing entry","type":"boolean"},"precondition_token":{"description":"PreconditionToken is the opaque token from the preview this write was\nconfirmed against (Spec 091 FR-005). When present, the core rechecks it\nat write time and responds 409 with action \"precondition_failed\" —\nwriting nothing — if the config or the entry MCPProxy would write has\ndrifted since; the caller then re-previews instead of retrying. Absent\nmeans exactly the pre-091 behavior. A replace-classified flow sends this\nTOGETHER with force=true: the token, not the absence of force, is the\noverwrite safety.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.ImportFromPathRequest":{"properties":{"format":{"description":"Optional format hint","type":"string"},"path":{"description":"File path to import from","type":"string"},"rename":{"additionalProperties":{"type":"string"},"description":"Rename maps a server name → new name. Applied after parsing so the\ncaller can disambiguate cross-source name collisions (Spec 046 v2 —\ne.g. \"mcpproxy\" → \"mcpproxy_claude_code\"). Keys are matched against\neither the raw source name (OriginalName) or the sanitized name shown\nin the preview (Server.Name); these differ for names that need\nsanitizing (e.g. \"Figma Desktop\" → \"Figma_Desktop\"). Keys not present\nin the imported set are ignored.","type":"object"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportRequest":{"properties":{"content":{"description":"Raw JSON or TOML content","type":"string"},"format":{"description":"Optional format hint","type":"string"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportResponse":{"properties":{"failed":{"items":{"$ref":"#/components/schemas/configimport.FailedServer"},"type":"array","uniqueItems":false},"format":{"type":"string"},"format_name":{"type":"string"},"imported":{"items":{"$ref":"#/components/schemas/httpapi.ImportedServerResponse"},"type":"array","uniqueItems":false},"skipped":{"items":{"$ref":"#/components/schemas/configimport.SkippedServer"},"type":"array","uniqueItems":false},"summary":{"$ref":"#/components/schemas/configimport.ImportSummary"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportedServerResponse":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"command":{"type":"string"},"fields_skipped":{"items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"type":"string"},"original_name":{"type":"string"},"protocol":{"type":"string"},"source_format":{"type":"string"},"url":{"type":"string"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.IsolationRequest":{"description":"Isolation carries per-server Docker isolation overrides (enabled,\nmode_override, image, network_mode, extra_args, working_dir). A nil\npointer means \"do not touch isolation config\". A present object is\napplied field-by-field ON TOP of the persisted overrides, so omitting a\nfield leaves it alone; clear an individual override by sending it\nexplicitly (` + "`" + `\"enabled\": null` + "`" + `, ` + "`" + `\"image\": \"\"` + "`" + `).","properties":{"enabled":{"description":"Enabled exists ONLY to detect and reject an echoed-back read. It is the\neffective state on the read surface and is never writable; see validate().","type":"boolean"},"enabled_override":{"description":"EnabledOverride is the tri-state per-server override — the RAW value, the\nsame one reads return as ` + "`" + `enabled_override` + "`" + `. It has THREE meaningful wire\nstates, and collapsing them is what silently un-isolated servers\n(GH #1142):\n  - absent          → leave the persisted override untouched\n  - null            → clear the override, back to inheriting the global\n  - true / false    → set an explicit opt-in / opt-out","type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"mode_override":{"description":"ModeOverride sets ` + "`" + `isolation.mode` + "`" + ` (\"docker\" | \"sandbox\" | \"none\").\nnil leaves the persisted value alone; an empty string clears it. An\nunrecognized value is rejected with a 400 rather than persisted.","type":"string"},"network_mode":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.OnboardingMarkRequest":{"properties":{"connect_step_status":{"description":"ConnectStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value. The stored enum is wider (Spec 080\nFR-001): a \"skipped\" request for a previously untouched connect step\nis upgraded server-side to \"completed_external\" when the install\nshows positive evidence of an external connection (Spec 080 FR-002).\n\"completed_external\" is NOT accepted from clients — it must never be\npersisted without that server-verified evidence (edge case: \"never\nguess completed_external without positive evidence\").","type":"string"},"engaged":{"description":"Engaged marks the wizard as engaged (completed or explicitly skipped).\nOnce true, the wizard does not auto-show again.","type":"boolean"},"mark_shown":{"description":"MarkShown records the wizard's first display time if not already set.","type":"boolean"},"server_step_status":{"description":"ServerStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value.","type":"string"}},"type":"object"},"httpapi.SetActiveProfileRequest":{"properties":{"active_profile":{"type":"string"},"profile":{"type":"string"}},"type":"object"},"httpapi.UndoConnectRequest":{"properties":{"backup_name":{"description":"BackupName is the bare filename (filepath.Base) of the backup returned as\nbackup_path by the preceding connect — a name, never a path. Undo resolves\nthe full path server-side by joining it with the client's own config\ndirectory, so a client-supplied value can never contribute a directory\ncomponent (traversal is impossible by construction). Empty means the\nconnect created the file (no prior file existed), so undo removes it.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.UpdateFailureRequest":{"properties":{"stage":{"description":"Stage is the failure stage of the update session.","enum":["appcast","download","install","other"],"type":"string"}},"type":"object"},"management.BulkOperationResult":{"properties":{"errors":{"additionalProperties":{"type":"string"},"description":"Map of server name to error message","type":"object"},"failed":{"description":"Number of failed operations","type":"integer"},"successful":{"description":"Number of successful operations","type":"integer"},"total":{"description":"Total servers processed","type":"integer"}},"type":"object"},"observability.HealthResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"observability.HealthStatus":{"properties":{"error":{"type":"string"},"latency":{"type":"string"},"name":{"type":"string"},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"}},"type":"object"},"observability.ReadinessResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"ready\" or \"not_ready\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"secureenv.EnvConfig":{"description":"Environment configuration for secure variable filtering","properties":{"allowed_system_vars":{"items":{"type":"string"},"type":"array","uniqueItems":false},"custom_vars":{"additionalProperties":{"type":"string"},"type":"object"},"enhance_path":{"description":"Enable PATH enhancement for Launchd scenarios","type":"boolean"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned upstream servers (MCP-2769). It is OFF by\ndefault and deliberately kept out of the AllowedSystemVars default list:\nproxy URLs frequently carry credentials (http://user:pass@proxy), so\nforwarding them to every stdio upstream is a credential-leak risk. When\nenabled, values are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"inherit_system_safe":{"type":"boolean"}},"type":"object"},"telemetry.FeedbackContext":{"properties":{"arch":{"type":"string"},"connected_server_count":{"type":"integer"},"edition":{"type":"string"},"os":{"type":"string"},"routing_mode":{"type":"string"},"server_count":{"type":"integer"},"version":{"type":"string"}},"type":"object"},"telemetry.FeedbackRequest":{"properties":{"category":{"description":"bug, feature, other","type":"string"},"context":{"$ref":"#/components/schemas/telemetry.FeedbackContext"},"email":{"type":"string"},"message":{"type":"string"}},"type":"object"},"telemetry.FeedbackResponse":{"properties":{"error":{"type":"string"},"issue_url":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"description":"API key authentication via query parameter. Use ?apikey=your-key","in":"query","name":"apikey","type":"apiKey"}}},
     "info": {"contact":{"name":"MCPProxy Support","url":"https://github.com/smart-mcp-proxy/mcpproxy-go"},"description":"{{escape .Description}}","license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"},"title":"{{.Title}}","version":"{{.Version}}"},
     "externalDocs": {"description":"","url":""},
     "paths": {"/api/v1/activity":{"get":{"description":"Returns paginated list of activity records with optional filtering","parameters":[{"description":"Filter by activity type(s), comma-separated for multiple (Spec 024)","in":"query","name":"type","schema":{"enum":["tool_call","policy_decision","quarantine_change","server_change","system_start","system_stop","internal_tool_call","config_change","preflight","prompt_get"],"type":"string"}},{"description":"Filter by server name","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter by tool name","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter by MCP transport session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by work session (one client, one project, across reconnects)","in":"query","name":"work_session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"enum":["success","error","blocked","rejected"],"type":"string"}},{"description":"Filter by intent operation type (Spec 018)","in":"query","name":"intent_type","schema":{"enum":["read","write","destructive"],"type":"string"}},{"description":"Filter by HTTP request ID for log correlation (Spec 021)","in":"query","name":"request_id","schema":{"type":"string"}},{"description":"Filter by parent call id — returns the sub-calls one code_execution issued","in":"query","name":"parent_id","schema":{"type":"string"}},{"description":"Include successful call_tool_* internal tool calls (default: false, excluded to avoid duplicates)","in":"query","name":"include_call_tool","schema":{"type":"boolean"}},{"description":"Filter by sensitive data detection (true=has detections, false=no detections)","in":"query","name":"sensitive_data","schema":{"type":"boolean"}},{"description":"Filter by specific detection type (e.g., 'aws_access_key', 'credit_card')","in":"query","name":"detection_type","schema":{"type":"string"}},{"description":"Filter by severity level","in":"query","name":"severity","schema":{"enum":["critical","high","medium","low"],"type":"string"}},{"description":"Filter by agent token name (Spec 028)","in":"query","name":"agent","schema":{"type":"string"}},{"description":"Filter by auth type (Spec 028)","in":"query","name":"auth_type","schema":{"enum":["admin","agent"],"type":"string"}},{"description":"Filter activities after this time (RFC3339)","in":"query","name":"start_time","schema":{"type":"string"}},{"description":"Filter activities before this time (RFC3339)","in":"query","name":"end_time","schema":{"type":"string"}},{"description":"Maximum records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Pagination offset (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Omit arguments, response and metadata except a contextual whitelist (intent.reason, intent.operation_type, decision, reason, client_name, client_version) (default: false). For clients that render summary fields only; has_sensitive_data is still derived before metadata is dropped.","in":"query","name":"exclude_payloads","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"List activity records","tags":["Activity"]}},"/api/v1/activity/export":{"get":{"description":"Exports activity records in JSON Lines or CSV format for compliance","parameters":[{"description":"Export format: json (default) or csv","in":"query","name":"format","schema":{"type":"string"}},{"description":"Filter by activity type","in":"query","name":"type","schema":{"type":"string"}},{"description":"Filter by server name","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter by tool name","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter by MCP transport session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by work session (one client, one project, across reconnects)","in":"query","name":"work_session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"type":"string"}},{"description":"Filter by HTTP request ID for log correlation (Spec 021)","in":"query","name":"request_id","schema":{"type":"string"}},{"description":"Filter by parent call id — exports the sub-calls one code_execution issued","in":"query","name":"parent_id","schema":{"type":"string"}},{"description":"Filter activities after this time (RFC3339)","in":"query","name":"start_time","schema":{"type":"string"}},{"description":"Filter activities before this time (RFC3339)","in":"query","name":"end_time","schema":{"type":"string"}},{"description":"Maximum records to export (1-50000, default 10000)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Pagination offset (default 0)","in":"query","name":"offset","schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"string"}},"application/x-ndjson":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}}},"description":"Streamed activity records"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Export activity records","tags":["Activity"]}},"/api/v1/activity/summary":{"get":{"description":"Returns aggregated activity statistics for a time period","parameters":[{"description":"Time period: 1h, 24h (default), 7d, 30d","in":"query","name":"period","schema":{"type":"string"}},{"description":"Group by: server, tool (optional)","in":"query","name":"group_by","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get activity summary statistics","tags":["Activity"]}},"/api/v1/activity/usage":{"get":{"description":"Returns the actor-owned usage aggregate (per-tool rollup + timeline + tokens-saved headline) for the Web UI usage graphs (Spec 069). Served from an in-memory snapshot — never a per-request full-log scan. Per-tool metrics are lifetime-cumulative; ` + "`" + `window` + "`" + ` scopes the timeline and filters the tool list to tools active within the span.","parameters":[{"description":"Time window for timeline + tool-list membership","in":"query","name":"window","schema":{"enum":["24h","7d","all"],"type":"string"}},{"description":"Filter to one server","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter to one tool","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter to tools with activity of this status","in":"query","name":"status","schema":{"enum":["success","error","blocked","rejected"],"type":"string"}},{"description":"Top-N tools by sort key; remainder folded into 'other' (default 20)","in":"query","name":"top","schema":{"type":"integer"}},{"description":"Ranking key for the per-tool list","in":"query","name":"sort","schema":{"enum":["calls","resp_bytes","error_rate","p95"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get usage statistics aggregate","tags":["Activity"]}},"/api/v1/activity/{id}":{"get":{"description":"Returns full details for a single activity record","parameters":[{"description":"Activity record ID (ULID)","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Not Found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get activity record details","tags":["Activity"]}},"/api/v1/annotations/coverage":{"get":{"description":"Reports how many upstream tools have MCP annotations vs don't, broken down by server","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Annotation coverage report"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get annotation coverage report","tags":["annotations"]}},"/api/v1/code/scripts":{"get":{"description":"List the stored scripts available to the code_execution tool. Scripts are ` + "`" + `\u003cname\u003e.js` + "`" + ` / ` + "`" + `\u003cname\u003e.ts` + "`" + ` files in the ` + "`" + `scripts/` + "`" + ` directory next to the active configuration file. Entries are advisory: ` + "`" + `ok` + "`" + ` scripts are invocable, ` + "`" + `ambiguous` + "`" + ` names have both extensions, and ` + "`" + `invalid` + "`" + ` ones report why (empty, oversized, unreadable, non-regular). Read-only — there is no write surface for stored scripts.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Stored scripts and the directory they were read from"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List stored code-execution scripts","tags":["code"]}},"/api/v1/config":{"get":{"description":"Retrieves the current MCPProxy configuration including all server definitions, global settings, and runtime parameters","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetConfigResponse"}}},"description":"Configuration retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read the configuration document"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get current configuration","tags":["config"]},"patch":{"description":"Deep-merges only the fields present in the request body onto the live in-memory configuration and routes the result through the existing apply pipeline (validation, change detection, disk persistence, hot-reload). Fields the client omits — including masked secrets such as ` + "`" + `api_key` + "`" + ` and secret request headers — are preserved verbatim. Nested objects are merged recursively; arrays and scalars replace wholesale.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Partial configuration with only the fields to change","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Configuration patch applied (inspect validation_errors for rejected values)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload or empty patch"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to read or apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Partially update configuration","tags":["config"]}},"/api/v1/config/apply":{"post":{"description":"Applies a new MCPProxy configuration. Validates and persists the configuration to disk. Some changes apply immediately, while others may require a restart. Returns detailed information about applied changes and restart requirements.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/config.Config"}}},"description":"Configuration to apply","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Configuration applied successfully with change details"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Apply configuration","tags":["config"]}},"/api/v1/config/docker-isolation":{"patch":{"description":"Convenience endpoint to flip ` + "`" + `docker_isolation.enabled` + "`" + ` without resending the full config. Persists to disk via the existing config writer — the file watcher then hot-reloads the change. Returns the new state and whether a restart is required for existing connections to pick it up.","requestBody":{"content":{"application/json":{"schema":{"properties":{"enabled":{"type":"boolean"}},"type":"object"}}},"description":"New isolation state","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Isolation toggle applied"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Toggle global Docker isolation","tags":["config"]}},"/api/v1/config/validate":{"post":{"description":"Validates a provided MCPProxy configuration without applying it. Checks for syntax errors, invalid server definitions, conflicting settings, and other configuration issues.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/config.Config"}}},"description":"Configuration to validate","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ValidateConfigResponse"}}},"description":"Configuration validation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Validation failed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Validate configuration","tags":["config"]}},"/api/v1/connect":{"get":{"description":"Returns the connection status for all known MCP client applications.\nEach entry indicates whether the client config file exists and whether\nMCPProxy is currently registered in it.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"List of ClientStatus objects"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List client connection status","tags":["connect"]}},"/api/v1/connect/{client}":{"delete":{"description":"Remove the MCPProxy entry from the specified client's configuration file.\nCreates a backup of the existing config before modifying.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectRequest"}}},"description":"Optional parameters (server_name)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client or entry not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disconnect MCPProxy from a client","tags":["connect"]},"get":{"description":"Resolves one client's status by reading its config file on demand.\nThis is the only Connect endpoint that opens a client config file, so\non macOS it is the sole place an App-Data privacy prompt may legitimately\nappear (scoped to this user action). Resolves access_state to\naccessible|absent|denied|malformed and populates remediation when denied.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ClientStatus"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get a single client's connection status (on-demand)","tags":["connect"]},"post":{"description":"Register MCPProxy as an MCP server in the specified client's configuration file.\nCreates a backup of the existing config before modifying.\nOptionally accepts precondition_token from a preview (Spec 091): when supplied,\nthe core rechecks the raw pre-write state and the entry it would write, and\nrefuses a drifted write with 409 before taking any backup. The 409 body's\naction discriminates the two conflict kinds: \"precondition_failed\" (stale\npreview — re-preview, do not retry) vs \"already_exists\" (entry present — pass\nforce=true). force=true never rescues a stale token.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectRequest"}}},"description":"Optional connection parameters (server_name, force, precondition_token)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectConflictResponse"}}},"description":"Conflict: action=already_exists (use force=true) or action=precondition_failed (preview is stale; re-preview)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Connect MCPProxy to a client","tags":["connect"]}},"/api/v1/connect/{client}/preview":{"get":{"description":"Returns the exact entry a subsequent connect would add to the client's\nconfig — target path, server key, entry name, and entry contents — WITHOUT\nmodifying the file or creating a backup (Spec 078 US1). The embedded API key\nis masked in the payload; contains_api_key flags that a credential is written.\nentry_exists distinguishes a create from an overwrite of a same-named entry.\nReads the config on demand to classify create-vs-overwrite, so on macOS this\nmay raise an App-Data privacy prompt; a denial returns 403 + remediation.\nSpec 091 adds three fields: existing_entry_summary (present only when\nentry_exists — a sanitized, non-secret projection of the entry being replaced:\nits name, type, endpoint with query/userinfo stripped, command, and header and\nenv NAMES, never values); precondition_token (always present — an opaque keyed\ndigest of the raw pre-write state and the pending entry, echoed back on POST\nconnect to detect drift); and connect_refusal (present when the write would\nrefuse regardless of intent, e.g. a non-create-capable client with no config —\ntreat its presence as \"Connect unavailable\").","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}},{"description":"Entry name to preview (defaults to mcpproxy); mirror the value passed to POST connect","in":"query","name":"server_name","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectPreview"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Preview the change a connect would make (no write)","tags":["connect"]}},"/api/v1/connect/{client}/undo":{"post":{"description":"Reverts the connect that produced the named backup (Spec 078 US3):\nrestores the client config byte-for-byte from that backup, or — when\nbackup_name is empty because the connect created the file — deletes the\ncreated file. backup_name is the bare filename of the backup the connect\nreturned (never a path); undo resolves the full path server-side inside\nthe client's own config directory, so a client value cannot escape it.\nRefuses with 409 when the config changed since the connect (undo never\nclobbers later edits; use DELETE /connect/{client} for a surgical entry\nremoval instead). Takes its own safety backup first; its path is returned\nas backup_path in the result.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.UndoConnectRequest"}}},"description":"Undo parameters (server_name, backup_name = the bare filename of the backup the preceding connect returned)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult (action restored|deleted)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (e.g. backup_name is a path, or not a backup of this client's config)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client or backup no longer exists"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Config changed since connect; undo refused"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Undo a connect, restoring the pre-connect config","tags":["connect"]}},"/api/v1/diagnostics":{"get":{"description":"Get comprehensive health diagnostics including upstream errors, OAuth requirements, missing secrets, and Docker status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.Diagnostics"}}},"description":"Health diagnostics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get health diagnostics","tags":["diagnostics"]}},"/api/v1/docker/status":{"get":{"description":"Retrieve current Docker availability and recovery status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Docker status information"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get Docker status","tags":["docker"]}},"/api/v1/doctor":{"get":{"description":"Get comprehensive health diagnostics including upstream errors, OAuth requirements, missing secrets, and Docker status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.Diagnostics"}}},"description":"Health diagnostics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get health diagnostics","tags":["diagnostics"]}},"/api/v1/feedback":{"post":{"description":"Submit a bug report, feature request, or general feedback","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/telemetry.FeedbackRequest"}}},"description":"Feedback request","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/telemetry.FeedbackResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Bad Request"},"429":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"Submit feedback","tags":["feedback"]}},"/api/v1/index/search":{"get":{"description":"Search across all upstream MCP server tools using BM25 keyword search","parameters":[{"description":"Search query","in":"query","name":"q","required":true,"schema":{"type":"string"}},{"description":"Maximum number of results","in":"query","name":"limit","schema":{"default":10,"maximum":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SearchToolsResponse"}}},"description":"Search results"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing query parameter)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Search for tools","tags":["tools"]}},"/api/v1/info":{"get":{"description":"Get essential server metadata including version, web UI URL, endpoint addresses, and update availability\nweb_ui_url carries the ?apikey= credential ONLY for an authenticated admin; a scoped agent token receives the bare URL\nThis endpoint is designed for tray-core communication and version checking\nUse refresh=true query parameter to force an immediate update check against GitHub\nThe launched_by field reports durable launch provenance (\"tray\", \"installer\", or \"\" for user-launched/unknown)","parameters":[{"description":"Force immediate update check against GitHub","in":"query","name":"refresh","schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"Server information with optional update info"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server information","tags":["status"]}},"/api/v1/onboarding/mark":{"post":{"description":"Updates wizard engagement and per-step status. Once engaged is\ntrue, the wizard does not auto-show again, even if state regresses.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.OnboardingMarkRequest"}}},"description":"Mark request","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Updated OnboardingStateResponse"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read onboarding state"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Mark onboarding wizard state (Spec 046)","tags":["onboarding"]}},"/api/v1/onboarding/state":{"get":{"description":"Returns the wizard engagement record alongside live predicates\n(whether any client is connected, whether any server is configured),\nplus a derived ShouldShowWizard flag the frontend can rely on.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"OnboardingStateResponse"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read onboarding state"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get onboarding wizard state and predicates (Spec 046)","tags":["onboarding"]}},"/api/v1/preflight":{"post":{"description":"Deterministic, side-effect-free availability check for a caller-supplied list of tool IDs (Spec 098). Performs zero upstream calls and mutates no runtime state. HTTP status reports whether the CHECK executed: a fully blocked set is still 200, with the availability verdict in the body. Every executed preflight writes an activity record before the response is returned.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.PreflightRequest"}}},"description":"Tool IDs (1-100 before dedup), optional profile, annotation policy filters and wait budget","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"Preflight verdict and per-tool results"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Validation error (malformed, oversized, doubled or unknown-field body; empty or oversized tool list; conflicting duplicate pins; unknown profile; wait_ms out of range)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Missing or invalid credentials"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Runtime unavailable, evaluator infrastructure read failure, or the activity record could not be persisted"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Preflight required tools","tags":["tools"]}},"/api/v1/profiles":{"get":{"description":"List all configured profiles with their effective servers and indexed tool count (Profiles v2). A profile scopes tool discovery and calls to a named subset of upstream servers.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Profile list"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Configuration unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List configured profiles","tags":["profiles"]}},"/api/v1/profiles/active":{"get":{"description":"Get the server-level default active profile used by UI surfaces (Web UI / tray). Empty string means \"all servers\". Note: within a live MCP session, the set_profile tool selection takes precedence over this default.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Active profile"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get the default active profile","tags":["profiles"]},"put":{"description":"Set the server-level default active profile for UI surfaces. The slug must match a configured profile; pass an empty string to clear. This does not affect live MCP sessions, which use the set_profile tool.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.SetActiveProfileRequest"}}},"description":"Profile slug to activate (empty clears)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Active profile updated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid request body"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot change the active profile)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown profile"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Set the default active profile","tags":["profiles"]}},"/api/v1/registries":{"get":{"description":"Retrieves list of all MCP server registries that can be browsed for discovering and installing new upstream servers. Includes registry metadata, server counts, and API endpoints.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetRegistriesResponse"}}},"description":"Registries retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to list registries"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List available MCP server registries","tags":["registries"]},"post":{"description":"Adds a generic modelcontextprotocol/registry v0.1 https endpoint as a custom registry (MCP-866). The source is always tagged custom/unverified, so every server discovered through it lands quarantined and can never skip quarantine.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.AddRegistrySourceRequest"}}},"description":"Registry source (https url + optional protocol/id/name)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source added"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"invalid_registry_url"},"403":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/contracts.ErrorResponse"},{"$ref":"#/components/schemas/contracts.ErrorResponse"}]}}},"description":"Forbidden (agent tokens cannot mutate registries)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin | duplicate_registry"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add a user-supplied registry source","tags":["registries"]}},"/api/v1/registries/{id}":{"delete":{"description":"Removes a custom/unverified registry previously added via add-source (MCP-1057). Built-in registries are refused with registry_shadows_builtin; an unknown id yields registry_not_found. The change is persisted copy-on-write.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source removed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registries_locked"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Remove a user-added custom registry source","tags":["registries"]},"put":{"description":"Updates a custom registry previously added via add-source (MCP-1072): name, url, servers-url. Empty fields are left unchanged. Built-in registries are refused with registry_shadows_builtin; an unknown id yields registry_not_found; a non-https url yields invalid_registry_url. The change is persisted copy-on-write.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.EditRegistrySourceRequest"}}},"description":"Fields to update (name/url/servers_url; empty = unchanged)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source updated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required | invalid_registry_url"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registries_locked"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Edit a user-added custom registry source","tags":["registries"]}},"/api/v1/registries/{id}/refresh":{"post":{"description":"Invalidates the cached server lists for a registry so the next search re-fetches fresh data from the source (spec 070 FR-007). Returns how many cache entries were dropped.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.RefreshRegistryResponse"}}},"description":"Registry cache refreshed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to refresh registry cache"}},"summary":"Refresh a registry's cached server list","tags":["registries"]}},"/api/v1/registries/{id}/servers":{"get":{"description":"Searches for MCP servers within a specific registry by keyword or tag. Returns server metadata including installation commands, source code URLs, and npm package information for easy discovery and installation.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Search query keyword","in":"query","name":"q","schema":{"type":"string"}},{"description":"Filter by tag","in":"query","name":"tag","schema":{"type":"string"}},{"description":"Maximum number of results (default 10)","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SearchRegistryServersResponse"}}},"description":"Servers retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to search servers"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Search MCP servers in a registry","tags":["registries"]}},"/api/v1/registries/{id}/servers/{serverId}/add":{"post":{"description":"Resolves a registry server reference server-side, re-derives a validated config, and persists it quarantined (spec 070 keystone). The client never sends a config blob — command/args/url and the quarantine flag are derived from the registry entry, not the request.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Server ID within the registry","in":"path","name":"serverId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.AddFromRegistryRequest"}}},"description":"Optional overrides (name, env, enabled)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server added (quarantined)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"no_install_info | missing_required_input | duplicate_name"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot add servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found | server_not_found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add an upstream server from a registry reference","tags":["registries"]}},"/api/v1/routing":{"get":{"description":"Get the current routing mode and available MCP endpoints.\nrouting_mode is what /mcp is actually serving; pending_routing_mode carries a\nrestart-pending value persisted on disk (empty when there is none).\ntool_response_mode and direct_tool_response_mode report the two serialization axes, resolved.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Routing mode information"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get routing mode information","tags":["status"]}},"/api/v1/secrets":{"post":{"description":"Stores a secret value in the operating system's secure keyring. The secret can then be referenced in configuration using ${keyring:secret-name} syntax. Automatically notifies runtime to restart affected servers.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret stored successfully with reference syntax"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload, missing name/value, or unsupported type"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver not available or failed to store secret"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Store a secret in OS keyring","tags":["secrets"]}},"/api/v1/secrets/{name}":{"delete":{"description":"Deletes a secret from the operating system's secure keyring. Automatically notifies runtime to restart affected servers. Only keyring type is supported for security.","parameters":[{"description":"Name of the secret to delete","in":"path","name":"name","required":true,"schema":{"type":"string"}},{"description":"Secret type (only 'keyring' supported, defaults to 'keyring')","in":"query","name":"type","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret deleted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Missing secret name or unsupported type"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver not available or failed to delete secret"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Delete a secret from OS keyring","tags":["secrets"]}},"/api/v1/servers":{"get":{"description":"Get a list of all configured upstream MCP servers with their connection status and statistics","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServersResponse"}}},"description":"Server list with statistics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List all upstream MCP servers","tags":["servers"]},"post":{"description":"Add a new MCP upstream server to the configuration. New servers are quarantined by default for security. Isolation: ` + "`" + `isolation.enabled` + "`" + ` is READ-ONLY (it reports the effective state on reads) and is rejected with 400; set the per-server override via ` + "`" + `isolation.enabled_override` + "`" + ` (true | false | null to clear, omit to leave unchanged). An unrecognized ` + "`" + `isolation.mode_override` + "`" + ` is rejected with 400.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.AddServerRequest"}}},"description":"Server configuration","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server added successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid configuration"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Conflict - server with this name already exists"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add a new upstream server","tags":["servers"]}},"/api/v1/servers/disable_all":{"post":{"description":"Disable all configured upstream MCP servers with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk disable results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disable all servers","tags":["servers"]}},"/api/v1/servers/enable_all":{"post":{"description":"Enable all configured upstream MCP servers with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk enable results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable all servers","tags":["servers"]}},"/api/v1/servers/import":{"post":{"description":"Import MCP server configurations from a Claude Desktop, Claude Code, Cursor IDE, Codex CLI, or Gemini CLI configuration file","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}},{"description":"Force format (claude-desktop, claude-code, cursor, codex, gemini)","in":"query","name":"format","schema":{"type":"string"}},{"description":"Comma-separated list of server names to import","in":"query","name":"server_names","schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"file"}}},"description":"Configuration file to import","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid file or format"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from uploaded configuration file","tags":["servers"]}},"/api/v1/servers/import/json":{"post":{"description":"Import MCP server configurations from raw JSON or TOML content (useful for pasting configurations)","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportRequest"}}},"description":"Import request with content","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid content or format"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from JSON/TOML content","tags":["servers"]}},"/api/v1/servers/import/path":{"post":{"description":"Import MCP server configurations by reading a file from the server's filesystem","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportFromPathRequest"}}},"description":"Import request with file path","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid path or format"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"File not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from a file path","tags":["servers"]}},"/api/v1/servers/import/paths":{"get":{"description":"Returns well-known configuration file paths for supported formats with existence check","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPathsResponse"}}},"description":"Canonical config paths"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get canonical config file paths","tags":["servers"]}},"/api/v1/servers/reconnect":{"post":{"description":"Force reconnection to all upstream MCP servers","parameters":[{"description":"Reason for reconnection","in":"query","name":"reason","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"All servers reconnected successfully"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Reconnect all servers","tags":["servers"]}},"/api/v1/servers/restart_all":{"post":{"description":"Restart all configured upstream MCP servers sequentially with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk restart results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Restart all servers","tags":["servers"]}},"/api/v1/servers/{id}":{"delete":{"description":"Remove an MCP upstream server from the configuration. This stops the server if running and removes it from config.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server removed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Remove an upstream server","tags":["servers"]},"patch":{"description":"Update specific fields of an existing upstream MCP server configuration. Isolation: ` + "`" + `isolation.enabled` + "`" + ` is READ-ONLY (it reports the effective state on reads) and is rejected with 400; set the per-server override via ` + "`" + `isolation.enabled_override` + "`" + ` (true | false | null to clear, omit to leave unchanged). An unrecognized ` + "`" + `isolation.mode_override` + "`" + ` is rejected with 400.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.AddServerRequest"}}},"description":"Fields to update (all optional)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server updated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - no fields or invalid body"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Partially update an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/config-to-secret":{"post":{"description":"Atomically reads the real value from the server config, stores it in the OS keyring, and rewrites the config field to ` + "`" + `${keyring:\u003cname\u003e}` + "`" + `. Unblocks the UI's Convert-to-secret affordance for values the API redacts on the read path.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret stored, config updated with reference"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad scope/key/secret_name, or value is already a reference / empty"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server or key not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver or config update failed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Convert a header / env value to a keyring secret","tags":["servers"]}},"/api/v1/servers/{id}/disable":{"post":{"description":"Disable a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server disabled successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disable an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/discover-tools":{"post":{"description":"Manually trigger tool discovery and indexing for a specific upstream MCP server. This forces an immediate refresh of the server's tool cache.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Tool discovery triggered successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot discover tools)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to discover tools"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Discover tools for a specific server","tags":["servers"]}},"/api/v1/servers/{id}/enable":{"post":{"description":"Enable a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server enabled successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/login":{"post":{"description":"Initiate OAuth authentication flow for a specific upstream MCP server. Returns structured OAuth start response with correlation ID for tracking.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.OAuthStartResponse"}}},"description":"OAuth login initiated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.OAuthFlowError"}}},"description":"OAuth error (client_id required, DCR failed, etc.)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Trigger OAuth login for server","tags":["servers"]}},"/api/v1/servers/{id}/logout":{"post":{"description":"Clear OAuth authentication token and disconnect a specific upstream MCP server. The server will need to re-authenticate before tools can be used again.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"OAuth logout completed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled or read-only mode)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Clear OAuth token and disconnect server","tags":["servers"]}},"/api/v1/servers/{id}/logs":{"get":{"description":"Retrieve log entries for a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Number of log lines to retrieve","in":"query","name":"tail","schema":{"default":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerLogsResponse"}}},"description":"Server logs retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server logs","tags":["servers"]}},"/api/v1/servers/{id}/quarantine":{"post":{"description":"Place a specific upstream MCP server in quarantine to prevent tool execution","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server quarantined successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Quarantine a server","tags":["servers"]}},"/api/v1/servers/{id}/refresh":{"post":{"description":"Re-discover and re-index a specific upstream MCP server's tools without changing any security state. Alias of discover-tools, named for the upstream_servers 'refresh' operation; use it to make just-approved tools searchable immediately.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Tool refresh triggered successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot refresh)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to refresh tools"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Refresh a server's tools","tags":["servers"]}},"/api/v1/servers/{id}/restart":{"post":{"description":"Restart the connection to a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server restarted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Restart an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/tool-calls":{"get":{"description":"Retrieves tool call history filtered by upstream server ID. Returns recent tool executions for the specified server including timestamps, arguments, results, and errors. Useful for server-specific debugging and monitoring.","parameters":[{"description":"Upstream server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Maximum number of records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerToolCallsResponse"}}},"description":"Server tool calls retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get server tool calls"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call history for specific server","tags":["tool-calls"]}},"/api/v1/servers/{id}/tools":{"get":{"description":"Retrieve all available tools for a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerToolsResponse"}}},"description":"Server tools retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/block":{"post":{"description":"Atomically approves AND disables the given tools (or all pending/changed tools when block_all=true) for a server. The approve and disable land in a single write per tool, so a tool is never left in the approved+enabled state. The \"blocked\" field counts tools actually blocked.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Block result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Block (approve+disable) tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/disable_all":{"post":{"description":"Bulk-toggles every known tool of a server. The \"changed\" field","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Operation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable or disable all tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/enable_all":{"post":{"description":"Bulk-toggles every known tool of a server. The \"changed\" field","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Operation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable or disable all tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/unquarantine":{"post":{"description":"Remove a specific upstream MCP server from quarantine to allow tool execution","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server unquarantined successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Unquarantine a server","tags":["servers"]}},"/api/v1/sessions":{"get":{"description":"Retrieves paginated list of active and recent MCP client sessions. Each session represents a connection from an MCP client to MCPProxy, tracking initialization time, tool calls, and connection status.","parameters":[{"description":"Maximum number of sessions to return (1-100, default 10)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Number of sessions to skip for pagination (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Filter by session status","in":"query","name":"status","schema":{"enum":["active","closed"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetSessionsResponse"}}},"description":"Sessions retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid status filter"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read MCP session history"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get sessions"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get active MCP sessions","tags":["sessions"]}},"/api/v1/sessions/{id}":{"get":{"description":"Retrieves detailed information about a specific MCP client session including initialization parameters, connection status, tool call count, and activity timestamps.","parameters":[{"description":"Session ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetSessionDetailResponse"}}},"description":"Session details retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Session ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read MCP session history"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Session not found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get MCP session details by ID","tags":["sessions"]}},"/api/v1/stats/tokens":{"get":{"description":"Retrieve token savings statistics across all servers and sessions","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Token statistics"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read deployment-wide token statistics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get token savings statistics","tags":["stats"]}},"/api/v1/status":{"get":{"description":"Get comprehensive server status including running state, listen address, upstream statistics, and timestamp","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server status information"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server status","tags":["status"]}},"/api/v1/telemetry/payload":{"get":{"description":"Render the exact JSON heartbeat payload that mcpproxy would next send to the telemetry endpoint, without making a network call. Counters in the payload reflect the current in-memory state. Spec 042.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Telemetry heartbeat payload"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read the deployment telemetry payload"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Telemetry service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Preview next telemetry heartbeat payload","tags":["telemetry"]}},"/api/v1/telemetry/update-failure":{"post":{"description":"Records one terminal update-session failure, identified only by its\nstage (appcast, download, install, other). The body carries no error\ntext, URL, or version — the stage is the only value transmitted.\nReturns 204 both when the occurrence was durably persisted and when\ntelemetry is inactive at event time (config opt-out, environment\nopt-out, CI, or dev build), in which case nothing is recorded.\nCallers cannot and need not distinguish the two.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.UpdateFailureRequest"}}},"description":"Update failure stage","required":true},"responses":{"204":{"description":"Accepted (recorded, or a deliberate no-op while telemetry is inactive)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Malformed body, unknown field, trailing value, or stage outside the closed set"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Persistence failure"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Record a desktop auto-update failure occurrence (Spec 095)","tags":["telemetry"]}},"/api/v1/tool-calls":{"get":{"description":"Retrieves paginated tool call history across all upstream servers or filtered by session ID. Includes execution timestamps, arguments, results, and error information for debugging and auditing.","parameters":[{"description":"Maximum number of records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Number of records to skip for pagination (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Filter tool calls by MCP session ID","in":"query","name":"session_id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetToolCallsResponse"}}},"description":"Tool calls retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get tool calls"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call history","tags":["tool-calls"]}},"/api/v1/tool-calls/{id}":{"get":{"description":"Retrieves detailed information about a specific tool call execution including full request arguments, response data, execution time, and any errors encountered.","parameters":[{"description":"Tool call ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetToolCallDetailResponse"}}},"description":"Tool call details retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Tool call ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Tool call not found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call details by ID","tags":["tool-calls"]}},"/api/v1/tool-calls/{id}/replay":{"post":{"description":"Re-executes a previous tool call with optional modified arguments. Useful for debugging and testing tool behavior with different inputs. Creates a new tool call record linked to the original.","parameters":[{"description":"Original tool call ID to replay","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ReplayToolCallRequest"}}},"description":"Optional modified arguments for replay"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ReplayToolCallResponse"}}},"description":"Tool call replayed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Tool call ID required or invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Shed by a concurrency limit (Retry-After header carries the wait hint)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to replay tool call"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Replay a tool call","tags":["tool-calls"]}},"/api/v1/tools":{"get":{"description":"Consolidated, read-only listing of all tools from every configured server (including disabled servers and disabled/config-denied tools), enriched with approval state and 30-day usage. Backs the global Tools page and the CLI global ` + "`" + `tools list` + "`" + ` (spec 050, issue #437).","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GlobalToolsResponse"}}},"description":"All tools across all servers"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Could not enumerate servers"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List every tool across all servers","tags":["tools"]}},"/api/v1/tools/call":{"post":{"description":"Execute a tool on an upstream MCP server (wrapper around MCP tool calls)","requestBody":{"content":{"application/json":{"schema":{"properties":{"arguments":{"type":"object"},"tool_name":{"type":"string"}},"type":"object"}}},"description":"Tool call request with tool name and arguments","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Tool call result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (invalid payload or missing tool name)"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Shed by a concurrency limit (Retry-After header carries the wait hint)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error or tool execution failure"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Call a tool","tags":["tools"]}},"/healthz":{"get":{"description":"Get comprehensive health status including all component health (Kubernetes-compatible liveness probe)","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.HealthResponse"}}},"description":"Service is healthy"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.HealthResponse"}}},"description":"Service is unhealthy"}},"summary":"Get health status","tags":["health"]}},"/readyz":{"get":{"description":"Get readiness status including all component readiness checks (Kubernetes-compatible readiness probe)","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.ReadinessResponse"}}},"description":"Service is ready"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.ReadinessResponse"}}},"description":"Service is not ready"}},"summary":"Get readiness status","tags":["health"]}}},
diff --git a/oas/swagger.yaml b/oas/swagger.yaml
index 33b9a74c2..90435f547 100644
--- a/oas/swagger.yaml
+++ b/oas/swagger.yaml
@@ -383,6 +383,17 @@ components:
             type: string
           type: array
           uniqueItems: false
+        trusted_proxies:
+          description: |-
+            TrustedProxies lists the CIDRs or IP addresses whose X-Forwarded-For /
+            X-Real-IP / X-Forwarded-Proto / X-Forwarded-Host headers are believed
+            (Spec 107 FR-027). Empty (default) trusts nobody. Edition-neutral, live
+            (hot-reloadable). Env override: MCPPROXY_TRUSTED_PROXIES (comma-separated).
+            The one reader is ForwardedHeaders; validation is validateTrustedProxies.
+          items:
+            type: string
+          type: array
+          uniqueItems: false
         update_check:
           $ref: '#/components/schemas/config.UpdateCheckConfig'
       type: object
diff --git a/roadmap.yaml b/roadmap.yaml
index 8859ed3da..33018288c 100644
--- a/roadmap.yaml
+++ b/roadmap.yaml
@@ -810,13 +810,14 @@ epics:
     tasks:
       - id: sso-pr-a-freeze-cut
         title: PR-A freeze/cut latent code + config normaliser + per-owner token cap (US5, US6)
-        status: in_progress
+        status: done
         depends_on: []
         pr: "#1287"
       - id: sso-pr-b-oidc-front-door
         title: PR-B generic OIDC provider + front door behind ingress + telemetry v13 (US2, US7)
-        status: todo
+        status: in_progress
         depends_on: [sso-pr-a-freeze-cut]
+        pr: "#1292"
       - id: sso-pr-c-group-allowlist
         title: PR-C one entitlement predicate, group grants, tenant Web UI session principal (US1, US4)
         status: todo
diff --git a/scripts/dev-server-edition.sh b/scripts/dev-server-edition.sh
new file mode 100755
index 000000000..c70897b84
--- /dev/null
+++ b/scripts/dev-server-edition.sh
@@ -0,0 +1,506 @@
+#!/usr/bin/env bash
+# dev-server-edition.sh — Spec 107 local verification rig (quickstart.md).
+#
+# Isolated, synthetic, loopback-only. Builds the server edition into a scratch
+# directory, starts the fake OpenID Provider from tests/oauthserver, writes a
+# scratch config + data dir, boots the server edition on a high port, performs
+# the headless login as alice@example.com and prints /api/v1/auth/me. Nothing
+# here touches ~/.mcpproxy, the tray's core, or a production IdP.
+#
+# Usage:
+#   scripts/dev-server-edition.sh [--phase b|c|d] [--scratch DIR] [--port N]
+#                                 [--idp-port N] [--idp-args "<flags>"]
+#                                 [--keep] [--skip-build]
+#
+#   --phase b   quickstart §0–§4: build, fake IdP, config, boot, headless login,
+#               open-redirect check, /mcp auth gate (session cookie and no
+#               credential both 401) (default)
+#   --phase c   + §5: tenant principal on core REST (PR-C)
+#   --phase d   + §6: mint an agent token as Alice, call /mcp, audit tail (PR-D)
+#   --scratch   root for the binary, config, data dir and logs
+#               (default: $MCPPROXY_RIG_SCRATCH or mktemp under $TMPDIR)
+#   --idp-args  extra flags for the fake IdP, e.g. "-token-error bad-signature";
+#               any tamper flag switches the login step to expect a refusal —
+#               403 (FR-024's closed-reason class) for most flags, but 503
+#               ("Sign-in is temporarily unavailable") for the unavailability
+#               class: -discovery-http-token-endpoint, -token-endpoint-redirect,
+#               and -userinfo-error redirect|non-json|unavailable
+#   --keep      keep the scratch directory on success (always kept on failure)
+#   --skip-build reuse <scratch>/mcpproxy-server and <scratch>/oauthserver
+#
+# Rules this script encodes (all verified, see quickstart.md "Rules"):
+#   * the server binary is built with `-o` — a bare `go build -tags server
+#     ./cmd/mcpproxy` clobbers ./mcpproxy;
+#   * the instance runs with BOTH --config and --data-dir, else the generated
+#     API key lands in a file the next boot never reads;
+#   * teardown kills only the PIDs this script started — never pkill by name;
+#   * every curl carries --max-time and every wait loop is bounded, so a
+#     missing feature (e.g. the OIDC provider on an older branch) is reported,
+#     never hung on.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO="$(cd "$HERE/.." && pwd)"
+cd "$REPO"
+
+PHASE="b"
+SCRATCH="${MCPPROXY_RIG_SCRATCH:-}"
+PORT=""
+IDP_PORT=""
+IDP_EXTRA=""
+KEEP="0"
+SKIP_BUILD="0"
+SCRATCH_OWNED="0"
+
+usage() { sed -n '2,34p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
+
+while [[ $# -gt 0 ]]; do
+	case "$1" in
+	--phase) PHASE="${2:-}"; shift 2 ;;
+	--phase=*) PHASE="${1#*=}"; shift ;;
+	--scratch) SCRATCH="${2:-}"; shift 2 ;;
+	--scratch=*) SCRATCH="${1#*=}"; shift ;;
+	--port) PORT="${2:-}"; shift 2 ;;
+	--port=*) PORT="${1#*=}"; shift ;;
+	--idp-port) IDP_PORT="${2:-}"; shift 2 ;;
+	--idp-port=*) IDP_PORT="${1#*=}"; shift ;;
+	--idp-args) IDP_EXTRA="${2:-}"; shift 2 ;;
+	--idp-args=*) IDP_EXTRA="${1#*=}"; shift ;;
+	--keep) KEEP="1"; shift ;;
+	--skip-build) SKIP_BUILD="1"; shift ;;
+	-h | --help) usage; exit 0 ;;
+	*) echo "unknown argument: $1" >&2; usage >&2; exit 2 ;;
+	esac
+done
+
+case "$PHASE" in
+b | c | d) ;;
+*) echo "--phase must be b, c or d (got: '$PHASE')" >&2; exit 2 ;;
+esac
+
+# ---------------------------------------------------------------------------
+# Output helpers. Assertions are fail-fast: later steps depend on earlier ones.
+# ---------------------------------------------------------------------------
+ts() { date '+%H:%M:%S'; }
+log() { echo "$(ts) [rig] $*"; }
+ok() { echo "$(ts) [rig]   ok   $*"; }
+FAILED="0"
+die() {
+	FAILED="1"
+	echo "$(ts) [rig] FAIL $*" >&2
+	exit 1
+}
+tail_log() { # tail_log <label> <file>
+	[[ -f "$2" ]] || return 0
+	echo "----- last 30 lines of $1 ($2) -----" >&2
+	tail -n 30 "$2" >&2
+	echo "----- end $1 -----" >&2
+}
+need() { command -v "$1" >/dev/null 2>&1 || die "missing tool: $1"; }
+# curl wrapper: bounded, silent, never follows redirects unless asked.
+c() { curl -s --max-time 10 "$@"; }
+port_free() { ! (exec 3<>"/dev/tcp/127.0.0.1/$1") 2>/dev/null; }
+pick_port() { # pick_port <prefix>
+	local p n=0
+	while :; do
+		p="$1$((RANDOM % 900 + 100))"
+		port_free "$p" && { echo "$p"; return 0; }
+		n=$((n + 1))
+		[[ $n -lt 20 ]] || die "no free 1${1#1}xxx port found"
+	done
+}
+wait_http() { # wait_http <url> <seconds> [curl args...]
+	local url="$1" secs="$2" i
+	shift 2
+	for ((i = 0; i < secs * 2; i++)); do
+		if c -f -o /dev/null "$@" "$url"; then return 0; fi
+		sleep 0.5
+	done
+	return 1
+}
+pid_alive() { kill -0 "$1" 2>/dev/null; }
+
+# ---------------------------------------------------------------------------
+# Teardown: PID-scoped, runs on every exit path.
+# ---------------------------------------------------------------------------
+MP_PID=""
+IDP_PID=""
+cleanup() {
+	local rc=$?
+	trap - EXIT
+	set +e
+	for pid in "$MP_PID" "$IDP_PID"; do
+		[[ -n "$pid" ]] || continue
+		pid_alive "$pid" || continue
+		kill -TERM "$pid" 2>/dev/null
+	done
+	for pid in "$MP_PID" "$IDP_PID"; do
+		[[ -n "$pid" ]] || continue
+		for _ in 1 2 3 4 5 6 7 8 9 10; do
+			pid_alive "$pid" || break
+			sleep 0.5
+		done
+		pid_alive "$pid" && kill -KILL "$pid" 2>/dev/null
+		wait "$pid" 2>/dev/null
+	done
+	if [[ "$rc" -ne 0 || "$FAILED" == "1" ]]; then
+		[[ -n "${SCRATCH:-}" ]] && tail_log "main.log" "$SCRATCH/main.log"
+		echo "$(ts) [rig] scratch kept for inspection: $SCRATCH" >&2
+		exit "${rc:-1}"
+	fi
+	if [[ "$KEEP" == "1" || "$SCRATCH_OWNED" != "1" ]]; then
+		log "scratch kept: $SCRATCH"
+	else
+		rm -rf "$SCRATCH" # only a directory this run created via mktemp
+		log "scratch removed"
+	fi
+	exit "$rc"
+}
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+# ---------------------------------------------------------------------------
+# §0 One-time: tools, ports, scratch, build, fixture deps.
+# ---------------------------------------------------------------------------
+need go; need node; need npm; need jq; need curl
+[[ -d "$REPO/cmd/mcpproxy" && -d "$REPO/tests/oauthserver/cmd/server" ]] || die "not a mcpproxy-go checkout: $REPO"
+
+if [[ -z "$SCRATCH" ]]; then
+	tmp_root="${TMPDIR:-/tmp}"
+	SCRATCH="$(mktemp -d "${tmp_root%/}/mcpproxy-107.XXXXXX")"
+	SCRATCH_OWNED="1"
+else
+	mkdir -p "$SCRATCH"
+	SCRATCH="$(cd "$SCRATCH" && pwd)"
+fi
+[[ -n "$PORT" ]] || PORT="$(pick_port 18)"
+[[ -n "$IDP_PORT" ]] || IDP_PORT="$(pick_port 19)"
+port_free "$PORT" || die "port $PORT is busy"
+port_free "$IDP_PORT" || die "port $IDP_PORT is busy"
+log "phase=$PHASE scratch=$SCRATCH port=$PORT idp_port=$IDP_PORT"
+
+BIN="$SCRATCH/mcpproxy-server"
+IDP_BIN="$SCRATCH/oauthserver"
+if [[ "$SKIP_BUILD" == "1" && -x "$BIN" && -x "$IDP_BIN" ]]; then
+	log "§0 reusing $BIN and $IDP_BIN (--skip-build)"
+else
+	log "§0 go build -tags server -o $BIN ./cmd/mcpproxy"
+	go build -tags server -o "$BIN" ./cmd/mcpproxy || die "server edition build failed"
+	log "§0 go build -o $IDP_BIN ./tests/oauthserver/cmd/server"
+	go build -o "$IDP_BIN" ./tests/oauthserver/cmd/server || die "fake IdP build failed (tests/oauthserver)"
+fi
+# `version` prints "MCPProxy vX (server)" as text; the JSON form carries the
+# edition key the quickstart greps for.
+"$BIN" version -o json | jq -e '.edition=="server"' >/dev/null || die "binary does not self-identify as the server edition"
+ok "§0 $BIN self-identifies: $("$BIN" version | head -n 1)"
+
+FIXTURE="$REPO/tests/echo-rugpull-server"
+if [[ ! -d "$FIXTURE/node_modules/@modelcontextprotocol/sdk" ]]; then
+	log "§0 npm ci --prefix $FIXTURE (once)"
+	npm ci --prefix "$FIXTURE" --no-audit --no-fund >"$SCRATCH/npm-ci.log" 2>&1 || {
+		tail_log "npm-ci.log" "$SCRATCH/npm-ci.log"
+		die "npm ci for the stdio fixture failed"
+	}
+fi
+ok "§0 stdio fixture ready: node $FIXTURE/index.js"
+
+# ---------------------------------------------------------------------------
+# §1 Fake OIDC IdP.
+# ---------------------------------------------------------------------------
+IDP_ARGS=(
+	-port "$IDP_PORT" -oidc
+	-redirect-uri "http://127.0.0.1:$PORT/api/v1/auth/callback"
+	-user 'alice@example.com:pass:eng' -user 'bob@example.com:pass:'
+	-user 'carol@example.com:pass:ops' -user 'dana@example.com:pass:'
+	-groups-claim groups
+)
+TAMPER="0"
+GROUPS_TAMPER="0"
+if [[ -n "$IDP_EXTRA" ]]; then
+	read -r -a extra <<<"$IDP_EXTRA"
+	IDP_ARGS+=("${extra[@]}")
+	case " $IDP_EXTRA " in
+	*" -groups-error non-array "*)
+		# tests/oauthserver's GroupsNonArray knob renders the groups value as
+		# a comma-joined STRING (token.go's joinGroups), and oidc_provider.go's
+		# groupsFromClaims explicitly accepts a bare string as one valid group
+		# name (`case string:`) — it is not a "non-array/non-string shape"
+		# under FR-008's own wording, so it does NOT fail closed: the login
+		# succeeds with that string as the caller's one group, exactly like
+		# TestOIDCVerify_GroupsClaimMissingFailsClosed's
+		# "single_string_is_one_group" case. Neither TAMPER nor GROUPS_TAMPER
+		# — this falls through to the normal §4c assertions below, which the
+		# caller must point at the expected joined-string group name instead
+		# of the default ["eng"] (cross-review round 6, chunk 4 P2: an
+		# earlier version of this script folded "non-array" into the
+		# fail-closed GROUPS_TAMPER bucket alongside absent/overage and
+		# asserted groups==[], which this claim shape never produces).
+		;;
+	*" -groups-error "*)
+		# FR-008 fail-closed groups fixtures (absent/overage): the login
+		# still SUCCEEDS (groups land as [] and groups_claim_missing is
+		# logged) — this is NOT a login-refusal tamper case (cross-review
+		# round 5, chunk 4 P3).
+		GROUPS_TAMPER="1"
+		;;
+	*)
+		TAMPER="1"
+		;;
+	esac
+fi
+IDP_URL="http://127.0.0.1:$IDP_PORT"
+log "§1 starting fake IdP: $IDP_BIN ${IDP_ARGS[*]}"
+"$IDP_BIN" "${IDP_ARGS[@]}" >"$SCRATCH/idp.log" 2>&1 &
+IDP_PID=$!
+if ! wait_http "$IDP_URL/.well-known/openid-configuration" 20; then
+	tail_log "idp.log" "$SCRATCH/idp.log"
+	die "fake IdP did not serve /.well-known/openid-configuration within 20s (pid $IDP_PID)"
+fi
+c "$IDP_URL/.well-known/openid-configuration" |
+	jq -e '.userinfo_endpoint and .jwks_uri and (.id_token_signing_alg_values_supported|index("RS256"))' >/dev/null ||
+	die "OIDC discovery document lacks userinfo_endpoint / jwks_uri / RS256"
+# The discovery endpoint answers as soon as the listener is bound — before
+# the startup banner (Confidential ID/Secret included) finishes printing to
+# idp.log — so a single read right after wait_http can race an empty file.
+# Poll the same bounded way wait_http does.
+OIDC_CLIENT_ID=""
+OIDC_CLIENT_SECRET=""
+for ((i = 0; i < 40; i++)); do
+	OIDC_CLIENT_ID="$(sed -n 's/^Confidential ID:[[:space:]]*//p' "$SCRATCH/idp.log" 2>/dev/null | head -n1)"
+	OIDC_CLIENT_SECRET="$(sed -n 's/^Confidential Secret:[[:space:]]*//p' "$SCRATCH/idp.log" 2>/dev/null | head -n1)"
+	[[ -n "$OIDC_CLIENT_ID" && -n "$OIDC_CLIENT_SECRET" ]] && break
+	sleep 0.5
+done
+[[ -n "$OIDC_CLIENT_ID" && -n "$OIDC_CLIENT_SECRET" ]] || die "could not read Confidential ID/Secret from idp.log within 20s"
+export OIDC_CLIENT_ID OIDC_CLIENT_SECRET
+ok "§1 fake IdP up (pid $IDP_PID), client_id=$OIDC_CLIENT_ID, tamper=$TAMPER"
+
+# ---------------------------------------------------------------------------
+# §2 Scratch configuration (the config references the IdP client through
+# ${env:} — nested server_edition.* keys have no env override, FR-020).
+# ---------------------------------------------------------------------------
+CONFIG="$SCRATCH/mcp_config.json"
+AUDIT="$SCRATCH/audit.jsonl"
+cat >"$CONFIG" <<EOF
+{
+  "listen": "127.0.0.1:$PORT",
+  "require_mcp_auth": false,
+  "trusted_proxies": ["127.0.0.1/32"],
+  "audit_log": {"enabled": true, "path": "$AUDIT", "stdout": false},
+  "mcpServers": [
+    {"name": "a",    "command": "node", "args": ["$FIXTURE/index.js"], "protocol": "stdio", "enabled": true, "shared": true},
+    {"name": "b",    "command": "node", "args": ["$FIXTURE/index.js"], "protocol": "stdio", "enabled": true, "shared": true},
+    {"name": "a__b", "command": "node", "args": ["$FIXTURE/index.js"], "protocol": "stdio", "enabled": true, "shared": true}
+  ],
+  "server_edition": {
+    "enabled": true,
+    "admin_emails": ["dana@example.com"],
+    "public_url": "http://127.0.0.1:$PORT",
+    "session_cookie_secure": "auto",
+    "oauth": {
+      "provider": "oidc",
+      "issuer_url": "$IDP_URL",
+      "allow_insecure_issuer": true,
+      "client_id": "\${env:OIDC_CLIENT_ID}",
+      "client_secret": "\${env:OIDC_CLIENT_SECRET}",
+      "scopes": ["openid", "profile", "email", "groups"],
+      "groups_claim": "groups",
+      "email_verified_policy": "refuse_false",
+      "display_name": "Example Corp"
+    },
+    "access": {"group_servers": {"eng": ["a"], "ops": ["a", "b"]}, "default_servers": []}
+  }
+}
+EOF
+jq -e . "$CONFIG" >/dev/null || die "scratch config is not valid JSON"
+ok "§2 wrote $CONFIG"
+
+# ---------------------------------------------------------------------------
+# §3 Run.
+# ---------------------------------------------------------------------------
+BASE="http://127.0.0.1:$PORT"
+MAIN_LOG="$SCRATCH/main.log"
+log "§3 $BIN serve --config $CONFIG --data-dir $SCRATCH --log-level=debug"
+"$BIN" serve --config "$CONFIG" --data-dir "$SCRATCH" --log-level=debug >"$MAIN_LOG" 2>&1 &
+MP_PID=$!
+for ((i = 0; i < 120; i++)); do
+	if ! pid_alive "$MP_PID"; then
+		wait "$MP_PID" && rc=0 || rc=$?
+		reason="$(grep -E '^Error:|"level":"error"|ERROR' "$MAIN_LOG" | tail -n 1)"
+		[[ "$rc" -eq 3 ]] && die "server exited 3 (BBolt lock) — another instance holds $SCRATCH/config.db"
+		[[ "$rc" -eq 4 ]] && die "server refused the scratch config (exit 4): ${reason:-see main.log} — on a branch without the oidc provider this is the expected stop"
+		die "server exited early with code $rc: ${reason:-see main.log}"
+	fi
+	c -f -o /dev/null "$BASE/readyz" && break
+	sleep 0.5
+done
+c -f -o /dev/null "$BASE/readyz" || die "server not ready on $BASE/readyz within 60s (pid $MP_PID)"
+API_KEY="$(jq -r '.api_key // empty' "$CONFIG")"
+[[ -n "$API_KEY" ]] || die "no api_key written back to $CONFIG (is --config + --data-dir wiring intact?)"
+c -f -H "X-API-Key: $API_KEY" "$BASE/api/v1/status" | jq -e '.data.edition=="server"' >/dev/null ||
+	die "/api/v1/status does not report edition=server"
+ok "§3 server edition ready (pid $MP_PID), api_key read from config (operator key; tenants never see it)"
+if grep -q 'Failed to initialize server features' "$MAIN_LOG"; then
+	grep 'Failed to initialize server features' "$MAIN_LOG" | tail -n 1 >&2
+	die "server-edition features did not initialise — the /api/v1/auth/* front door is NOT mounted on this build (see the line above; on a branch without the oidc provider this is expected)"
+fi
+log "§3 boot notices:"
+grep -E 'require_mcp_auth.*overrid|public_url|audit_log.*enabled' "$MAIN_LOG" | head -n 5 | sed 's/^/    /' || true
+
+# ---------------------------------------------------------------------------
+# §4 Headless login (Alice) — no browser, no API key.
+# ---------------------------------------------------------------------------
+# headless_login <jar> <redirect_uri> -> prints "<callback http code> <redirect_url>"
+headless_login() {
+	local jar="$1" want="$2" auth cb
+	# 4a. /auth/login stores state+nonce server-side and 302s to the IdP.
+	auth="$(c -o /dev/null -w '%{http_code} %{redirect_url}' -c "$jar" "$BASE/api/v1/auth/login?redirect_uri=$want")"
+	if [[ "${auth%% *}" != "302" && "${auth%% *}" != "303" && "${auth%% *}" != "307" ]]; then
+		if [[ "$TAMPER" == "1" ]]; then
+			# Some tamper flags (e.g. -discovery-http-token-endpoint) fail
+			# synchronously at /auth/login itself — discovery runs before the
+			# redirect to the IdP is built — so there is no IdP form to
+			# submit and no callback to complete; the unavailable response IS
+			# the terminal outcome for this attempt. Previously this always
+			# died here, so that tamper case's expected-503 handling
+			# downstream was unreachable (cross-review round 7, chunk 4 P2).
+			echo "$auth"
+			return 0
+		fi
+		die "4a /auth/login answered HTTP ${auth%% *} instead of a redirect to the IdP (OIDC front door missing?)"
+	fi
+	auth="${auth#* }"
+	[[ "$auth" == "$IDP_URL"/* ]] || die "4a /auth/login redirected off the fake IdP: $auth"
+	echo "$auth" | grep -Eq 'code_challenge_method=S256' || die "4a authorize URL lacks code_challenge_method=S256 (FR-021)"
+	echo "$auth" | grep -q 'nonce=' || die "4a authorize URL lacks nonce (FR-021)"
+	# 4b. submit the fake IdP's form; do NOT follow the redirect.
+	cb="$(c -o /dev/null -w '%{redirect_url}' -X POST "$auth" \
+		--data-urlencode username=alice@example.com --data-urlencode password=pass \
+		--data consent=on --data action=approve)"
+	[[ "$cb" == "$BASE/api/v1/auth/callback?"* ]] || die "4b fake IdP did not redirect to our callback (got: '$cb')"
+	# 4c. complete the callback; the session cookie lands in the jar.
+	c -o /dev/null -w '%{http_code} %{redirect_url}' -b "$jar" -c "$jar" "$cb"
+}
+
+J="$SCRATCH/alice.jar"
+res="$(headless_login "$J" "/my/tokens")"
+code="${res%% *}"; loc="${res#* }"
+if [[ "$TAMPER" == "1" ]]; then
+	# FR-024: unavailability (discovery/provider/internal failures) is the one
+	# distinct class — 503, not the 403 closed-reason page — so a tamper flag
+	# that injects one of those must expect 503, never a blanket 403.
+	want="403"
+	case " $IDP_EXTRA " in
+	*" -discovery-http-token-endpoint "*|*" -token-endpoint-redirect "*|\
+	*" -userinfo-error redirect "*|*" -userinfo-error non-json "*|*" -userinfo-error unavailable "*|\
+	*" -token-error invalid_client "*|*" -token-error invalid_grant "*|\
+	*" -token-error invalid_scope "*|*" -token-error server_error "*)
+		# These are HTTP-level token-endpoint failures (ExchangeCode returns
+		# an error on a non-200 response), not ID-token content defects: the
+		# callback maps them to provider_error, not authorization_denied
+		# (cross-review round 5, chunk 4 P3). The other -token-error values
+		# are id_token defects checked after a successful exchange and stay
+		# in the 403 bucket (bad-signature, wrong-iss, wrong-aud, etc.).
+		want="503"
+		;;
+	esac
+	[[ "$code" == "$want" ]] || die "4c tamper case: expected $want from the callback, got HTTP $code ($loc)"
+	[[ "$(grep -c mcpproxy_session "$J" 2>/dev/null || true)" == "0" ]] || die "4c tamper case: a session cookie was issued"
+	ok "4c tamper case refused with $want and no session (idp-args: $IDP_EXTRA)"
+	log "§4 done (tamper run); phases c/d are not exercised under tamper"
+	exit 0
+fi
+[[ "$code" == "302" && "$loc" == "$BASE/my/tokens" ]] || die "4c callback: expected 302 -> $BASE/my/tokens, got HTTP $code -> '$loc'"
+[[ "$(grep -c mcpproxy_session "$J")" == "1" ]] || die "4c expected exactly one mcpproxy_session cookie in $J"
+ME="$(c -b "$J" "$BASE/api/v1/auth/me")"
+if [[ "$GROUPS_TAMPER" == "1" ]]; then
+	# FR-008 fail-closed: a missing/non-array/oversized groups claim stores
+	# [] (never the pre-existing value) rather than refusing the login.
+	echo "$ME" | jq -e '.email=="alice@example.com" and .groups==[]' >/dev/null ||
+		die "4c groups-error tamper case: expected alice with groups [] (fail-closed): $ME"
+	ok "4c groups-error tamper case: alice logged in with groups [] (fail-closed, idp-args: $IDP_EXTRA)"
+	log "§4 done (groups-tamper run); phases c/d are not exercised under tamper"
+	exit 0
+fi
+echo "$ME" | jq -e '.email=="alice@example.com" and .groups==["eng"]' >/dev/null ||
+	die "4c /auth/me is not alice with groups [eng]: $ME"
+ok "§4 alice logged in; /api/v1/auth/me:"
+echo "$ME" | jq . | sed 's/^/    /'
+
+# Open-redirect check (US2.7): an absolute redirect_uri must fall back to /ui/.
+J2="$SCRATCH/alice-evil.jar"
+res="$(headless_login "$J2" "https://evil.example/")"
+code="${res%% *}"; loc="${res#* }"
+[[ "$code" == "302" && "$loc" == "$BASE/ui/" ]] || die "4d open redirect: expected 302 -> $BASE/ui/, got HTTP $code -> '$loc'"
+ok "4d redirect_uri=https://evil.example/ landed on /ui/ (US2.7)"
+
+# §4e /mcp auth gate (T062, part of phase b itself — the session cookie and
+# JWT are never MCP credentials, and require_mcp_auth is forced true, so both
+# checks stand on PR-B alone and must run before the phase-b exit below
+# rather than only under --phase d, where they used to live unreachable
+# (cross-review round 7, chunk 4 P2).
+code="$(c -o /dev/null -w '%{http_code}' -b "$J" -X POST "$BASE/mcp" -d '{}')"
+[[ "$code" == "401" ]] || die "4e cookie on /mcp must be 401 (FR-003, got $code)"
+code="$(c -o /dev/null -w '%{http_code}' -X POST "$BASE/mcp" -d '{}')"
+[[ "$code" == "401" ]] || die "4e no credential on /mcp must be 401 despite require_mcp_auth:false (FR-029, got $code)"
+ok "§4e /mcp refuses a session cookie and refuses no credential"
+
+[[ "$PHASE" == "b" ]] && { log "phase b complete"; exit 0; }
+
+# ---------------------------------------------------------------------------
+# §5 Tenant principal on core REST (PR-C).
+# ---------------------------------------------------------------------------
+c "$BASE/api/v1/auth/provider" | jq -e '.display_name=="Example Corp" and (keys|length==1)' >/dev/null ||
+	die "5 /auth/provider must expose exactly display_name (FR-030)"
+c -b "$J" "$BASE/api/v1/servers" | jq -e '[.data.servers[].name]==["a"]' >/dev/null ||
+	die "5 /servers as alice must list exactly [a] (entitlement-filtered)"
+c -b "$J" "$BASE/api/v1/user/servers" | jq -e '[.shared[].name]==["a"]' >/dev/null ||
+	die "5 /user/servers as alice must list shared=[a]"
+code="$(c -o /dev/null -w '%{http_code}' -b "$J" "$BASE/api/v1/config")"
+[[ "$code" == "403" ]] || die "5 /config with a tenant cookie must be 403 (got $code)"
+code="$(c -o /dev/null -w '%{http_code}' -b "$J" -X POST -d '{}' "$BASE/api/v1/tools/call")"
+[[ "$code" == "403" ]] || die "5 /tools/call with a tenant cookie must be 403 before body parse (got $code)"
+code="$(c -o /dev/null -w '%{http_code}' -b "$J" -H 'X-API-Key: wrong' "$BASE/api/v1/status")"
+[[ "$code" == "401" ]] || die "5 wrong X-API-Key beside a valid cookie must be 401 (FR-001 precedence, got $code)"
+ok "§5 tenant principal on core REST"
+
+[[ "$PHASE" == "c" ]] && { log "phase c complete"; exit 0; }
+
+# ---------------------------------------------------------------------------
+# §6 Mint an agent token as Alice, call /mcp, read the audit line (PR-D).
+# ---------------------------------------------------------------------------
+TOK="$(c -b "$J" -X POST "$BASE/api/v1/user/tokens" -H 'Content-Type: application/json' \
+	-d '{"name":"t1","allowed_servers":["*"],"permissions":["read"],"expires_in":"720h"}' | jq -r '.token // empty')"
+[[ -n "$TOK" ]] || die "6 token mint as alice returned no token"
+c -b "$J" "$BASE/api/v1/user/tokens" | jq -e '.tokens[0].allowed_servers==["a"]' >/dev/null ||
+	die "6 minted token must have '*' materialised to [a] (US1.3)"
+mcp() {
+	c -X POST "$BASE/mcp" -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \
+		-H 'Accept: application/json, text/event-stream' "$@"
+}
+mcp -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"quickstart","version":"1"}}}' \
+	-D "$SCRATCH/init.h" >/dev/null
+SID="$(grep -i '^mcp-session-id' "$SCRATCH/init.h" | tr -d '\r' | cut -d' ' -f2)"
+[[ -n "$SID" ]] || die "6 initialize returned no Mcp-Session-Id"
+allowed="$(mcp -H "Mcp-Session-Id: $SID" -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"call_tool_read","arguments":{"name":"a:echo","args":{"text":"hello","secret":"AKIAQUICKSTART7SENTINEL0"}}}}' | jq -c '.result.isError')"
+[[ "$allowed" == "false" ]] || die "6 a:echo through the token must succeed (isError=$allowed)"
+hiddenResp="$(mcp -H "Mcp-Session-Id: $SID" -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"call_tool_read","arguments":{"name":"b:echo","args":{}}}}')"
+hidden="$(echo "$hiddenResp" | jq -r '.result.content[0].text // empty')"
+log "6 b:echo refusal text: ${hidden:-<empty>}"
+# Server b is not in Alice's entitlement scope; the call must be refused, not
+# answered (an authorization regression here would otherwise pass the rig
+# silently — cross-review round 8, chunk 4 P2).
+echo "$hiddenResp" | jq -e '.result.isError==true' >/dev/null ||
+	die "6 b:echo must be refused (isError=true) for a token scoped to [a]"
+[[ -f "$AUDIT" ]] || die "6 audit log $AUDIT was not written"
+log "6 last audit lines:"
+tail -n 3 "$AUDIT" | jq -c '{event,decision,outcome,server,tool,reason,disclosed,caller:.caller.kind,email:.caller.user_email,rid:.request_id}' | sed 's/^/    /'
+[[ "$(grep -c 'AKIAQUICKSTART7SENTINEL0' "$AUDIT" || true)" == "0" ]] || die "6 secret bytes leaked into the audit log"
+[[ "$(grep -c '"event":"auth_event"' "$AUDIT" || true)" -ge 1 ]] || die "6 no auth_event line for alice's login"
+MCPPROXY_AUDIT_JSONL="$AUDIT" go test ./internal/audit -run TestExternalJSONLValidates -count=1 >"$SCRATCH/audit-schema.log" 2>&1 || {
+	tail_log "audit-schema.log" "$SCRATCH/audit-schema.log"
+	die "6 audit JSONL failed schema validation"
+}
+ok "§6 token mint, /mcp gate, audit lines and schema validation"
+log "phase d complete"
diff --git a/specs/107-server-edition-sso-hardening/tasks.md b/specs/107-server-edition-sso-hardening/tasks.md
index bafddddc0..2bab84a2c 100644
--- a/specs/107-server-edition-sso-hardening/tasks.md
+++ b/specs/107-server-edition-sso-hardening/tasks.md
@@ -82,11 +82,11 @@ Gate set for every PR = plan.md §Gates. Never claim a skipped gate passed; writ
 
 ## Phase B.1 — Test rig: fake OIDC IdP and dev script (FR-047 part 2)
 
-- [ ] T032 [US2] **[compile-red until T033]** Write failing `tests/oauthserver/oidc_test.go`: with `Options.OIDC`, discovery carries `userinfo_endpoint` + `id_token_signing_alg_values_supported`, the auth-code token response carries an RS256 `id_token` whose `nonce`/`sub`/`email`/`email_verified`/`name`/`groups` match `Options.UserClaims`, `/userinfo` returns the same claims for the access token, and **every** `ErrorMode` tamper knob of research D2 (the eleven original ones plus `IDTokenMultiAudNoAzp`, `IDTokenNbfFuture`, `IDTokenUnknownKid`, `IDTokenKeyAlgMismatch`, `GroupsNonArray`, `GroupsOverageMarker`, `GroupsAbsentEverywhere`, `UserinfoRedirect`, `UserinfoNonJSON`, `UserinfoUnavailable`, `AuthAccessDenied` (exists)) produces the intended defect, one sub-test per knob so an unimplemented knob is a named failure — `tests/oauthserver/oidc_test.go`
-- [ ] T033 [US2] Implement `Options.OIDC`, `Options.UserClaims`, `Options.ClientRedirectURIs`, `Options.GroupsClaim`, the full `ErrorMode` knob list of research D2 (as extended in round 2 — every T037 network/integration case has a knob; the pure-verification cases T037 lists that need no IdP behaviour, e.g. `alg: none`/HS256 crafted locally, are minted in the test with the fake's `KeyRing` against the fake's real JWKS), `id_token` minting in `token.go:54-185` using the `KeyRing`, `/userinfo` handler, discovery additions (`discovery.go:9-50`), nonce capture in `authorize.go`; keep every existing test green — `tests/oauthserver/{options.go,discovery.go,token.go,authorize.go,userinfo.go(new),types.go}`
-- [ ] T034a [US2] **[compile-red until T033 (`Options` fields) and T034 (`parseFlags`)]** Write failing `tests/oauthserver/cmd/server/main_test.go`: a table test over `parseFlags(args []string) (oauthserver.Options, error)` — `-oidc`, `-user email:sub:name:group1,group2`, `-redirect-uri`, `-groups-claim`, every tamper flag → the expected `Options`/`ErrorMode`; an unknown tamper name → error — `tests/oauthserver/cmd/server/main_test.go`
-- [ ] T034 [US2] (after T033 and T034a; not parallel — the flag parser targets `Options` fields T033 introduces) Extract `parseFlags` from `main()` and add the CLI flags `-oidc`, `-user`, `-redirect-uri`, `-groups-claim`, tamper flags on `tests/oauthserver/cmd/server/main.go`; print the OIDC endpoints — `tests/oauthserver/cmd/server/main.go`
-- [ ] T035 [P] [US2] Create `scripts/dev-server-edition.sh` implementing quickstart §0–§4 and §6 (`--phase b|c|d` gates the later steps), with PID-scoped teardown and no `pkill`; the stdio fixture is `node $PWD/tests/echo-rugpull-server/index.js` (a deterministic `echo` tool when `DESC_FILE` is unset — there is no `test/fixtures/echo-server` in the repo; the script runs `npm ci --prefix tests/echo-rugpull-server` once); tooling task (no Go test): `bash -n` + `shellcheck` gate and the T062 real-instance run are its verification; document it in `docs/development/server-edition-multiuser-auth.md` — `scripts/dev-server-edition.sh`, `docs/development/server-edition-multiuser-auth.md`
+- [x] T032 [US2] **[compile-red until T033]** Write failing `tests/oauthserver/oidc_test.go`: with `Options.OIDC`, discovery carries `userinfo_endpoint` + `id_token_signing_alg_values_supported`, the auth-code token response carries an RS256 `id_token` whose `nonce`/`sub`/`email`/`email_verified`/`name`/`groups` match `Options.UserClaims`, `/userinfo` returns the same claims for the access token, and **every** `ErrorMode` tamper knob of research D2 (the eleven original ones plus `IDTokenMultiAudNoAzp`, `IDTokenNbfFuture`, `IDTokenUnknownKid`, `IDTokenKeyAlgMismatch`, `GroupsNonArray`, `GroupsOverageMarker`, `GroupsAbsentEverywhere`, `UserinfoRedirect`, `UserinfoNonJSON`, `UserinfoUnavailable`, `AuthAccessDenied` (exists)) produces the intended defect, one sub-test per knob so an unimplemented knob is a named failure — `tests/oauthserver/oidc_test.go`
+- [x] T033 [US2] Implement `Options.OIDC`, `Options.UserClaims`, `Options.ClientRedirectURIs`, `Options.GroupsClaim`, the full `ErrorMode` knob list of research D2 (as extended in round 2 — every T037 network/integration case has a knob; the pure-verification cases T037 lists that need no IdP behaviour, e.g. `alg: none`/HS256 crafted locally, are minted in the test with the fake's `KeyRing` against the fake's real JWKS), `id_token` minting in `token.go:54-185` using the `KeyRing`, `/userinfo` handler, discovery additions (`discovery.go:9-50`), nonce capture in `authorize.go`; keep every existing test green — `tests/oauthserver/{options.go,discovery.go,token.go,authorize.go,userinfo.go(new),types.go}`
+- [x] T034a [US2] **[compile-red until T033 (`Options` fields) and T034 (`parseFlags`)]** Write failing `tests/oauthserver/cmd/server/main_test.go`: a table test over `parseFlags(args []string) (oauthserver.Options, error)` — `-oidc`, `-user email:sub:name:group1,group2`, `-redirect-uri`, `-groups-claim`, every tamper flag → the expected `Options`/`ErrorMode`; an unknown tamper name → error — `tests/oauthserver/cmd/server/main_test.go`
+- [x] T034 [US2] (after T033 and T034a; not parallel — the flag parser targets `Options` fields T033 introduces) Extract `parseFlags` from `main()` and add the CLI flags `-oidc`, `-user`, `-redirect-uri`, `-groups-claim`, tamper flags on `tests/oauthserver/cmd/server/main.go`; print the OIDC endpoints — `tests/oauthserver/cmd/server/main.go`
+- [x] T035 [P] [US2] Create `scripts/dev-server-edition.sh` implementing quickstart §0–§4 and §6 (`--phase b|c|d` gates the later steps), with PID-scoped teardown and no `pkill`; the stdio fixture is `node $PWD/tests/echo-rugpull-server/index.js` (a deterministic `echo` tool when `DESC_FILE` is unset — there is no `test/fixtures/echo-server` in the repo; the script runs `npm ci --prefix tests/echo-rugpull-server` once); tooling task (no Go test): `bash -n` + `shellcheck` gate and the T062 real-instance run are its verification; document it in `docs/development/server-edition-multiuser-auth.md` — `scripts/dev-server-edition.sh`, `docs/development/server-edition-multiuser-auth.md`
 
 ## Phase B.2 — US2: generic OIDC provider with verified ID tokens (P1)
 
@@ -94,58 +94,58 @@ Gate set for every PR = plan.md §Gates. Never claim a skipped gate passed; writ
 
 ### Tests first
 
-- [ ] T036 [US2] **[compile-red until T043]** Write failing `internal/serveredition/auth/oidc_jwks_test.go`: RSA and EC JWK → public key, unknown `kty` refused, malformed `n`/`e` refused; `internal/serveredition/auth/oidc_discovery_test.go`: lazy fetch on first login (boot makes no request — assert with a counting `httptest` server), `issuer` byte-compare (trailing slash mismatch → `discovery_failed`), cache TTL clamped to [5 min, 24 h], refetch on error, `http` endpoint refused unless loopback + `allow_insecure_issuer`, 3xx from any back-channel endpoint → `provider_error` (non-redirecting client), client-auth method chosen from `token_endpoint_auth_methods_supported` (basic / post / absent → basic / neither → `discovery_failed`) — files above
-- [ ] T037 [P] [US2] **[compile-red until T043 (provider/verifier); the handler-level assertions — user store untouched, stored groups untouched, `email_verified_policy` refusals, `groups_claim_missing` warning — are compile-red until T044 too, so the file compiles only once both land]** Write failing `internal/serveredition/auth/oidc_verify_test.go` (every case is driven through the in-process `tests/oauthserver` knob named in T032/T033, or — for crafted-token cases — minted with its `KeyRing`; no case is synthesised against a second fake): the tamper matrix (bad signature, wrong `iss`, wrong `aud`, multi-`aud` without matching `azp`, expired, `nbf` future, wrong/missing `nonce`, `alg: none`, HS256, unknown `kid` → one JWKS refetch then refuse, key-type/alg mismatch) each → the closed reason, user store untouched, log line names the check and never a claim value; `email_verified_policy` × {true,false,absent} × {refuse_false,require_true,ignore}; groups from the token, from userinfo only when the token lacks the claim and `sub` matches (mismatch/absent → `userinfo_subject_mismatch`), userinfo transport/3xx/non-200/non-JSON → `provider_error` with stored groups untouched, absent in both / non-array / Entra overage marker → `[]` + `groups_claim_missing` warning — `internal/serveredition/auth/oidc_verify_test.go`
-- [ ] T038 [P] [US2] **[compile-red until T044/T045]** Write failing `internal/serveredition/auth/oauth_handler_subject_test.go`: same provider+email, different `sub` → `subject_mismatch`; configured-provider change → first login re-binds (`provider_rebound`); `subject_rebind_armed_at` set only on a real disable→enable transition, consumed by the first successful login (restart between enable and login; failed-then-successful; two concurrent logins for the same email with **two different subjects** → exactly one rebinds, the other is `subject_mismatch`, and the stored subject equals the winner's — driven through `UpdateUserLogin` directly with a barrier so both calls start after the flag is armed); `Provider`/`ProviderSubjectID` refreshed on every login — `internal/serveredition/auth/oauth_handler_subject_test.go`, `internal/serveredition/api/admin_handlers_rebind_test.go`
-- [ ] T039 [P] [US2] **[compile-red until T044]** Write failing `internal/serveredition/auth/oauth_handler_refusal_test.go`: every refusal reason renders the one generic 403 page with a request id — including an IdP authorization-response error on the callback (`?error=access_denied&state=…`, the fake's `AuthAccessDenied` knob, and a user who declines consent on the fake's form): the pending state is consumed **before** the response is classified, the page is the generic 403 (never the IdP's `error_description`), the typed terminal reason is `authorization_denied` (asserted through the handler's `LoginResult` observer hook of T044 — **no audit line is asserted in PR-B**; T106 in PR-D re-drives these fixtures and asserts exactly one `auth_event`) — today the callback returns a distinct 400 `missing code parameter` before touching the state (`oauth_handler.go:163-167`); `discovery_failed`/`provider_error`/`internal_error` (fault injection through the T044 seams: a failing `loginStore`, a failing `bearerSigner`, a failing `sessionCreator` — one sub-test per `internal_error` branch) render the 503 page; no user record created before the upsert commits; readiness unaffected during an IdP outage; `pendingStates` capped at 10,000 (insert 10,001, the first is gone, its login → `state_invalid`); legacy providers (`google`, `github`, `microsoft`) unchanged: no nonce, no JWKS, `client_secret_post`, stored groups `[]` — `internal/serveredition/auth/oauth_handler_refusal_test.go`
-- [ ] T040 [P] [US2] **[compile-red until T041]** Write failing `internal/config/server_edition_oidc_config_test.go`: `provider: oidc` admitted; `issuer_url` required/https rule/loopback exception; `scopes` default + `openid` appended; `groups_claim`, `email_verified_policy` enum, `display_name`; `users.User.Validate` admits `oidc` and still requires a non-empty subject (`internal/serveredition/users/models_test.go`) — files above
+- [x] T036 [US2] **[compile-red until T043]** Write failing `internal/serveredition/auth/oidc_jwks_test.go`: RSA and EC JWK → public key, unknown `kty` refused, malformed `n`/`e` refused; `internal/serveredition/auth/oidc_discovery_test.go`: lazy fetch on first login (boot makes no request — assert with a counting `httptest` server), `issuer` byte-compare (trailing slash mismatch → `discovery_failed`), cache TTL clamped to [5 min, 24 h], refetch on error, `http` endpoint refused unless loopback + `allow_insecure_issuer`, 3xx from any back-channel endpoint → `provider_error` (non-redirecting client), client-auth method chosen from `token_endpoint_auth_methods_supported` (basic / post / absent → basic / neither → `discovery_failed`) — files above
+- [x] T037 [P] [US2] **[compile-red until T043 (provider/verifier); the handler-level assertions — user store untouched, stored groups untouched, `email_verified_policy` refusals, `groups_claim_missing` warning — are compile-red until T044 too, so the file compiles only once both land]** Write failing `internal/serveredition/auth/oidc_verify_test.go` (every case is driven through the in-process `tests/oauthserver` knob named in T032/T033, or — for crafted-token cases — minted with its `KeyRing`; no case is synthesised against a second fake): the tamper matrix (bad signature, wrong `iss`, wrong `aud`, multi-`aud` without matching `azp`, expired, `nbf` future, wrong/missing `nonce`, `alg: none`, HS256, unknown `kid` → one JWKS refetch then refuse, key-type/alg mismatch) each → the closed reason, user store untouched, log line names the check and never a claim value; `email_verified_policy` × {true,false,absent} × {refuse_false,require_true,ignore}; groups from the token, from userinfo only when the token lacks the claim and `sub` matches (mismatch/absent → `userinfo_subject_mismatch`), userinfo transport/3xx/non-200/non-JSON → `provider_error` with stored groups untouched, absent in both / non-array / Entra overage marker → `[]` + `groups_claim_missing` warning — `internal/serveredition/auth/oidc_verify_test.go`
+- [x] T038 [P] [US2] **[compile-red until T044/T045]** Write failing `internal/serveredition/auth/oauth_handler_subject_test.go`: same provider+email, different `sub` → `subject_mismatch`; configured-provider change → first login re-binds (`provider_rebound`); `subject_rebind_armed_at` set only on a real disable→enable transition, consumed by the first successful login (restart between enable and login; failed-then-successful; two concurrent logins for the same email with **two different subjects** → exactly one rebinds, the other is `subject_mismatch`, and the stored subject equals the winner's — driven through `UpdateUserLogin` directly with a barrier so both calls start after the flag is armed); `Provider`/`ProviderSubjectID` refreshed on every login — `internal/serveredition/auth/oauth_handler_subject_test.go`, `internal/serveredition/api/admin_handlers_rebind_test.go`
+- [x] T039 [P] [US2] **[compile-red until T044]** Write failing `internal/serveredition/auth/oauth_handler_refusal_test.go`: every refusal reason renders the one generic 403 page with a request id — including an IdP authorization-response error on the callback (`?error=access_denied&state=…`, the fake's `AuthAccessDenied` knob, and a user who declines consent on the fake's form): the pending state is consumed **before** the response is classified, the page is the generic 403 (never the IdP's `error_description`), the typed terminal reason is `authorization_denied` (asserted through the handler's `LoginResult` observer hook of T044 — **no audit line is asserted in PR-B**; T106 in PR-D re-drives these fixtures and asserts exactly one `auth_event`) — today the callback returns a distinct 400 `missing code parameter` before touching the state (`oauth_handler.go:163-167`); `discovery_failed`/`provider_error`/`internal_error` (fault injection through the T044 seams: a failing `loginStore`, a failing `bearerSigner`, a failing `sessionCreator` — one sub-test per `internal_error` branch) render the 503 page; no user record created before the upsert commits; readiness unaffected during an IdP outage; `pendingStates` capped at 10,000 (insert 10,001, the first is gone, its login → `state_invalid`); legacy providers (`google`, `github`, `microsoft`) unchanged: no nonce, no JWKS, `client_secret_post`, stored groups `[]` — `internal/serveredition/auth/oauth_handler_refusal_test.go`
+- [x] T040 [P] [US2] **[compile-red until T041]** Write failing `internal/config/server_edition_oidc_config_test.go`: `provider: oidc` admitted; `issuer_url` required/https rule/loopback exception; `scopes` default + `openid` appended; `groups_claim`, `email_verified_policy` enum, `display_name`; `users.User.Validate` admits `oidc` and still requires a non-empty subject (`internal/serveredition/users/models_test.go`) — files above
 
 ### Implementation
 
-- [ ] T041 [US2] Config: add `IssuerURL`, `AllowInsecureIssuer`, `Scopes`, `GroupsClaim`, `EmailVerifiedPolicy`, `DisplayName` to `ServerEditionOAuthConfig` (`server_edition_config.go:31-37`); provider enum + rules in `Validate`, defaults in `ApplyDefaults`; `users/models.go:48` admits `oidc`; `cmd/mcpproxy/status_serveredition.go` unchanged (prints the value) — `internal/config/server_edition_config.go`, `internal/serveredition/users/models.go`
-- [ ] T042 [US2] Widen the provider factory: `providerRegistry map[string]func(*config.ServerEditionOAuthConfig) *OAuthProvider` (`oauth_providers.go:60-64`, `GetProvider :116-122`); legacy factories ignore everything but `TenantID`; **the provider is constructed once**: `NewOAuthHandler` resolves it through the registry and stores it as `h.provider` (no network I/O at construction — discovery stays lazy), and the two call sites `oauth_handler.go:129,193` read `h.provider` instead of calling `GetProvider` per request (today every call returns a fresh value, `oauth_providers.go:59-64,116-122`, so a discovery/JWKS cache on the provider would have request lifetime, not the [5 min, 24 h] TTL); the T036 counting test asserts one discovery fetch across login → callback → second login, a refetch after TTL expiry, and exactly one JWKS refetch per unknown-`kid` attempt — `internal/serveredition/auth/oauth_providers.go`, `internal/serveredition/auth/oauth_handler.go`, tests that swap the registry (`oauth_handler_test.go:97-118`, `integration_test.go:116-128`)
-- [ ] T043 [US2] Implement `oidc_jwks.go` (stdlib JWK → key, per-`kid` cache; measure with `wc -l`, budget 150) and `oidc_provider.go` (discovery cache, non-redirecting 10 s client, endpoint https rule, client-auth method choice, `BuildAuthURL` with `nonce`, `ExchangeCode`, verified ID token via `jwt/v5` with the allowed-alg intersection, `iss`/`aud`/`azp`/`exp`/`nbf`/`iat` (60 s), nonce, `email_verified`, groups from token then userinfo with the `sub` comparison); `parseIDToken` unreachable for `oidc` (retained for legacy); `OAuthUserInfo` + `Groups`, `EmailVerified` — `internal/serveredition/auth/oidc_provider.go`, `oidc_jwks.go`, `oauth_providers.go`
-- [ ] T044 [US2] `HandleLogin`/`HandleCallback`: nonce stored beside the state; bounded `pendingStates` (10,000, oldest evicted); closed reason enum type `LoginRefusal` with the FR-013 vocabulary (+ `authorization_denied` for an IdP authorization-response error — `error=access_denied` or any other RFC 6749 §4.1.2.1 code — arriving on the callback with a valid `state`; the state is consumed first, then the response classified; the IdP's `error`/`error_description` reach only the server log); one generic 403 page and one 503 page (templates with the request id); every callback branch mapped to exactly one reason and reported once through a handler-level `LoginResultObserver func(LoginResult)` hook (`LoginResult{RequestID, Surface, Reason LoginRefusal, UserID, EmailHash, Flags}`; nil = no-op) — PR-B's T038/T039 assert the typed result through it and PR-D's T107 installs the `auth_event` emitter on the same hook; **fault-injection seams**: `OAuthHandler` holds concrete `*users.UserStore`/`*SessionManager` fields and calls the package function `GenerateBearerToken` directly (`oauth_handler.go:25-30,242-289`), so it gains three narrow unexported interfaces/func fields — `loginStore` (`UpdateUserLogin`, `GetUserByEmail`), `sessionCreator` (`CreateSession`), `bearerSigner func(...) (string, error)` — defaulted to the real implementations in `NewOAuthHandler` and swappable from the test package (same package tests); **role derived live**: the handler takes the `ServerEditionConfigProvider` (`setup.go`) and derives the login role from the *current* `admin_emails` (today `h.config.IsAdminEmail` reads the boot pointer, `oauth_handler.go:25,254`, so a JWT minted after a hot-reload demotion carried the stale role — #1169's remaining horizon); T038/T039 mutate `admin_emails` after handler construction and assert the next login's role; groups upsert (`Groups`, `GroupsUpdatedAt`, wholesale replace) and subject binding with `SubjectRebindArmedAt` consumed atomically in a **transaction-owned** `users.(*UserStore).UpdateUserLogin(ctx, verified LoginClaims) (LoginOutcome, error)` — `LoginClaims{Email, Provider, Subject, Name, AvatarURL, Groups []string, GroupsKnown bool}`; the store re-reads the record **inside one `db.Update`** (by the email index), evaluates the subject rule there (`ProviderSubjectID` empty or equal → bind; provider changed → rebind + `Rebound=true`; different subject with `SubjectRebindArmedAt` set → rebind + clear the flag; different subject otherwise → `ErrSubjectMismatch`, nothing written; `Disabled` → `ErrUserDisabled`), writes groups/subject/provider/last-login in that same transaction and returns `LoginOutcome{User, Created, Rebound, RebindConsumed}` — a pre-mutated `*User` handed to the store cannot be a compare-and-set (today `GetUserByEmail` is a separate `View`, `store.go:128-164`, and `UpdateUser` only re-reads to maintain the email index, `:166-221`, so two callbacks could both observe the armed flag and rebind to different subjects); `HandleCallback` maps `LoginOutcome`/errors to the FR-013 reasons; `Provider`/`ProviderSubjectID` refreshed every login — `internal/serveredition/auth/oauth_handler.go`, `internal/serveredition/auth/login_pages.go` (new), `internal/serveredition/users/{models.go,store.go}`
-- [ ] T045 [P] [US2] Admin handlers: `enable` sets `subject_rebind_armed_at` on a real transition, `disable` clears it (`admin_handlers.go:220-306`); `GET /admin/users` returns `groups`, `groups_updated_at`, `subject_rebind_armed_at`; `GET /auth/me` returns `groups`, `groups_updated_at` — `internal/serveredition/api/admin_handlers.go`, `internal/serveredition/api/auth_endpoints.go`
-- [ ] T046 [US2] Harness: extend `internal/serveredition/setup_wiring_test.go` `newWiringHarness` with an in-process `tests/oauthserver` (OIDC) and a `loginAs(t, email, groups) *http.CookieJar` helper driving login → form POST → callback; add an `httptest` reverse-proxy helper that sets/strips `X-Forwarded-*` and rewrites `Host`, dialing from a chosen source address — `internal/serveredition/setup_wiring_test.go`, `internal/serveredition/harness_oidc_test.go` (new)
+- [x] T041 [US2] Config: add `IssuerURL`, `AllowInsecureIssuer`, `Scopes`, `GroupsClaim`, `EmailVerifiedPolicy`, `DisplayName` to `ServerEditionOAuthConfig` (`server_edition_config.go:31-37`); provider enum + rules in `Validate`, defaults in `ApplyDefaults`; `users/models.go:48` admits `oidc`; `cmd/mcpproxy/status_serveredition.go` unchanged (prints the value) — `internal/config/server_edition_config.go`, `internal/serveredition/users/models.go`
+- [x] T042 [US2] Widen the provider factory: `providerRegistry map[string]func(*config.ServerEditionOAuthConfig) *OAuthProvider` (`oauth_providers.go:60-64`, `GetProvider :116-122`); legacy factories ignore everything but `TenantID`; **the provider is constructed once**: `NewOAuthHandler` resolves it through the registry and stores it as `h.provider` (no network I/O at construction — discovery stays lazy), and the two call sites `oauth_handler.go:129,193` read `h.provider` instead of calling `GetProvider` per request (today every call returns a fresh value, `oauth_providers.go:59-64,116-122`, so a discovery/JWKS cache on the provider would have request lifetime, not the [5 min, 24 h] TTL); the T036 counting test asserts one discovery fetch across login → callback → second login, a refetch after TTL expiry, and exactly one JWKS refetch per unknown-`kid` attempt — `internal/serveredition/auth/oauth_providers.go`, `internal/serveredition/auth/oauth_handler.go`, tests that swap the registry (`oauth_handler_test.go:97-118`, `integration_test.go:116-128`)
+- [x] T043 [US2] Implement `oidc_jwks.go` (stdlib JWK → key, per-`kid` cache; measure with `wc -l`, budget 150) and `oidc_provider.go` (discovery cache, non-redirecting 10 s client, endpoint https rule, client-auth method choice, `BuildAuthURL` with `nonce`, `ExchangeCode`, verified ID token via `jwt/v5` with the allowed-alg intersection, `iss`/`aud`/`azp`/`exp`/`nbf`/`iat` (60 s), nonce, `email_verified`, groups from token then userinfo with the `sub` comparison); `parseIDToken` unreachable for `oidc` (retained for legacy); `OAuthUserInfo` + `Groups`, `EmailVerified` — `internal/serveredition/auth/oidc_provider.go`, `oidc_jwks.go`, `oauth_providers.go`
+- [x] T044 [US2] `HandleLogin`/`HandleCallback`: nonce stored beside the state; bounded `pendingStates` (10,000, oldest evicted); closed reason enum type `LoginRefusal` with the FR-013 vocabulary (+ `authorization_denied` for an IdP authorization-response error — `error=access_denied` or any other RFC 6749 §4.1.2.1 code — arriving on the callback with a valid `state`; the state is consumed first, then the response classified; the IdP's `error`/`error_description` reach only the server log); one generic 403 page and one 503 page (templates with the request id); every callback branch mapped to exactly one reason and reported once through a handler-level `LoginResultObserver func(LoginResult)` hook (`LoginResult{RequestID, Surface, Reason LoginRefusal, UserID, EmailHash, Flags}`; nil = no-op) — PR-B's T038/T039 assert the typed result through it and PR-D's T107 installs the `auth_event` emitter on the same hook; **fault-injection seams**: `OAuthHandler` holds concrete `*users.UserStore`/`*SessionManager` fields and calls the package function `GenerateBearerToken` directly (`oauth_handler.go:25-30,242-289`), so it gains three narrow unexported interfaces/func fields — `loginStore` (`UpdateUserLogin`, `GetUserByEmail`), `sessionCreator` (`CreateSession`), `bearerSigner func(...) (string, error)` — defaulted to the real implementations in `NewOAuthHandler` and swappable from the test package (same package tests); **role derived live**: the handler takes the `ServerEditionConfigProvider` (`setup.go`) and derives the login role from the *current* `admin_emails` (today `h.config.IsAdminEmail` reads the boot pointer, `oauth_handler.go:25,254`, so a JWT minted after a hot-reload demotion carried the stale role — #1169's remaining horizon); T038/T039 mutate `admin_emails` after handler construction and assert the next login's role; groups upsert (`Groups`, `GroupsUpdatedAt`, wholesale replace) and subject binding with `SubjectRebindArmedAt` consumed atomically in a **transaction-owned** `users.(*UserStore).UpdateUserLogin(ctx, verified LoginClaims) (LoginOutcome, error)` — `LoginClaims{Email, Provider, Subject, Name, AvatarURL, Groups []string, GroupsKnown bool}`; the store re-reads the record **inside one `db.Update`** (by the email index), evaluates the subject rule there (`ProviderSubjectID` empty or equal → bind; provider changed → rebind + `Rebound=true`; different subject with `SubjectRebindArmedAt` set → rebind + clear the flag; different subject otherwise → `ErrSubjectMismatch`, nothing written; `Disabled` → `ErrUserDisabled`), writes groups/subject/provider/last-login in that same transaction and returns `LoginOutcome{User, Created, Rebound, RebindConsumed}` — a pre-mutated `*User` handed to the store cannot be a compare-and-set (today `GetUserByEmail` is a separate `View`, `store.go:128-164`, and `UpdateUser` only re-reads to maintain the email index, `:166-221`, so two callbacks could both observe the armed flag and rebind to different subjects); `HandleCallback` maps `LoginOutcome`/errors to the FR-013 reasons; `Provider`/`ProviderSubjectID` refreshed every login — `internal/serveredition/auth/oauth_handler.go`, `internal/serveredition/auth/login_pages.go` (new), `internal/serveredition/users/{models.go,store.go}`
+- [x] T045 [P] [US2] Admin handlers: `enable` sets `subject_rebind_armed_at` on a real transition, `disable` clears it (`admin_handlers.go:220-306`); `GET /admin/users` returns `groups`, `groups_updated_at`, `subject_rebind_armed_at`; `GET /auth/me` returns `groups`, `groups_updated_at` — `internal/serveredition/api/admin_handlers.go`, `internal/serveredition/api/auth_endpoints.go`
+- [x] T046 [US2] Harness: extend `internal/serveredition/setup_wiring_test.go` `newWiringHarness` with an in-process `tests/oauthserver` (OIDC) and a `loginAs(t, email, groups) *http.CookieJar` helper driving login → form POST → callback; add an `httptest` reverse-proxy helper that sets/strips `X-Forwarded-*` and rewrites `Host`, dialing from a chosen source address — `internal/serveredition/setup_wiring_test.go`, `internal/serveredition/harness_oidc_test.go` (new)
 
 ## Phase B.3 — Front door behind an ingress (FR-025..FR-030; US2.6–2.10)
 
 ### Tests first
 
-- [ ] T047 [US2] **[compile-red until T050]** Write failing `internal/config/trusted_proxies_test.go`: CIDR/IP parsing, `ForwardedHeaders(r, trusted)` honours `X-Forwarded-For` (right-most untrusted hop)/`X-Real-IP`/`X-Forwarded-Proto`/`X-Forwarded-Host` only from a trusted peer; env `MCPPROXY_TRUSTED_PROXIES`; `DetectConfigChanges` reports `trusted_proxies` live; **live consumer test**: every replaced reader (T050) is handed a `func() []string` provider — mutate the provider's list after construction and assert the next request honours/ignores `X-Forwarded-*` accordingly (a "live" key whose readers captured a boot slice is not live) — `internal/config/trusted_proxies_test.go`, `internal/runtime/config_hotreload_test.go`, `internal/httpapi/swagger_forwarded_test.go`, `internal/serveredition/auth/session_store_forwarded_test.go`
-- [ ] T048 [P] [US2] **[compile-red until T050 (`config.ForwardedHeaders`, the trusted-proxy provider) and T051]** Write failing `internal/serveredition/auth/front_door_test.go` (harness): `public_url` set + ingress rewriting `Host` and stripping XFP → `redirect_uri` is `<public_url>/api/v1/auth/callback` and the cookie is `Secure`; **boot log** (US2.1): with `public_url` set, setup logs one INFO line carrying the resolved public URL and callback URL and makes no IdP request (counting fake); `public_url` unset + untrusted XFP/XFF → ignored; trusted → honoured; `session_cookie_secure` `auto|true|false` matrix; `MCPPROXY_PUBLIC_URL` overrides the file value, an unset variable leaves it, and the personal build ignores the variable (opaque carrier); validation refuses `false` with https `public_url`/TLS; unset `public_url` on a non-loopback listener → boot warning + `doctor` finding **as a `runtime_warnings` entry of `GET /api/v1/diagnostics`** (`mcpproxy doctor` only renders the daemon's `contracts.Diagnostics`, `doctor_cmd.go:100-128`; findings are produced by `management.(*service).Doctor`, `internal/management/diagnostics.go:47-227` — T052 adds the seam; asserted through the service, `internal/management/diagnostics_serveredition_test.go`); scheme-disagreement warning with request id; `redirect_uri` matrix (`https://evil.example/`, `//evil.example`, `/\evil.example`, `javascript:`, `/my/tokens?x=1`, plus the FR-028 control-character and encoded forms — `/ok%0D%0ASet-Cookie:x`, `/ok%00`, `/%5Cevil.example`, `/%2F%2Fevil.example` (`r.URL.Query().Get` percent-decodes, so the check runs on the decoded value), a literal tab, `/ok\r\n` — each → `/ui/`) → `/ui/` or honoured, `RedirectRejected` carried on the pending state; `connector_provider.go` base URL from `public_url` (no first-seen latch) — `internal/serveredition/auth/front_door_test.go`, `internal/serveredition/api/connector_provider_test.go`
-- [ ] T049 [P] [US2] **[compile-red until T052 (accessors) and T053 (route)]** Write failing `internal/server/mcp_auth_forced_test.go` (`-tags server`, and a `!server` twin): with `server_edition.enabled` and `require_mcp_auth: false`, no credential → 401, session cookie → 401, user JWT → 401, agent token/API key/socket unchanged; boot notice logged; personal build unchanged; `internal/serveredition/api/auth_provider_probe_test.go`: `GET /api/v1/auth/provider` returns only `{display_name}` (fallback to the provider family name when `display_name` is unset; legacy providers too), no `pendingStates` growth, **404 when `server_edition.enabled` is false or the `oauth` block is absent** (the route is registered only by `SetupAll` on an enabled block, so a disabled server build answers like the personal build), 404 on the personal build (`internal/httpapi` stub test) — files above
+- [x] T047 [US2] **[compile-red until T050]** Write failing `internal/config/trusted_proxies_test.go`: CIDR/IP parsing, `ForwardedHeaders(r, trusted)` honours `X-Forwarded-For` (right-most untrusted hop)/`X-Real-IP`/`X-Forwarded-Proto`/`X-Forwarded-Host` only from a trusted peer; env `MCPPROXY_TRUSTED_PROXIES`; `DetectConfigChanges` reports `trusted_proxies` live; **live consumer test**: every replaced reader (T050) is handed a `func() []string` provider — mutate the provider's list after construction and assert the next request honours/ignores `X-Forwarded-*` accordingly (a "live" key whose readers captured a boot slice is not live) — `internal/config/trusted_proxies_test.go`, `internal/runtime/config_hotreload_test.go`, `internal/httpapi/swagger_forwarded_test.go`, `internal/serveredition/auth/session_store_forwarded_test.go`
+- [x] T048 [P] [US2] **[compile-red until T050 (`config.ForwardedHeaders`, the trusted-proxy provider) and T051]** Write failing `internal/serveredition/auth/front_door_test.go` (harness): `public_url` set + ingress rewriting `Host` and stripping XFP → `redirect_uri` is `<public_url>/api/v1/auth/callback` and the cookie is `Secure`; **boot log** (US2.1): with `public_url` set, setup logs one INFO line carrying the resolved public URL and callback URL and makes no IdP request (counting fake); `public_url` unset + untrusted XFP/XFF → ignored; trusted → honoured; `session_cookie_secure` `auto|true|false` matrix; `MCPPROXY_PUBLIC_URL` overrides the file value, an unset variable leaves it, and the personal build ignores the variable (opaque carrier); validation refuses `false` with https `public_url`/TLS; unset `public_url` on a non-loopback listener → boot warning + `doctor` finding **as a `runtime_warnings` entry of `GET /api/v1/diagnostics`** (`mcpproxy doctor` only renders the daemon's `contracts.Diagnostics`, `doctor_cmd.go:100-128`; findings are produced by `management.(*service).Doctor`, `internal/management/diagnostics.go:47-227` — T052 adds the seam; asserted through the service, `internal/management/diagnostics_serveredition_test.go`); scheme-disagreement warning with request id; `redirect_uri` matrix (`https://evil.example/`, `//evil.example`, `/\evil.example`, `javascript:`, `/my/tokens?x=1`, plus the FR-028 control-character and encoded forms — `/ok%0D%0ASet-Cookie:x`, `/ok%00`, `/%5Cevil.example`, `/%2F%2Fevil.example` (`r.URL.Query().Get` percent-decodes, so the check runs on the decoded value), a literal tab, `/ok\r\n` — each → `/ui/`) → `/ui/` or honoured, `RedirectRejected` carried on the pending state; `connector_provider.go` base URL from `public_url` (no first-seen latch) — `internal/serveredition/auth/front_door_test.go`, `internal/serveredition/api/connector_provider_test.go`
+- [x] T049 [P] [US2] **[compile-red until T052 (accessors) and T053 (route)]** Write failing `internal/server/mcp_auth_forced_test.go` (`-tags server`, and a `!server` twin): with `server_edition.enabled` and `require_mcp_auth: false`, no credential → 401, session cookie → 401, user JWT → 401, agent token/API key/socket unchanged; boot notice logged; personal build unchanged; `internal/serveredition/api/auth_provider_probe_test.go`: `GET /api/v1/auth/provider` returns only `{display_name}` (fallback to the provider family name when `display_name` is unset; legacy providers too), no `pendingStates` growth, **404 when `server_edition.enabled` is false or the `oauth` block is absent** (the route is registered only by `SetupAll` on an enabled block, so a disabled server build answers like the personal build), 404 on the personal build (`internal/httpapi` stub test) — files above
 
 ### Implementation
 
-- [ ] T050 [US2] `internal/config/trusted_proxies.go` (edition-neutral): `TrustedProxies []string` on `Config`, parsing, `ForwardedHeaders`, env override in `applyTLSEnvOverrides` (`loader.go:629-790`), `DetectConfigChanges` `slices.Equal` clause; **validation wired into both `Config.Validate()` and `ValidateDetailed()`** (`validateTrustedProxies(cfg)` called from each, message text from `contracts/config-keys.md`) so boot, PATCH and `/config/apply` refuse an unparsable entry identically (FR-039) — T047 drives all four doors, not only the parser; replace the four raw readers (`session_store.go:129-151`, `oauth_handler.go:413-423`, `connector_provider.go:126-135`, `httpapi/swagger.go:105-114`) — each is a static function today with no config access, so each consumer gains a `trustedProxies func() []string` **provider** (httpapi: from the server's config provider; serveredition: from `Dependencies.ConfigProvider`) evaluated per request, never a slice captured at construction (the key is declared live in `contracts/config-keys.md`); add the **request-metadata tag** PR-D's audit line needs (`RemoteAddr` is on `*http.Request`, never on the context — `transport/context.go:20-30` carries only the connection source): an edition-neutral middleware `httpapi.tagRequestMeta` installed on the `/api/v1` group, `/events` and the `/mcp*` mounts that stores `{ClientIP: ForwardedHeaders(r, trusted).ClientIP, Mount: mcp|api}` on the context (`reqcontext.RequestMeta`), the mount value fixed by the mount point and never by a header; test both mounts and trusted/untrusted peers — files above, `internal/runtime/config_hotreload.go`, `internal/httpapi/middleware.go`, `internal/reqcontext/*.go`, `internal/server/server.go`
-- [ ] T051 [US2] `PublicURL`, `SessionCookieSecure` on `ServerEditionConfig`; validation + `ApplyDefaults` — the `session_cookie_secure: false` × (`https` `public_url` **or** `tls.enabled`) refusal needs the top-level `Config.TLS`, which `ServerEditionConfig.Validate` cannot see, so it lives in the build-tagged `*Config`-level bridge `validateServerEditionConfig(cfg *Config)` of T019 (`config_validate_serveredition.go`, reached from `Config.Validate()`/`ValidateDetailed()`) and T048 drives it through `Config.Validate`, PATCH and `/config/apply`; env override `MCPPROXY_PUBLIC_URL` via a build-tagged `applyServerEditionEnvOverrides(cfg)` (`internal/config/env_serveredition.go` + `_stub.go` no-op) called from `applyTLSEnvOverrides` (`loader.go:629`) — the one nested `server_edition.*` key with an env alias (FR-025); `buildCallbackURL` and `connector_provider.go:50-62` prefer `public_url`; `NewSessionManager(..., securePolicy)` replacing the hardcoded `false` at `setup.go:115` with `auto|true|false` resolution (`public_url` scheme, in-process TLS, trusted XFP — the trusted list read through the live provider of T050); one INFO boot line with the resolved public URL and callback URL (US2.1); boot warnings + `doctor` findings (via the T052 `config.DoctorFindings` source — `cmd/mcpproxy/doctor*.go` is **not** touched: it renders `runtime_warnings` as today); `redirect_uri` sanitiser in `HandleLogin` (`oauth_handler.go:115-118`) — `internal/config/server_edition_config.go`, `internal/serveredition/setup.go`, `internal/serveredition/auth/{oauth_handler.go,session_store.go}`, `internal/serveredition/api/connector_provider.go`, `internal/config/doctor_findings{,_stub}.go`
-- [ ] T052 [US2] Build-tagged accessors `internal/config/serveredition_accessors.go` (`//go:build server`) + `_stub.go`: `EffectiveRequireMCPAuth`, `ServerEditionEnabled`, `IdPProviderFamily`, `PublicURL`; `mcpAuthMiddleware` (`internal/server/server.go:353,450`) uses `EffectiveRequireMCPAuth`; boot notice + `doctor` finding for an overridden `require_mcp_auth: false`. **Doctor seam** (there is no `cmd/mcpproxy` producer: `doctor` fetches `GET /api/v1/diagnostics`, `doctor_cmd.go:100-128`, produced by `management.(*service).Doctor`, `internal/management/diagnostics.go:47-227`, which appends free-text `RuntimeWarnings` and counts them in `TotalIssues`): `management.Service` gains `AddRuntimeWarningSource(func() []string)` (guarded like `scanEnricher`, `service.go:178-182`), consulted by `Doctor` after the TCC probe (`:210-213`); `internal/server` registers two sources at boot — `config.DoctorFindings(cfg)` (edition-neutral file `internal/config/doctor_findings.go` + build-tagged `doctor_findings_serveredition{,_stub}.go` for the server-only findings: overridden `require_mcp_auth`, unset `public_url` on a non-loopback listener, explicit `session_cookie_secure: false`, unknown `access` map names — T074 adds the last) reading the **live** config through the runtime's config provider, and in PR-D the audit sink's failure counter (T109). Test through the service (`internal/management/diagnostics_serveredition_test.go`, `-tags server`) and one `doctor` JSON/pretty render test on a fixture `Diagnostics` — files above, `internal/server/server.go`, `internal/management/{service.go,diagnostics.go}`, `internal/config/doctor_findings{,_serveredition,_stub}.go`
-- [ ] T053 [P] [US2] Public `GET /api/v1/auth/provider` in `internal/serveredition/api/auth_endpoints.go` (mounted beside login/callback at `setup.go:160-161`, outside every auth group, only when the block is enabled — a disabled block registers nothing, so 404 falls out of chi exactly as on the personal build); personal build has no route (404 falls out of chi) — `internal/serveredition/api/auth_endpoints.go`, `internal/serveredition/setup.go`
-- [ ] T054a [P] [US2] **[behaviour-red]** Frontend unit tests first: extend `frontend/tests/unit/settings-server-edition-wording.spec.ts` (the OIDC + front-door rows of `contracts/config-keys.md` exist, `client_secret` does not) and add `auth-provider-probe.spec.ts` (the auth store calls `GET /api/v1/auth/provider` before any authenticated call; `Login.vue` renders `display_name`; a 404 from the probe means personal edition) — red because none of the rows/probe exist — `frontend/tests/unit/*.spec.ts`
-- [ ] T054 [US2] (after T054a) Web UI: `services/auth-api.ts` probe; `stores/auth.ts` learns the edition from the probe before any authenticated call; `Login.vue:28` labels the button with `display_name`; `fields.ts` gains the OIDC + front-door rows of `contracts/config-keys.md` (no `client_secret`; `oauth.allow_insecure_issuer` is deliberately **Raw-JSON-only** — a loopback-only development toggle that must not look like a normal setting); the retained keys keep their **Raw-JSON-only** disposition of today (`admin_emails`, `session_ttl`, `bearer_token_ttl`, `oauth.client_id`, `oauth.tenant_id`, `oauth.allowed_domains` — the `Settings` column of `contracts/config-keys.md` is the authority; `credential_encryption_key` is secret/env-only and `store_idp_tokens` is deprecated: neither ever gets a row), and `settings-server-edition-wording.spec.ts` asserts the exact row set so an undecided key cannot appear by accident — `frontend/src/services/auth-api.ts`, `frontend/src/stores/auth.ts`, `frontend/src/views/teams/Login.vue`, `frontend/src/views/settings/fields.ts`
+- [x] T050 [US2] `internal/config/trusted_proxies.go` (edition-neutral): `TrustedProxies []string` on `Config`, parsing, `ForwardedHeaders`, env override in `applyTLSEnvOverrides` (`loader.go:629-790`), `DetectConfigChanges` `slices.Equal` clause; **validation wired into both `Config.Validate()` and `ValidateDetailed()`** (`validateTrustedProxies(cfg)` called from each, message text from `contracts/config-keys.md`) so boot, PATCH and `/config/apply` refuse an unparsable entry identically (FR-039) — T047 drives all four doors, not only the parser; replace the four raw readers (`session_store.go:129-151`, `oauth_handler.go:413-423`, `connector_provider.go:126-135`, `httpapi/swagger.go:105-114`) — each is a static function today with no config access, so each consumer gains a `trustedProxies func() []string` **provider** (httpapi: from the server's config provider; serveredition: from `Dependencies.ConfigProvider`) evaluated per request, never a slice captured at construction (the key is declared live in `contracts/config-keys.md`); add the **request-metadata tag** PR-D's audit line needs (`RemoteAddr` is on `*http.Request`, never on the context — `transport/context.go:20-30` carries only the connection source): an edition-neutral middleware `httpapi.tagRequestMeta` installed on the `/api/v1` group, `/events` and the `/mcp*` mounts that stores `{ClientIP: ForwardedHeaders(r, trusted).ClientIP, Mount: mcp|api}` on the context (`reqcontext.RequestMeta`), the mount value fixed by the mount point and never by a header; test both mounts and trusted/untrusted peers — files above, `internal/runtime/config_hotreload.go`, `internal/httpapi/middleware.go`, `internal/reqcontext/*.go`, `internal/server/server.go`
+- [x] T051 [US2] `PublicURL`, `SessionCookieSecure` on `ServerEditionConfig`; validation + `ApplyDefaults` — the `session_cookie_secure: false` × (`https` `public_url` **or** `tls.enabled`) refusal needs the top-level `Config.TLS`, which `ServerEditionConfig.Validate` cannot see, so it lives in the build-tagged `*Config`-level bridge `validateServerEditionConfig(cfg *Config)` of T019 (`config_validate_serveredition.go`, reached from `Config.Validate()`/`ValidateDetailed()`) and T048 drives it through `Config.Validate`, PATCH and `/config/apply`; env override `MCPPROXY_PUBLIC_URL` via a build-tagged `applyServerEditionEnvOverrides(cfg)` (`internal/config/env_serveredition.go` + `_stub.go` no-op) called from `applyTLSEnvOverrides` (`loader.go:629`) — the one nested `server_edition.*` key with an env alias (FR-025); `buildCallbackURL` and `connector_provider.go:50-62` prefer `public_url`; `NewSessionManager(..., securePolicy)` replacing the hardcoded `false` at `setup.go:115` with `auto|true|false` resolution (`public_url` scheme, in-process TLS, trusted XFP — the trusted list read through the live provider of T050); one INFO boot line with the resolved public URL and callback URL (US2.1); boot warnings + `doctor` findings (via the T052 `config.DoctorFindings` source — `cmd/mcpproxy/doctor*.go` is **not** touched: it renders `runtime_warnings` as today); `redirect_uri` sanitiser in `HandleLogin` (`oauth_handler.go:115-118`) — `internal/config/server_edition_config.go`, `internal/serveredition/setup.go`, `internal/serveredition/auth/{oauth_handler.go,session_store.go}`, `internal/serveredition/api/connector_provider.go`, `internal/config/doctor_findings{,_stub}.go`
+- [x] T052 [US2] Build-tagged accessors `internal/config/serveredition_accessors.go` (`//go:build server`) + `_stub.go`: `EffectiveRequireMCPAuth`, `ServerEditionEnabled`, `IdPProviderFamily`, `PublicURL`; `mcpAuthMiddleware` (`internal/server/server.go:353,450`) uses `EffectiveRequireMCPAuth`; boot notice + `doctor` finding for an overridden `require_mcp_auth: false`. **Doctor seam** (there is no `cmd/mcpproxy` producer: `doctor` fetches `GET /api/v1/diagnostics`, `doctor_cmd.go:100-128`, produced by `management.(*service).Doctor`, `internal/management/diagnostics.go:47-227`, which appends free-text `RuntimeWarnings` and counts them in `TotalIssues`): `management.Service` gains `AddRuntimeWarningSource(func() []string)` (guarded like `scanEnricher`, `service.go:178-182`), consulted by `Doctor` after the TCC probe (`:210-213`); `internal/server` registers two sources at boot — `config.DoctorFindings(cfg)` (edition-neutral file `internal/config/doctor_findings.go` + build-tagged `doctor_findings_serveredition{,_stub}.go` for the server-only findings: overridden `require_mcp_auth`, unset `public_url` on a non-loopback listener, explicit `session_cookie_secure: false`, unknown `access` map names — T074 adds the last) reading the **live** config through the runtime's config provider, and in PR-D the audit sink's failure counter (T109). Test through the service (`internal/management/diagnostics_serveredition_test.go`, `-tags server`) and one `doctor` JSON/pretty render test on a fixture `Diagnostics` — files above, `internal/server/server.go`, `internal/management/{service.go,diagnostics.go}`, `internal/config/doctor_findings{,_serveredition,_stub}.go`
+- [x] T053 [P] [US2] Public `GET /api/v1/auth/provider` in `internal/serveredition/api/auth_endpoints.go` (mounted beside login/callback at `setup.go:160-161`, outside every auth group, only when the block is enabled — a disabled block registers nothing, so 404 falls out of chi exactly as on the personal build); personal build has no route (404 falls out of chi) — `internal/serveredition/api/auth_endpoints.go`, `internal/serveredition/setup.go`
+- [x] T054a [P] [US2] **[behaviour-red]** Frontend unit tests first: extend `frontend/tests/unit/settings-server-edition-wording.spec.ts` (the OIDC + front-door rows of `contracts/config-keys.md` exist, `client_secret` does not) and add `auth-provider-probe.spec.ts` (the auth store calls `GET /api/v1/auth/provider` before any authenticated call; `Login.vue` renders `display_name`; a 404 from the probe means personal edition) — red because none of the rows/probe exist — `frontend/tests/unit/*.spec.ts`
+- [x] T054 [US2] (after T054a) Web UI: `services/auth-api.ts` probe; `stores/auth.ts` learns the edition from the probe before any authenticated call; `Login.vue:28` labels the button with `display_name`; `fields.ts` gains the OIDC + front-door rows of `contracts/config-keys.md` (no `client_secret`; `oauth.allow_insecure_issuer` is deliberately **Raw-JSON-only** — a loopback-only development toggle that must not look like a normal setting); the retained keys keep their **Raw-JSON-only** disposition of today (`admin_emails`, `session_ttl`, `bearer_token_ttl`, `oauth.client_id`, `oauth.tenant_id`, `oauth.allowed_domains` — the `Settings` column of `contracts/config-keys.md` is the authority; `credential_encryption_key` is secret/env-only and `store_idp_tokens` is deprecated: neither ever gets a row), and `settings-server-edition-wording.spec.ts` asserts the exact row set so an undecided key cannot appear by accident — `frontend/src/services/auth-api.ts`, `frontend/src/stores/auth.ts`, `frontend/src/views/teams/Login.vue`, `frontend/src/views/settings/fields.ts`
 
 ## Phase B.4 — Config wiring for `server_edition` (FR-039 part 2)
 
-- [ ] T055 [US2] **[behaviour-red]** (the keys exist after T041/T051; the clause does not) Write failing `internal/runtime/config_hotreload_serveredition_test.go` (`-tags server`): an `enabled`/`oauth.*`/`public_url`/`session_cookie_secure`/`credential_encryption_key`/TTL edit → `RequiresRestart` with the reason and `ChangedFields: server_edition` (one case per key; `credential_encryption_key` is bound at setup, `setup.go:120-126`, so it is restart-pinned too); an `admin_emails`-only edit → live, `ChangedFields: server_edition.admin_emails`; a personal-build twin asserts raw-byte comparison reports `server_edition` changed-and-restart-pinned — `internal/runtime/config_hotreload_serveredition_test.go`
-- [ ] T056 [US2] Implement the clauses (`jsonEqual` on a projection struct; `slices.Equal` for `admin_emails`) in `internal/runtime/config_hotreload.go` after the `update_check` clause (`:413-417`), build-tagged projection helper in `internal/config`. Keep the function's existing early-return shape (`:92-182`: a `listen`/TLS/data-dir/API-key/timeout change returns immediately with only that field, and the restart re-reads everything) — the new clauses follow the same rule, so T055 tests single-key edits only and documents that a mixed edit with one of those keys reports the early-return key alone, as every existing key does — `internal/runtime/config_hotreload.go`, `internal/config/serveredition_accessors{,_stub}.go`
-- [ ] T057 [P] [US2] Docs: `server_edition` reference section in `docs/configuration/config-file.md` — **one complete key table**: every PR-B key *and* the retained keys `enabled`, `admin_emails`, `session_ttl`, `bearer_token_ttl`, `credential_encryption_key` (+ `MCPPROXY_CRED_KEY`), `store_idp_tokens` (deprecated, no-op), `oauth.{provider,client_id,client_secret,tenant_id,allowed_domains}`, and a "removed keys" row for `max_user_servers`/`workspace_idle_timeout` with their boot diagnostic text (default, restart/live, validation text, the per-IdP groups-claim table from spec Edge Cases, the `public_url`/`trusted_proxies` container topology, `email_verified_policy` cost note); `docs/configuration/environment-variables.md` (`MCPPROXY_TRUSTED_PROXIES`, `MCPPROXY_PUBLIC_URL`, and `MCPPROXY_CRED_KEY` — its only page today is `idp-token-storage.md`, which T023 tombstones); `docs/operations/reverse-proxy.md` (`trusted_proxies`; `trusted_hosts` is not the SSO control); `docs/getting-started/installation.md:368-400` Docker recipe (`public_url`, `trusted_proxies`, `${env:}` secrets); `docs/development/server-edition-multiuser-auth.md:4,9,13-31` (four providers); root `docs/configuration.md` rows for `trusted_proxies` — files above
-- [ ] T058 [P] [US2] `make swagger` for `trusted_proxies` on the `Config` schema; `make swagger-verify` clean; `go run ./cmd/generate-types` + `TestContractsInSync` (expected no-op, proven); Swift `SettingsCatalog.swift` read-only row for `trusted_proxies`; run `python3 scripts/check-settings-parity.py` and `swift test` from `native/macos/MCPProxy` locally (both are required CI jobs in `native-tests.yml:83,97` and neither is in the Go gate set) — `oas/swagger.yaml`, `oas/docs.go`, `native/macos/MCPProxy/.../SettingsCatalog.swift`
-- [ ] T059 [P] [US2] `.github/RELEASE_NOTICE.md` PR-B bullets: forced MCP auth under the server edition, `trusted_proxies` now gating forwarded headers, generic OIDC, `email_verified_policy` default — `.github/RELEASE_NOTICE.md`
+- [x] T055 [US2] **[behaviour-red]** (the keys exist after T041/T051; the clause does not) Write failing `internal/runtime/config_hotreload_serveredition_test.go` (`-tags server`): an `enabled`/`oauth.*`/`public_url`/`session_cookie_secure`/`credential_encryption_key`/TTL edit → `RequiresRestart` with the reason and `ChangedFields: server_edition` (one case per key; `credential_encryption_key` is bound at setup, `setup.go:120-126`, so it is restart-pinned too); an `admin_emails`-only edit → live, `ChangedFields: server_edition.admin_emails`; a personal-build twin asserts raw-byte comparison reports `server_edition` changed-and-restart-pinned — `internal/runtime/config_hotreload_serveredition_test.go`
+- [x] T056 [US2] Implement the clauses (`jsonEqual` on a projection struct; `slices.Equal` for `admin_emails`) in `internal/runtime/config_hotreload.go` after the `update_check` clause (`:413-417`), build-tagged projection helper in `internal/config`. Keep the function's existing early-return shape (`:92-182`: a `listen`/TLS/data-dir/API-key/timeout change returns immediately with only that field, and the restart re-reads everything) — the new clauses follow the same rule, so T055 tests single-key edits only and documents that a mixed edit with one of those keys reports the early-return key alone, as every existing key does — `internal/runtime/config_hotreload.go`, `internal/config/serveredition_accessors{,_stub}.go`
+- [x] T057 [P] [US2] Docs: `server_edition` reference section in `docs/configuration/config-file.md` — **one complete key table**: every PR-B key *and* the retained keys `enabled`, `admin_emails`, `session_ttl`, `bearer_token_ttl`, `credential_encryption_key` (+ `MCPPROXY_CRED_KEY`), `store_idp_tokens` (deprecated, no-op), `oauth.{provider,client_id,client_secret,tenant_id,allowed_domains}`, and a "removed keys" row for `max_user_servers`/`workspace_idle_timeout` with their boot diagnostic text (default, restart/live, validation text, the per-IdP groups-claim table from spec Edge Cases, the `public_url`/`trusted_proxies` container topology, `email_verified_policy` cost note); `docs/configuration/environment-variables.md` (`MCPPROXY_TRUSTED_PROXIES`, `MCPPROXY_PUBLIC_URL`, and `MCPPROXY_CRED_KEY` — its only page today is `idp-token-storage.md`, which T023 tombstones); `docs/operations/reverse-proxy.md` (`trusted_proxies`; `trusted_hosts` is not the SSO control); `docs/getting-started/installation.md:368-400` Docker recipe (`public_url`, `trusted_proxies`, `${env:}` secrets); `docs/development/server-edition-multiuser-auth.md:4,9,13-31` (four providers); root `docs/configuration.md` rows for `trusted_proxies` — files above
+- [x] T058 [P] [US2] `make swagger` for `trusted_proxies` on the `Config` schema; `make swagger-verify` clean; `go run ./cmd/generate-types` + `TestContractsInSync` (expected no-op, proven); Swift `SettingsCatalog.swift` read-only row for `trusted_proxies`; run `python3 scripts/check-settings-parity.py` and `swift test` from `native/macos/MCPProxy` locally (both are required CI jobs in `native-tests.yml:83,97` and neither is in the Go gate set) — `oas/swagger.yaml`, `oas/docs.go`, `native/macos/MCPProxy/.../SettingsCatalog.swift`
+- [x] T059 [P] [US2] `.github/RELEASE_NOTICE.md` PR-B bullets: forced MCP auth under the server edition, `trusted_proxies` now gating forwarded headers, generic OIDC, `email_verified_policy` default — `.github/RELEASE_NOTICE.md`
 
 ## Phase B.5 — US7: telemetry v13 (P3)
 
-- [ ] T060 [US7] **[compile-red until T061]** Write failing `internal/telemetry/payload_v13_test.go`: server-edition fixture → `server_edition_enabled: true`, `idp_provider: "oidc"`, `user_count_bucket: "1-10"`, `env_markers.is_container` present; personal → `false`/`"none"`/`"0"`; the server-edition fixture lives in a `//go:build server` helper file and the personal fixture in a `//go:build !server` twin so both accessors are proven under their own tag (the shared test body is untagged); `TestPayloadHasNoForbiddenSubstrings` + `ScanForPII` with issuer host, group names, emails, server names as forbidden; `schema_version_guard_test.go` asserting no v12 pin survives — the guard assembles its regex from fragments (`"schema_version\":" + "12"` etc.) and skips its own file, otherwise its literal self-matches — `internal/telemetry/payload_v13_test.go`, `internal/telemetry/payload_v13_fixture_server_test.go`, `internal/telemetry/payload_v13_fixture_personal_test.go`, `internal/telemetry/schema_version_guard_test.go`
-- [ ] T061 [US7] Implement: `FeatureFlagSnapshot` fields via the accessors; `UserCountBucket` splice with a nil-safe `userCounter` installed from `internal/server/serveredition_wire.go`; `SchemaVersion = 13` + comment; update the eleven v12 sites (`payload_v7_test.go:20,81,112`, `payload_v2_test.go:91,138`, `telemetry_test.go:315,323`, `payload_privacy_test.go:147`, `current_error_codes_test.go:268`, `tpa_scanner_test.go:267`, `tpa_funnel_v9_test.go:263`); `docs/features/telemetry.md` — `internal/telemetry/{feature_flags.go,telemetry.go}`, the eleven test files, `internal/server/serveredition_wire.go`, `docs/features/telemetry.md`
+- [x] T060 [US7] **[compile-red until T061]** Write failing `internal/telemetry/payload_v13_test.go`: server-edition fixture → `server_edition_enabled: true`, `idp_provider: "oidc"`, `user_count_bucket: "1-10"`, `env_markers.is_container` present; personal → `false`/`"none"`/`"0"`; the server-edition fixture lives in a `//go:build server` helper file and the personal fixture in a `//go:build !server` twin so both accessors are proven under their own tag (the shared test body is untagged); `TestPayloadHasNoForbiddenSubstrings` + `ScanForPII` with issuer host, group names, emails, server names as forbidden; `schema_version_guard_test.go` asserting no v12 pin survives — the guard assembles its regex from fragments (`"schema_version\":" + "12"` etc.) and skips its own file, otherwise its literal self-matches — `internal/telemetry/payload_v13_test.go`, `internal/telemetry/payload_v13_fixture_server_test.go`, `internal/telemetry/payload_v13_fixture_personal_test.go`, `internal/telemetry/schema_version_guard_test.go`
+- [x] T061 [US7] Implement: `FeatureFlagSnapshot` fields via the accessors; `UserCountBucket` splice with a nil-safe `userCounter` installed from `internal/server/serveredition_wire.go`; `SchemaVersion = 13` + comment; update the eleven v12 sites (`payload_v7_test.go:20,81,112`, `payload_v2_test.go:91,138`, `telemetry_test.go:315,323`, `payload_privacy_test.go:147`, `current_error_codes_test.go:268`, `tpa_scanner_test.go:267`, `tpa_funnel_v9_test.go:263`); `docs/features/telemetry.md` — `internal/telemetry/{feature_flags.go,telemetry.go}`, the eleven test files, `internal/server/serveredition_wire.go`, `docs/features/telemetry.md`
 
 ## Phase B.6 — Delivery
 
-- [ ] T062 [US2] Real-instance verification: quickstart §0–§4 + §6 (`--phase b`: login, `/auth/me` groups, JWT/cookie on `/mcp` → 401, no-credential `/mcp` → 401 with `require_mcp_auth: false`), the open-redirect case, one tamper case (`-token-error bad-signature` → 403 generic page, no user created), `public_url` with a `Host`-rewriting `socat`/`curl -H Host:` front; record in verification.md — `verification.md`
-- [ ] T063 [US7] Real-instance verification: dump the heartbeat payload (`GET /api/v1/telemetry/payload` with the API key) from the server-edition instance and the personal instance; grep for the issuer host and emails (0 hits); record — `verification.md`
-- [ ] T064 [X] Full gate set; `wc -l internal/serveredition/auth/oidc_jwks.go` recorded against the 150-line budget — `verification.md`
-- [ ] T065 [X] Cross-model review (briefs: provider+verification / handler+pages+subject binding / front door+config / telemetry), ≤ 10 rounds — `verification.md`
-- [ ] T066 [X] Open PR-B (`Related #1169` for the live-role reuse); roadmap tick; `gen-roadmap.py --check`; CI green; no merge without instruction — `roadmap.yaml`, `ROADMAP.md`
+- [x] T062 [US2] Real-instance verification: quickstart §0–§4 + §6 (`--phase b`: login, `/auth/me` groups, JWT/cookie on `/mcp` → 401, no-credential `/mcp` → 401 with `require_mcp_auth: false`), the open-redirect case, one tamper case (`-token-error bad-signature` → 403 generic page, no user created), `public_url` with a `Host`-rewriting `socat`/`curl -H Host:` front; record in verification.md — `verification.md`
+- [x] T063 [US7] Real-instance verification: dump the heartbeat payload (`GET /api/v1/telemetry/payload` with the API key) from the server-edition instance and the personal instance; grep for the issuer host and emails (0 hits); record — `verification.md`
+- [x] T064 [X] Full gate set; `wc -l internal/serveredition/auth/oidc_jwks.go` recorded against the 150-line budget — `verification.md`
+- [x] T065 [X] Cross-model review (briefs: provider+verification / handler+pages+subject binding / front door+config / telemetry), ≤ 10 rounds — `verification.md`
+- [x] T066 [X] Open PR-B (`Related #1169` for the live-role reuse); roadmap tick; `gen-roadmap.py --check`; CI green; no merge without instruction — `roadmap.yaml`, `ROADMAP.md`
 
 ---
 
diff --git a/specs/107-server-edition-sso-hardening/verification.md b/specs/107-server-edition-sso-hardening/verification.md
index 1c167b585..bb6cb30da 100644
--- a/specs/107-server-edition-sso-hardening/verification.md
+++ b/specs/107-server-edition-sso-hardening/verification.md
@@ -139,10 +139,243 @@ Merge-readiness caveat (found while fetching `origin/main` for the gofmt row): `
 
 ### Real instance
 
+Run 2026-09-17 on HEAD `5ad3a080d` (`fix(spec-107): cross-review round 6 for PR-B`), server binaries built fresh from this tree into session-scratchpad rigs (never `~/.mcpproxy`); every instance ran on its own high port with **both** `--config` and `--data-dir`, started as its own background process, readiness polled on `/readyz`, and torn down by PID at the end (`kill 15669 15668 15642 15640 15774`; the unrelated foreign `oauthserver -port 19271 -per-method-auth`, pid 88569, and Comet/Chrome renderer processes were left untouched).
+
+**T062 §0–§4 (quickstart/`scripts/dev-server-edition.sh --phase b`), happy path** — `bash scripts/dev-server-edition.sh --phase b --scratch <rig>/prb-happy --keep`: built server edition + fake IdP, booted on port 18264/idp 19273, boot notices confirmed (`require_mcp_auth: false is overridden to true because server_edition.enabled is true`; `public_url resolved`), headless login as alice (`/auth/login` → 302 to the IdP with `code_challenge_method=S256` and `nonce=`; form POST; callback → 302 → `/my/tokens`; exactly one `mcpproxy_session` cookie), `GET /api/v1/auth/me` → `{"email":"alice@example.com","groups":["eng"],...}`, open-redirect check (`redirect_uri=https://evil.example/` → 302 → `/ui/`, US2.7) — all `ok`, script exited 0 at "phase b complete".
+
+**Discrepancy (rule 9, code wins)**: the task text asked for "§0–§4 + §6", but §6 (mint token, call `/mcp`) is gated behind `--phase d`, which runs §5 first (`/servers` entitlement filtering, `/auth/provider`, `/user/servers`) — §5 is PR-C work (entitlement predicate, group grants) not yet on this branch. `--phase d` against the current tree fails exactly there: `FAIL 5 /servers as alice must list exactly [a] (entitlement-filtered)` (server returns `{"servers":null}` — no entitlement filtering implemented yet, as expected for a PR-B-only tree). So §6 was verified directly with curl against a manually-restarted instance from the same rig binaries, skipping only the §5 entitlement assertions:
+- JWT/cookie on `/mcp` → 401 (`{"error":"Unauthorized","message":"Authentication required. Provide a valid session cookie or Bearer token."}`), no-credential `/mcp` → 401 (FR-029, `require_mcp_auth:false` overridden), a minted user JWT (`POST /api/v1/auth/token`) on `/mcp` → also 401 (FR-003: only agent tokens/API keys work on `/mcp`, never session credentials).
+- `POST /api/v1/user/tokens` as alice → `201` with `"token":"mcp_agt_..."` (note: the response field is `token`, not `raw_token` as quickstart §6 names it — quickstart's field name is stale from an earlier response shape; the code wins).
+- `initialize` with `Authorization: Bearer <token>` → **200**, `Mcp-Session-Id` header returned; `tools/list` on that session → **200** with the full built-in tool surface (`retrieve_tools`, `call_tool_read/write/destructive`, `code_execution`, `upstream_servers`, `quarantine_security`, etc.) — confirms the T062 requirement ("initialize + tools/list → 200").
+
+**Tamper matrix** (`--idp-args`, each its own `--phase b` run): `-token-error bad-signature|wrong-iss|wrong-aud|no-nonce` → each `ok 4c tamper case refused with 403 and no session`; `-token-endpoint-redirect` → `ok 4c tamper case refused with 503 and no session` (unavailability class, FR-024); `-discovery-http-token-endpoint` → the script's own `4a` assertion (expects a redirect) doesn't fit this knob, since discovery is resolved synchronously inside `/auth/login` itself (before any redirect is issued) when the discovered `token_endpoint` isn't `https`: `/auth/login` answered `503` directly, and `main.log` shows the typed reason `ERROR auth/oauth_handler.go:691 login unavailable {"reason": "discovery_failed", "check": "discovery token_endpoint is not an absolute https URL"}` — a generic refusal (503, no IdP detail leaked) plus a typed reason in the log, matching what the task asked for even though the script's own `--phase b` harness (built for the callback-stage knobs) reports it as a script-assertion mismatch rather than a `die`. All four fixed-403 cases and the two 503 cases confirm `ErrorMode` fails closed with no session cookie issued in every case.
+
+**Cookie Secure matrix behind a simulated proxy** — two fresh instances, identical except `trusted_proxies`: one `["127.0.0.1/32"]` (trusted), one `[]` (untrusted), both `session_cookie_secure: "auto"`, `public_url` http. Full login flow against each, `X-Forwarded-Proto` set only on the final callback request:
+  - trusted proxy + `X-Forwarded-Proto: https` → `Set-Cookie: mcpproxy_session=...; HttpOnly; **Secure**; SameSite=Lax`.
+  - trusted proxy, no `X-Forwarded-Proto` header (plain http) → `Set-Cookie: ...; HttpOnly; SameSite=Lax` (no `Secure`).
+  - untrusted proxy (`trusted_proxies: []`) + `X-Forwarded-Proto: https` from the same loopback address → header is **ignored**, no `Secure` — confirms FR-027's fail-closed behavior: an untrusted peer cannot spoof `https` to force (or, the inverse risk, avoid) the `Secure` attribute.
+
+**T063 telemetry payload** — `GET /api/v1/telemetry/payload -H "X-API-Key: <key>"` on the server-edition instance (secure-trusted rig): `feature_flags.server_edition_enabled=true`, `feature_flags.idp_provider="oidc"`, `member_count_bucket="1-10"` present. Same call on a personal binary (`go build -o mcpproxy ./cmd/mcpproxy`, no `server_edition` config): `edition="personal"`, `feature_flags.server_edition_enabled=false`, `feature_flags.idp_provider="none"`, `member_count_bucket="0"`.
+  - **Discrepancy (rule 9)**: the task/spec FR-038 wording says `user_count_bucket` and "false/absent" for the personal payload; the shipped wire keys are `member_count_bucket` (deliberate rename — documented and defended in cross-review round 6, rejected as a finding: `user`-prefixed keys would trip the PII scanner's home-dir-basename substring match against every `USER user`-topology server container) and, for personal, explicit sentinel values (`idp_provider="none"`, `member_count_bucket="0"`) rather than field absence — `TestPayloadV13_PassesScanWithCommonUsernameBlocked` pins the rename, and the personal defaults are the existing `FeatureFlagSnapshot` zero-value behavior, not a PR-B regression.
+
 ### Automated checks
 
+Run 2026-09-16 on branch `107-b-oidc-front-door` (HEAD `45d302a47` = the six PR-B commits on top of PR-A's `c741f82f2`; `origin/main` at `8acb506de`, merge-base `b1777e865`) from the worktree root, in plan.md §Gates order plus the rows the PR-B brief adds (`go test ./cmd/...`, `./tests/oauthserver/...`, `npm run build`, the OAuth E2E job's commands). Go `go1.26.0 darwin/arm64`. Logs in the session scratchpad `gates-prb/`. Baseline for "pre-existing": `gh pr checks 1287` (PR-A) — every job `pass` except the 4-second `CodeQL` row (the known config-URL false positive, memory `project_codeql_req`). The machine was shared with three other sessions running `go test -race -count=3 -shuffle=on` sweeps and a Docker build throughout (load average 6.5–7.2), which matters for row 13.
+
+| # | Command | Outcome |
+|---|---------|---------|
+| 1 | `go build -o /dev/null ./cmd/mcpproxy` | pass (exit 0) |
+| 2 | `go build -tags server -o ./mcpproxy-server ./cmd/mcpproxy` → `MCPProxy v0.1.0 (server)` | pass (exit 0) |
+| 3 | `go vet ./...` and `go vet -tags server ./...` | pass (exit 0 both) |
+| 4 | `go test -race -tags server -timeout 20m ./internal/serveredition/... ./internal/config/... ./internal/oauth/... ./internal/storage/...` | pass — 9 packages `ok` (serveredition 19.5s, api 28.5s, auth 33.4s, broker, multiuser, users, config, oauth, storage), 0 FAIL |
+| 5 | `go test -race -tags server -timeout 25m -skip 'E2E\|Binary\|MCPProtocol\|TestInfoEndpoint\|TestGracefulShutdownNoPanic\|TestSocketInfoEndpoint' ./internal/server/... ./internal/httpapi/...` (the `server-edition` CI job) | pass — `internal/server` 410.8s, `internal/server/tokens`, `internal/httpapi` all `ok` |
+| 6 | personal race sweep, split as the brief asks: `go test -race -timeout 25m -skip '<CI regex>' $(go list ./internal/... \| grep -v '/internal/server$')` then `… ./internal/server` | pass — 64 packages `ok` + `internal/server` `ok` 466.5s, 0 FAIL (incl. `internal/upstream/core`, `internal/transport`, `internal/runtime`, `internal/telemetry`) |
+| 7 | `go test -race -timeout 10m ./cmd/mcpproxy` and `… -tags server …` | pass (`ok` 31.3s / 18.6s) |
+| 8 | `go test -count=1 -v ./internal/server/ -run 'TestToolsListSnapshot_MatchesMergeBaseGoldens\|TestToolsListSnapshot_DeltaIsEnumerated\|TestMenuSurface_ExactDeltaFromPreFeature\|TestDirectFullMode_ByteStableAgainstPreFeatureE2E'` (frozen goldens, unregenerated; `internal/server/testdata` untouched) | pass — all 4 `--- PASS` |
+| 9 | `go test ./cmd/release-gate/` | pass (`ok`, 0.8s) |
+| 10 | `go test ./cmd/...` | pass — 9 packages `ok` |
+| 11 | `go test ./tests/oauthserver/...` (fake OIDC IdP, T032–T034) | pass — `tests/oauthserver` 3.4s, `tests/oauthserver/cmd/server` `ok` |
+| 12 | golangci-lint v2.9.0 `run --config .github/.golangci.yml --timeout=10m ./...` (bare) | pass — `0 issues` |
+| 12b | golangci-lint v2.9.0 `… --build-tags server --timeout=10m ./...` | **red → fixed → pass.** First run: 1 issue, `internal/serveredition/auth/oidc_jwks_test.go:192:20: QF1008: could remove embedded field "PublicKey" from selector (staticcheck)` — introduced by PR-B (T037's malformed-EC fixture). Fix: `p256.PublicKey.Y` → `p256.Y` (`ecdsa.PrivateKey` embeds `PublicKey`). Re-run: `0 issues`. |
+| 13 | `scripts/test-api-e2e.sh` — isolated: `pgrep -f test-api-e2e.sh` empty, no foreign scratch core in `pgrep -fl 'mcpproxy serve --config\|launcher-server'`; scratch copy with only line 80 (`pkill -f "mcpproxy.*serve"`) deleted (`diff` = `80d79`); `LISTEN_PORT=18523` and launcher port 39933 verified free with `lsof`; personal `./mcpproxy` rebuilt from HEAD (`v0.1.0 (personal)`); run only after rows 4–7 had finished | **run 1: 63/65** — the two failures are the paired "Launcher lifecycle: POST /enable respawns child" (`launcher-test never reconnected after enable`, 30×2s) and its dependent "per-server log captures child output". Core log: disable and enable both landed at 19:30:16; the disable's async `go func { RemoveServer }` in `lifecycle.go:1312-1315` logged `Server is disabled, removing from active connections` a second time at 19:30:17, *after* the enable had been recorded, so the re-enabled server was torn down again. This is the known launcher-timing flake family (memory `project_ci_flaky_unit_tests`, 2026-08-09 addition: exactly these two rows, rerun-clearable on loaded runners) and pre-existing: PR-B touches **no** file in `internal/runtime/lifecycle.go` or `internal/upstream/` (`git diff --name-only origin/107-a-freeze-cut...HEAD -- internal/runtime/lifecycle.go internal/upstream/` = 0), and the machine was at load 7 with three foreign `-race -count=3` sweeps. **Run 2 (same scratch copy, same port, same load): `Tests run: 65, passed: 65, failed: 0`.** After each run `git checkout -- test/e2e-config.json` restored the tracked config; the live tray core (pid 60473, :8080) survived both. |
+| 14 | `make swagger-verify` (PR-B changes `oas/swagger.yaml` + `oas/docs.go` for `trusted_proxies`, T058) | pass — `OpenAPI artifacts are up to date` |
+| 15 | `go run ./cmd/generate-types && go test ./cmd/generate-types/ -run TestContractsInSync` | pass — `contracts.ts` regenerated byte-identical (tree clean), PASS |
+| 16 | `python3 scripts/gen-roadmap.py --check` | pass — `ROADMAP.md is up to date.` |
+| 17 | `cd frontend && npx vitest run` | pass — 123 files, 1284 tests (includes T059's `auth-provider-probe.spec.ts` and the extended `settings-server-edition-wording.spec.ts`) |
+| 17b | `cd frontend && npm run build` | pass — `✓ built in 785ms`, exit 0 (one pre-existing `INEFFECTIVE_DYNAMIC_IMPORT` warning on `src/stores/auth.ts`, present on main) |
+| 18 | `gofmt -l` over the 139 touched Go files still on disk (`git diff --name-only origin/main...HEAD -- '*.go'`) | pass — empty list |
+| 19 | `python3 scripts/check-settings-parity.py` (required CI job `native-tests.yml` `settings-parity`; it runs because PR-B changes `frontend/src/views/settings/fields.ts`) | **red → fixed → pass.** First run: `FAILED: setting(s) in the Web UI but NOT editable in the macOS tray: ['trusted_proxies']` — T058's Swift half was not done (the PR-B tree changed nothing under `native/`). Fix (research D12, plan checklist §8): `ConfigField.listLines` flag (mirrors `listKind: 'lines'`), the `trusted_proxies` row after `listen` in `SettingsCatalog.security` (same label/help as `fields.ts`, `.textarea`, `optional`, not restart-pinned), and `ConfigStore.linesBinding` + `linesText`/`parseLines` in `ConfigSettingsView.swift` so the tray round-trips the `[]string` (a plain string binding rendered the list as "" and would have saved a string the core cannot decode) — splitting on newlines and commas, trimming, dropping blanks, `[]` when a present list is cleared, "unset" when the key was absent. Re-run: `Settings parity OK: 61 setting(s) consistent across web + native.` |
+| 20 | `(cd native/macos/MCPProxy && swift test)` (required CI job `native-tests.yml` `swift-test`) | **1166/1167** — `Executed 1167 tests, with 1 failure`. The six new `SettingsTrustedProxiesFieldTests` all `passed` (row exists as a lines textarea; parse/render helpers; the binding reads the array and writes an array back into the PATCH partial; clearing a present list saves `[]`; blank on an absent key stays undirty). The one failure is `AppLifecycleTests.testTheSharedJournalNeverWritesToTheRealInstanceRootUnderTests`, the same environmental red herring as PR-A rows 20 (memory `project_swift_test_silent_miss`): it fails whenever the live tray has written `~/.mcpproxy/tray-lifecycle.jsonl` (present, 92 KB, mtime 19:05 today). Pre-existing, not PR-B. |
+| 21 | OAuth E2E — the `e2e-tests.yml` `OAuth E2E Tests` job's two commands: `go test -race -timeout 5m ./tests/oauthserver/...` and `OAUTH_INTEGRATION_TESTS=1 go test -race -timeout 5m ./tests/oauthserver/... -run TestIntegration -v` | pass — `ok` both; 8 `TestIntegration_*` `--- PASS` (WWWAuthenticateDiscovery, DiscoveryEndpoints, ErrorHandling ×3, SlowResponse, DeviceCodePolling, DCRFlow, JWKSFetch, ResourceIndicator). The Playwright `scripts/run-oauth-e2e.sh` (browser flow, not a CI job) was not run. |
+
+Tooling note: as in PR-A, `/opt/homebrew/bin/golangci-lint` (2.5.0, built with go1.25.1) refuses the `go 1.26.0` module; rows 12/12b ran the CI-pinned `GOFLAGS=-mod=mod go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.9.0 …` (module cache; `go.mod`/`go.sum` untouched).
+
+Gate fixes (commit `4b8baa3bb` `fix(spec-107): gate fixes for PR-B`): `internal/serveredition/auth/oidc_jwks_test.go` (row 12b), `native/macos/MCPProxy/MCPProxy/Settings/SettingsCatalog.swift`, `native/macos/MCPProxy/MCPProxy/Settings/ConfigSettingsView.swift`, new `native/macos/MCPProxy/MCPProxyTests/SettingsTrustedProxiesFieldTests.swift` (rows 19–20). No Go production file changed, so rows 1–11 and 13–18 were not re-run after the fixes; row 12b, 19 and 20 were.
+
+Not run: none of the plan.md §Gates rows was skipped. PR-C/PR-D-only gates (Playwright tenant spec, SC-009 benchmark) do not apply to PR-B.
+
+**T064 — full gate re-run post cross-review round 6.** Rounds 3–6 changed `internal/config/{loader.go,server_edition_config.go,serveredition_accessors*.go}`, `internal/serveredition/auth/{oauth_handler.go,oauth_providers.go,oidc_provider.go}`, `internal/telemetry/telemetry.go`, `tests/oauthserver/authorize.go`, and `scripts/dev-server-edition.sh` after the table above was recorded (at gate-fix commit `4b8baa3bb`), so the whole gate set was re-run from HEAD `5ad3a080d` rather than trusting the stale table. `wc -l internal/serveredition/auth/oidc_jwks.go` = **142** (budget 150). Logs: session scratchpad `gates-prb-r6/`.
+
+| # | Command | Outcome |
+|---|---------|---------|
+| 1 | `go build -o /dev/null ./cmd/mcpproxy` | pass |
+| 2 | `go build -tags server -o ./mcpproxy-server ./cmd/mcpproxy` | pass |
+| 3 | `go vet ./...` and `go vet -tags server ./...` | pass (both exit 0) |
+| 4 | `go test -race -tags server -timeout 20m ./internal/serveredition/... ./internal/config/... ./internal/oauth/... ./internal/storage/...` | pass — 9 packages `ok` |
+| 5 | `go test -race -tags server -timeout 20m -skip '<CI regex>' ./internal/server/... ./internal/httpapi/...` | pass — `internal/server` 348.1s, `internal/server/tokens`, `internal/httpapi` `ok` |
+| 6 | personal race sweep, split: 66 non-`internal/server` packages, then `./internal/server` alone, both with the CI `-skip` regex | pass — 66 packages `ok` + `internal/server` `ok` 296.4s |
+| 7 | `go test -race -timeout 10m ./cmd/mcpproxy` and `… -tags server …` | pass (both `ok`) |
+| 8 | frozen tool-surface goldens (4 tests, unregenerated) | pass — all 4 `--- PASS` |
+| 9 | `go test ./cmd/release-gate/` | pass |
+| 10 | `go test ./cmd/...` | pass — 9 packages `ok` |
+| 11 | `go test ./tests/oauthserver/...` | pass |
+| 12 | golangci-lint v2.9.0 (module-cache pinned, same tooling note as PR-A row: the local `/opt/homebrew` binary is v2.5.0/go1.25.1 and refuses the go1.26 module) `run --config .github/.golangci.yml --timeout=10m ./...` | pass — `0 issues` |
+| 12b | `… --build-tags server --timeout=10m ./...` | pass — `0 issues` (the round-6 `oidc_jwks_test.go` fix from the earlier gate run held) |
+| 13 | `scripts/test-api-e2e.sh` — isolated (`pgrep -f test-api-e2e.sh` and `pgrep -fl 'mcpproxy serve --config\|launcher-server'` both empty first), `LISTEN_PORT=18196` | pass — **65/65**, no flake this run |
+| 14 | `make swagger-verify` | pass — `OpenAPI artifacts are up to date` |
+| 15 | `go run ./cmd/generate-types && go test ./cmd/generate-types/ -run TestContractsInSync` | pass — `contracts.ts` unchanged, `git status` shows only `verification.md` touched |
+| 16 | `python3 scripts/gen-roadmap.py --check` | pass |
+| 17 | `cd frontend && npx vitest run` | pass — 123 files, 1284 tests |
+| 17b | `cd frontend && npm run build` | pass — `✓ built in 639ms` (same pre-existing `INEFFECTIVE_DYNAMIC_IMPORT` warning on `src/stores/auth.ts`) |
+| 18 | `gofmt -l` over the 145 touched Go files still on disk (`git diff --name-only origin/main -- '*.go'`, filtered to files that still exist — the removed latent-code files from PR-A's cut no longer resolve and were excluded, not silently skipped) | pass — empty list |
+| 19 | `python3 scripts/check-settings-parity.py` | pass — `Settings parity OK: 61 setting(s) consistent across web + native` |
+| 20 | `(cd native/macos/MCPProxy && swift test)` | **1166/1167** — the one failure is `AppLifecycleTests.testTheSharedJournalNeverWritesToTheRealInstanceRootUnderTests`, the same pre-existing environmental red herring as the earlier gate run and PR-A (live tray's `~/.mcpproxy/tray-lifecycle.jsonl` present) |
+| 21 | OAuth E2E job commands: `go test -race -timeout 5m ./tests/oauthserver/...` and `OAUTH_INTEGRATION_TESTS=1 go test -race -timeout 5m ./tests/oauthserver/... -run TestIntegration -v` | pass — both `ok`; 8 `TestIntegration_*` `--- PASS` |
+
+`git checkout -- test/e2e-config.json` restored the tracked config after row 13 (it was rewritten in place by the run, as expected). Every row 1–21 is green on the round-6 tree; nothing skipped.
+
+**CI red on push (`gh pr checks 1292`), fixed and re-pushed at `717e58097`**: `Unit Tests (windows-latest, 1.26)` and `Build Binaries (windows-latest, windows, amd64, …)` both failed. Root cause (`gh run view --log 105007897949`): `internal/httpapi.handleAddFromRegistry`'s success path dereferenced a nil `cfg` from a test double, chi's `Recoverer` turned that panic into a bare 500, and under Go 1.26 on windows/amd64 the recovered hardware fault corrupts the Go heap (`golang/go#81238`) — the test binary later died with `fatal error: found pointer to free object` (Build Binaries job) / `fatal error: unexpected signal during runtime execution` during a later GC in `internal/server` (Unit Tests job, 393s in). `git diff origin/main -- internal/httpapi/server.go` showed origin/main already carries the fix as commit `8acb506de` (`fix(ci): stop the Windows recovered-panic heap crash and the Pass-2 temp-dir race (#1288)`, merged same day) — this branch diverged before it landed and never rebased. Not a PR-B regression: `git diff --name-only origin/107-a-freeze-cut...717e58097~1 -- internal/httpapi/server.go` shows only PR-B's own additions (`refuseRemovedConfigKeys`, `MergeConfigPatch`), the `cfg == nil` guard was simply never present on this branch. Fix: cherry-picked #1288 verbatim — the nil-config guard + its pinning test (`TestAddFromRegistry_NilConfigIsAnError`) in `internal/httpapi/{server.go,registry_add_test.go}`, and the unrelated Pass-2 temp-dir teardown race fix that commit bundled in `internal/security/scanner/service_test.go` (`waitForPass2Saved`). Verified locally before push: both editions build, `go vet` clean, `gofmt -l` clean on the 3 files, `go test -race ./internal/httpapi/... ./internal/security/scanner/...` green (`TestMutatingServerRoutes_AdminAllowed/registry-add-server`, `TestAddFromRegistry_NilConfigIsAnError`, `TestServiceStartScanDeepOnRunsSourceResolutionAndPass2` all `--- PASS`). Pushed as `717e58097`.
+
+**CI re-run, all green** — `gh pr checks 1292` on HEAD `b4ab0f987` (after the docs commit on top of `717e58097`): every check `pass` (`Unit Tests` ubuntu/macos/windows/shuffle, all `Build`/`Build Binaries` platforms incl. both windows-latest jobs that were previously red, `Server Edition` ×2, `Lint` ×2, `swift-test`, `settings-parity`, `roadmap-up-to-date`, `Build Server Docker Image`, `Cloudflare Pages`, `Sandbox Integration`, `Retrieval`/`Security regression gate`, `Validate PR title`); the 3 automation-only jobs (`auto-pass-qa-gate`, `dependabot-auto-merge`, `spec-gardener-auto-approve`) `skipping` as expected. Fix-round count: 1/3 (well under the escalation cap).
+
 ### Cross-review
 
+**Round 1** (2026-09-16, reviewer: `opencode run --model github-copilot/gpt-5.6-sol`, four briefs — provider+verification / handler+pages+subject binding / front door+config / telemetry+rig+frontend, run sequentially under the single-flight lock): 14 findings, 12 genuine after verification against the live tree, 2 rejected.
+
+- **Fixed** (chunk 1, provider/verification — `internal/serveredition/auth/oidc_provider.go`):
+  - (P2) `verifyIDToken` used `jwt.WithIssuedAt()`, which validates `iat` only when present and never makes it mandatory (no `WithIssuedAtRequired` in jwt/v5); `iat` is a REQUIRED OIDC Core §2 ID-token claim. Fixed with an explicit presence check right after the validator runs.
+  - (P2) `audienceList` silently dropped any non-string entry from an `aud` array, so a malformed `aud: ["client-id", 7]` was scored as a single-valued audience and the `azp` requirement for multi-valued `aud` never triggered. Fixed: the function now returns `(auds, ok)` and a non-string entry refuses the token (`id_token aud contains a non-string entry`).
+  - (P2) `exchangeCode`'s non-200 branch embedded the token endpoint's raw, IdP-controlled `error` field verbatim into the propagated error (and from there the log), a log-injection / arbitrary-content vector. Fixed with `sanitizeOAuthErrorCode`, clamping to the closed RFC 6749 §5.2 vocabulary (`unknown` otherwise).
+  - (P3) `resolveGroups`'s userinfo branch decoded the body into `map[string]any` and treated a JSON `null` (or any non-object scalar) as "sub absent" → `userinfo_subject_mismatch`/403, not the FR-022-required `provider_error`/503 for an undecodable body. Fixed with an explicit `info == nil` check.
+  - **Rejected** — (P3) "a non-object JWKS key entry aborts the whole `parseJWKS` document instead of being skipped": tried the fix, then reverted it — it directly contradicts the pre-existing, deliberately-written `TestParseJWKS_MalformedDocumentRefused/key_entry_is_string` (`{"keys":["RSA"]}` → `require.Error`), a documented fail-closed design choice (a malformed JWKS document refuses the whole set rather than silently proceeding on fewer keys). The file's own "skipped" language in its header comment covers well-formed-but-unusable crypto shapes (unsupported `kty`, off-curve point, missing `kid`), not structurally malformed entries — verified by reading every case in that test table.
+
+- **Fixed** (chunk 2, handler/subject binding — `internal/serveredition/users/store.go`, `internal/serveredition/api/admin_handlers.go`, `internal/serveredition/users/store_test.go`):
+  - (P1) `disableUser`/`enableUser` used `GetUser` (a `View`) + mutate-in-Go + `UpdateUser` (a blind `Put`) — a classic lost-update window: a concurrent `UpdateUserLogin` (its own atomic `db.Update`, writing `Groups`/`Provider`/`ProviderSubjectID`/`LastLoginAt` and clearing `SubjectRebindArmedAt`) landing entirely between the admin's read and write was silently reverted by the admin's stale-snapshot overwrite — reopening a just-consumed FR-023 rebind window or discarding a legitimate concurrent rebind. Fixed with a new `UserStore.SetUserDisabled(id, disabled) (*User, armed bool, error)` that re-reads and writes the record inside ONE `db.Update`, exactly like `UpdateUserLogin`; both admin handlers now call it instead of the blind pattern. New regression test `TestSetUserDisabled_DoesNotLoseConcurrentLoginWrite` (20 barrier-synchronised rounds) — verified it fails against the pre-fix code (`git stash` the three touched files, rerun: fails every round with the login's `Groups` write reverted; restored and re-verified green) before being kept.
+  - **Rejected** — (P2) "`UpdateUserLogin` consumes the armed rebind and commits the new subject before JWT signing/session creation, so a signer/session-store failure returns 503 while still consuming the single-use window": verified against `TestSubjectRebind_FailedAttemptDoesNotConsumeTheWindow`, whose own comment and assertions define "failed attempt" (the FR-023 guarantee's scope) as a failure BEFORE the store is consulted — once the store commit succeeds the identity was genuinely verified and legitimately consumes the window; a downstream signer/session failure is unrelated infrastructure, and the user's retry succeeds immediately because the binding is already correct. Working as designed, not a defect.
+
+- **Fixed** (chunk 3, front door/config — `internal/runtime/restart_gated.go`, `internal/config/{serveredition_accessors.go,serveredition_accessors_stub.go,server_edition_config.go,env_serveredition.go,loader.go}`, `internal/serveredition/auth/oauth_handler.go`):
+  - (P1) `pinRestartGated` never pinned `Config.ServerEdition` at all, so the restart-pinned subset FR-039 part 2 defines (`enabled`, `oauth.*`, `public_url`, `session_cookie_secure`, `session_ttl`, `bearer_token_ttl`, `credential_encryption_key`) was adopted into the LIVE running config on every apply — hot, not gated — even though `DetectConfigChanges`/the API reported it as requiring a restart. Worst case: disabling `server_edition.enabled` restored anonymous `/mcp` access immediately (`config.EffectiveRequireMCPAuth` reads the live pointer) while the operator was told a restart was still pending. Fixed with `config.MergeServerEditionRestartGated(live, desired)` (server build: pins the FR-039 subset to `live`, keeps `AdminEmails` hot per #1169; personal build: pins the whole opaque carrier, matching `ServerEditionRestartProjection`), wired into `pinRestartGated`. New regression tests `TestPinRestartGatedCoversServerEdition` (3 sub-cases) and `TestPinRestartGatedKeepsServerEditionAdminEmailsHot` in a new `internal/runtime/restart_gated_serveredition_test.go` — verified the coverage test fails against the pre-fix code (same stash/restore method as chunk 2) before being kept.
+  - (P2) `ValidatePublicURL` checked `u.Host == ""` but not `u.Hostname() == ""`; `https://:443` parses with `Host=":443"` (non-empty) and an empty `Hostname()`, so it passed validation and produced a malformed callback/connect-flow base URL. Fixed by adding the `Hostname() == ""` check.
+  - (P2) `${env:OIDC_CLIENT_SECRET}` / `${env:...}` in `server_edition.oauth.client_secret` or `client_id` — the pattern every doc page for this block (`config-file.md`, `installation.md`, `server-edition-multiuser-auth.md`, `scripts/dev-server-edition.sh`) tells the operator to use — was never expanded: no caller in `internal/serveredition/setup.go` or anywhere else invoked the secret resolver on this field, so the literal placeholder string reached the token endpoint as the client secret and every documented SSO login configuration would fail. Fixed with `expandServerEditionSecrets` (new, in `server_edition_config.go`; no-op stub on the personal build), wired into both `Load` and `LoadFromFile` right after `expandDataDir`, before `Validate`.
+  - (P2) `validateOIDC` checked `EmailVerifiedPolicy` unconditionally, before the `Provider != "oidc"` early return, so a legacy (`google`/`github`/`microsoft`) config carrying a stray/mistyped `email_verified_policy` was rejected outright instead of being ignored as the struct's own doc comment promises ("the legacy providers ignore them") and as the code's actual behaviour already is (`EmailVerifiedPolicy` is read only by `oidcIdentity`, never `legacyIdentity`). Fixed by moving the check after the early return; `DisplayName`'s length check stays unconditional (FR-020/FR-030: the login-button label applies to every provider).
+  - (P3) `warnSchemeDisagreement` only warned in the https-configured/http-observed direction; an http `public_url` behind an ingress that terminates TLS and forwards a trusted `X-Forwarded-Proto: https` produced no warning at all, though FR-025 says "disagrees with it" without a direction. Fixed: now compares both schemes and warns (with a new, distinct message) in the reverse direction too, guarded so an unset `public_url` still never warns (existing `TestFrontDoor_PublicURLBehindHostRewritingIngress`/"no public_url" cases stay green).
+  - (P3) `applyServerEditionEnvOverrides` checked `os.Getenv(EnvPublicURL) == ""` without trimming, so a whitespace-only `MCPPROXY_PUBLIC_URL` overrode a valid file value with an unparsable string and failed startup validation, contradicting the function's own "blank leaves the file value alone" doc comment. Fixed with `strings.TrimSpace` before the blank check.
+
+- **Rejected** (chunk 4, telemetry — `internal/telemetry/telemetry.go:385`): "schema v13 serializes the field as `member_count_bucket`, not the FR-038-mandated `user_count_bucket`". Verified: deliberate, documented (telemetry.go:140-150) and test-pinned (`TestPayloadV13_PassesScanWithCommonUsernameBlocked`) rename — `ScanForPII` substring-matches the wire form including keys, and `USER user` is the container image's own topology (the server edition's), so a key containing "user" would have refused every heartbeat from such a deployment before it left the machine. A corrected spec-vs-code discrepancy (rule 9: the code wins), not a defect.
+
+Verification for every fix: `go build -tags server -o /dev/null ./cmd/mcpproxy` and `go build -o /dev/null ./cmd/mcpproxy` (both editions), `go vet -tags server ./...` and `go vet ./...` (clean), then `go test -race` on every touched package plus `./internal/runtime/...`, `./internal/httpapi/...`, `./internal/telemetry/...`, `./tests/oauthserver/...` and the CI `-skip` regex on `./internal/server/...` (376.9s, green) — all green after fixes; `golangci-lint` itself could not run (`can't load config: the Go language version (go1.25) used to build golangci-lint is lower than the targeted Go version (1.26.0)`, memory `feedback_ci_gol` — known environment canary, `go vet` substitutes). `gofmt -l` clean on every touched file.
+
+Round 1 commit: see the `fix(spec-107): cross-review round 1 for PR-B` commit on this branch. Rounds used so far: 1/10.
+
+**Round 2** (2026-09-16, reviewer: `opencode run --model github-copilot/gpt-5.6-sol`, four briefs — provider+verification / handler+pages+subject binding / front door+config / telemetry+rig+frontend, run sequentially under the single-flight lock): 4 findings, 2 genuine after verification against the live tree, 2 rejected.
+
+- **Fixed** (chunk 1, provider — `internal/serveredition/auth/oidc_provider.go`):
+  - (P2) `authorizationURL` built the authorization request URL with `doc.AuthorizationEndpoint + "?" + params.Encode()` — a plain string append that assumes the discovered `authorization_endpoint` carries no query component of its own. An endpoint such as `https://idp.example/authorize?tenant=acme` (a real shape for a multi-tenant IdP) produced `?tenant=acme?client_id=...`: a single malformed query string the IdP cannot parse into separate `tenant`, `client_id`, `state`, `nonce` and PKCE parameters, so login fails for an otherwise-valid discovery document. Fixed by parsing the endpoint with `url.Parse`, merging the authorization parameters into `u.Query()`, and re-serializing with `u.String()` — the endpoint's own query (if any) survives alongside the added parameters.
+
+- **Fixed** (chunk 3, front door/config — `internal/config/server_edition_config.go`, new `internal/config/server_edition_secrets_expand_test.go`):
+  - (P2) `expandServerEditionSecrets` (the round-1 fix for `${env:...}` expansion in `oauth.client_id`/`client_secret`) kept the **original unresolved placeholder text** on a resolution failure ("using original value", explicitly modeled on `expandDataDir`'s pattern) — but `expandDataDir`'s callers separately check "does the value still contain `${`" before using it, and `client_id`/`client_secret` have no such check: `Validate()` only tests non-empty, and `${env:MISSING}` is itself non-empty. So a missing environment variable — the exact Kubernetes Secret scenario documented across four doc pages — passed boot validation and the literal placeholder string `${env:OIDC_CLIENT_SECRET}` was later sent to the IdP as the client secret, directly contradicting the function's own doc comment ("a missing env var is refused by 'client_secret is required'"). Fixed by clearing the field to `""` on a resolution failure instead of keeping the placeholder, so the existing required-field check in `Validate()` now actually fires. New regression test `TestExpandServerEditionSecrets_MissingEnvVarIsRefusedAtValidate` (`internal/config/server_edition_secrets_expand_test.go`) — verified it fails against the pre-fix code (`git stash` the touched file, rerun: `LoadFromFile` returns no error and the placeholder reaches the config; restored and re-verified green).
+
+- **Rejected** (chunk 2, handler — `internal/serveredition/api/admin_handlers.go` dashboard role label): "the admin dashboard's `getDashboard` derives each recent user's role from the boot-time `h.adminEmails` slice with a case-sensitive `==` instead of the live config's `IsAdminEmail` (EqualFold), so a hot-reloaded `admin_emails` change or a differently-cased address shows a stale/wrong role on the dashboard." Verified genuine as a description of the code, but out of scope for PR-B: `git diff 107-a-freeze-cut...HEAD -- internal/serveredition/api/admin_handlers.go` shows `getDashboard` is untouched by this PR (only `disableUser`/`enableUser`/`listUsers`/`RegisterRoutesWithPrefix` changed), and tasks.md T044 explicitly scopes "role derived live" to the **login handler only**, naming this exact class of remaining staleness as "#1169's remaining horizon" (T066: "Open PR-B (`Related #1169` for the live-role reuse)"). Pre-existing behaviour, not a PR-B regression, already tracked.
+- **Rejected** (chunk 4, frontend — `frontend/src/services/auth-api.ts`, `frontend/src/stores/auth.ts`): "`getProvider()` collapses every non-404 failure (malformed response, transient network error) to `null`, and `checkAuth()` treats `null` as definitive personal edition with no retry, so a transient failure stalls the SSO login surface for the rest of the SPA session." Verified against `git show 107-a-freeze-cut:frontend/src/stores/auth.ts`: the pre-PR-B code had the identical fail-to-personal-edition-with-no-retry shape (any `api.getStatus()` failure left `isTeamsEdition` at its initial `false`, no retry). PR-B's change here fixes a strictly worse pre-existing bug (critic G1: every tenant, not just on transient failures, read as personal edition because `getStatus()` required an API key no tenant holds) and does not introduce a new failure mode — the documented "degrade to personal surface rather than hang on a spinner" behaviour is a pre-existing design tradeoff, not a PR-B regression, and no FR requires retry logic.
+
+Verification for every fix: `go build -tags server -o /dev/null ./cmd/mcpproxy` and `go build -o /dev/null ./cmd/mcpproxy` (both editions), `go vet -tags server ./...` and `go vet ./...` (clean), `go test -race -tags server ./internal/config/... ./internal/serveredition/auth/... ./internal/runtime/... ./internal/telemetry/... ./tests/oauthserver/... ./internal/httpapi/...` — all green (`internal/server` was being exercised concurrently by another session against this worktree at review time per the shared-worktree convention; round 2's two fixes touch neither `internal/server` nor anything it imports, so it was not re-run here). `gofmt -l` clean on every touched file.
+
+Round 2 commit: see the `fix(spec-107): cross-review round 2 for PR-B` commit on this branch. Rounds used so far: 2/10.
+
+**Round 3** (2026-09-16, reviewer: `opencode run --model github-copilot/gpt-5.6-sol`, four briefs — provider+verification / handler+pages+subject binding / front door+config / telemetry+rig+frontend, run sequentially under the single-flight lock, one retry after a concurrent session held the lock): 6 findings, 4 genuine after verification against the live tree, 2 rejected.
+
+- **Fixed** (chunk 1, provider/verification — `internal/serveredition/auth/oidc_provider.go`, `internal/serveredition/auth/oidc_verify_test.go`):
+  - (P2) `resolveGroups` treated an empty `access_token` from the token endpoint exactly like an absent `userinfo_endpoint` — silent fail-closed `groups_claim_missing`, login succeeds with `[]` — when the ID token lacked the groups claim. RFC 6749 §5.1 requires `access_token` in every token response, but nothing in `exchangeCode` enforces it, so a hostile or misconfigured IdP omitting it would silently degrade a login instead of refusing it: FR-008/FR-022 require a userinfo fetch that cannot happen to be `provider_error`, never "claim absent". Fixed: an empty `accessToken` with a `userinfo_endpoint` present is now `provider_error` (never attempted, never silently skipped). New regression test `TestOIDCVerify_ResolveGroups_NoAccessTokenIsProviderError` (direct unit test on the provider, not through the fake IdP — there is no rig knob for a token response missing `access_token`) — verified it fails against the pre-fix code before being kept.
+
+- **Fixed** (chunk 2, subject binding — `internal/serveredition/users/store.go`, `internal/serveredition/auth/oauth_handler_subject_test.go`):
+  - (P2) `UpdateUserLogin` only set `out.Rebound` (and therefore the `provider_rebound` audit flag) when the presented `(provider, sub)` actually differed from the stored one; a **same**-subject login while the rebind window was armed still cleared `SubjectRebindArmedAt` and set `RebindConsumed`, but `RebindConsumed` is read nowhere in production code and no audit line carries it — so that class of window consumption left no trace at all. FR-023 says "the first successful login" while armed "carries `provider_rebound` in the line's flags", unconditionally. Fixed: `armed` now always sets `out.Rebound = true` alongside `out.RebindConsumed = true`, regardless of which subject-rule case matched. New regression test `TestUpdateUserLogin_Outcomes/same_subject_with_the_window_armed_still_consumes_and_flags_it` — verified it fails against the pre-fix code before being kept.
+  - (P3) The bearer-token-bearing session write in `HandleCallback` is a second, separate `store.CreateSession` after `sessionCreator.CreateSession` (called through the `SessionManager`) already durably wrote a bearer-less row; on the second write's failure the handler correctly answered 503, but the bearer-less row was never cleaned up and would sit unusable until its TTL. No test exercised this second-write failure path at all. Fixed with a new `sessionPersist`/`sessionCleanup` fault-injection seam (matching the existing `loginStore`/`sessionCreator`/`bearerSigner` pattern, T044) that best-effort-deletes the orphan row when the second write fails. New regression test `TestHandleCallback_Unavailable_InternalErrorRenders503/failing_sessionPersist` — asserts the row is gone after the injected failure.
+  - **Rejected** — (P2) "in personal builds, unauthenticated `GET /api/v1/auth/provider` returns 401 (from `apiKeyAuthMiddleware`, which chi runs before the sub-mux's own 404) instead of the FR-030-specified 404": genuine as a description of the code, but not a new defect — `internal/httpapi/auth_provider_probe_personal_test.go` already documents this exact behaviour under a `DISCREPANCY with FR-030 / T053` heading with the same root cause (middleware-before-404 chi ordering) and explicitly "pins the behaviour of the code as it stands" rather than asserting the spec's literal 404. Already known and reported per rule 9 (code wins; the discrepancy is on record with file:line), not something round 3 introduced or missed.
+
+- **Fixed** (chunk 3, front door — `internal/server/server.go`, `internal/server/mcp_auth_forced_test.go`):
+  - (P2) The connect-service wiring (`startCustomHTTPServer`) threaded the **raw** `cfg.RequireMCPAuth` / `c.RequireMCPAuth` field into `connect.NewService(...).WithRequireMCPAuth(...)` and its live `WithConfigProvider` closure, instead of the build-tagged `config.EffectiveRequireMCPAuth` accessor FR-029 requires and that the `/mcp` middleware itself already uses (`server.go:378,475`). `connect.Service` decides whether to embed a credential in a generated client config from exactly that value (doc comment at `internal/connect/connect.go:105-111`): with `server_edition.enabled: true` and `require_mcp_auth: false` (FR-029's own "not a validation error" case, and the common configuration since forced auth makes the raw value irrelevant to `/mcp` itself), connect wrote credential-less client configs while `/mcp` genuinely required one — every client Connect generated got a 401 on its first real call. Fixed both call sites. New regression test `TestConnectServiceWiring_UsesEffectiveRequireMCPAuth` — a source guard (pins the absence of the two raw-field patterns and the presence of the accessor calls) rather than a behavioural one: reproducing the actual 401 needs a listening HTTP server via `startCustomHTTPServer`, which none of this file's existing tests boot (they drive `srv.mcpAuthMiddleware` directly against `NewServer` alone) — out of proportion to build for a P2 wiring fix already covered end-to-end by `TestEffectiveRequireMCPAuth_ServerBuild`'s truth table on the accessor itself.
+  - **Rejected** — (P2) "`setup.go:156`'s `PublicURLHTTPS: cfg.PublicURLIsHTTPS() || tlsEnabled` lets an in-process TLS listener force a `Secure` cookie even when `public_url` is explicitly `http://…`, contradicting FR-025's 'public_url is the sole source of the scheme'": verified against the spec text directly — FR-025's "sole source" sentence scopes the redirect_uri and connect-flow base URL, not the cookie decision; FR-026 defines `auto` Secure as true when the effective scheme is https via **any** of three explicitly OR'd sources — "`public_url`, an in-process TLS listener, or a trusted `X-Forwarded-Proto: https`" — the exact three conditions the code checks. The described scenario (declared-http `public_url` behind in-process TLS) is an intentionally contradictory operator configuration, not a code defect, and is exactly what `warnSchemeDisagreement` (round 1 fix) already surfaces as an operator-readable warning without blocking login.
+
+- **Fixed** (chunk 4, telemetry/rig/release notice — `.github/RELEASE_NOTICE.md`, `scripts/dev-server-edition.sh`):
+  - (P2) `.github/RELEASE_NOTICE.md`'s new OIDC section (added by PR-B) said a 3xx from the token, JWKS or userinfo endpoint "refuses the login before the client secret or the code is sent anywhere" — factually wrong: `exchangeCode` sends the client secret and code to the configured token endpoint (and `resolveGroups` a bearer token to the configured userinfo endpoint) in the same request whose response is then checked for a 3xx; only *following* that redirect to another origin is what never happens. Fixed the wording to describe what the client channel actually protects (the credential reaches your configured endpoint as normal; a redirect answer is refused rather than followed, so it cannot be forwarded to another host).
+  - (P2) `scripts/dev-server-edition.sh`'s tamper branch (§4c) asserted a blanket HTTP 403 for every `--idp-args` combination, but FR-024 defines 503 ("Sign-in is temporarily unavailable") as a **distinct** class for `discovery_failed`/`provider_error` — exactly what `-discovery-http-token-endpoint`, `-token-endpoint-redirect` and `-userinfo-error redirect|non-json|unavailable` inject. Every such rig invocation failed with a wrong-status `die`, independent of whether the production code was correct. Fixed: the tamper branch now classifies the expected status from which flags are present in `--idp-args` (503 for the unavailability-class flags, 403 otherwise) and the `--idp-args` usage comment documents the split. Verified live: `--idp-args "-userinfo-error unavailable"` now passes with `4c tamper case refused with 503`; `--idp-args "-token-error bad-signature"` (a 403-class flag) still passes with `403`; a plain `--phase b` run (no tamper) is unaffected.
+  - (P3) The same script read the fake IdP's `Confidential ID`/`Confidential Secret` lines from `idp.log` with a single `sed` right after `wait_http` confirmed the discovery endpoint was reachable — but the fake IdP's HTTP listener starts serving (via `oauthserver.StartOnPort`) before its startup banner finishes printing to stdout, so `wait_http` can return before the credential lines exist, and the extraction would then non-deterministically read empty values. Fixed with a bounded 20s poll loop matching `wait_http`'s own pattern, `bash -n`/`shellcheck` clean.
+
+Verification for every fix: `go build -tags server -o /dev/null ./...` and `go build -o /dev/null ./cmd/mcpproxy` (both editions), `go test -tags server ./internal/serveredition/... ./internal/telemetry/... ./tests/oauthserver/...` and `go test -race -tags server -skip "E2E|Binary|MCPProtocol|TestInfoEndpoint|TestGracefulShutdownNoPanic|TestSocketInfoEndpoint" ./internal/server/... ./internal/serveredition/...` — all green (`internal/server` 337.6s under `-race`). `bash -n` and `shellcheck` clean on `scripts/dev-server-edition.sh`, exercised live for both the 503-class and 403-class tamper paths plus a plain `--phase b` run. `gofmt -l` clean on every touched Go file.
+
+Round 3 commit: see the `fix(spec-107): cross-review round 3 for PR-B` commit on this branch. Rounds used so far: 3/10.
+
+**Round 4** (2026-09-16, reviewer: `opencode run --model github-copilot/gpt-5.6-sol`, four briefs — provider+verification / handler+pages+subject binding / front door+config / telemetry+rig+frontend, run sequentially under the single-flight lock, one wait for a concurrent session (a Spec 105 PR-D review) holding the lock before chunk 3): 4 findings, 1 genuine after verification against the live tree, 3 rejected.
+
+- **Fixed** (chunk 4, telemetry — `internal/telemetry/telemetry.go`):
+  - (P2) `SetUserCounter` wrote `s.userCounter` with no synchronization while `BuildPayload` read and invoked it. The write and the read run on different goroutines with no ordering guarantee: `StartBackgroundInitialization` launches the heartbeat loop on its own goroutine (`go r.telemetryService.Start(r.appCtx)`) while `SetUserCounter` is called later, from a different call chain (`server.startCustomHTTPServer` → `serveredition_wire.go`) — a genuine data race under the Go memory model (not merely theoretical), the same class the file's own `s.mu` already documents and protects for `resolvedEnabled`/`config`/`endpoint` and the anonymous-id/funnel fields. Fixed by guarding both the setter and a new `userCounterFunc()` accessor with the existing `s.mu`, matching the file's established convention for this exact class of field; `BuildPayload` now reads the counter through the accessor instead of the bare field. `go test -race -tags server ./internal/telemetry/...` green.
+  - **Rejected** — (P2) "`.github/RELEASE_NOTICE.md`'s FR-042 notice is incomplete: it does not name the server-edition audit-to-stdout default, the session-cookie-only restriction on `POST /auth/token`/`POST /user/tokens`/token regeneration, the 365-day `expires_in` cap, or the sign-in-again window": genuine as a description of the file's current content, but out of scope for PR-B — `tasks.md` T059 explicitly scopes PR-B's own release-notice bullets to "forced MCP auth under the server edition, `trusted_proxies` now gating forwarded headers, generic OIDC, `email_verified_policy` default" (all present), while the audit-to-stdout default is T114 (PR-D) and the session-cookie-only restriction / 365-day cap / sign-in-again window are T092 (PR-C) — each PR appends its own bullets to the same file as it lands, and PR-C/PR-D have not merged yet.
+- **Rejected** (chunk 1, provider — `internal/serveredition/auth/oidc_provider.go:243`): "discovery metadata omitting or nulling `id_token_signing_alg_values_supported` is accepted by defaulting to `[\"RS256\"]` instead of refusing as `discovery_failed`": RS256 is the OIDC Discovery "mandatory to implement" signing algorithm — every compliant OP supports it even when a non-compliant one omits the advertisement — and the default does not widen what is actually accepted: `doc.allowedAlgs` is still built by intersecting the (possibly defaulted) advertised list against the fixed, hardcoded `oidcAllowedAlgs` safe set, so the fallback can only ever additionally-allow RS256, never `none`/HS*/an unvetted algorithm. A deliberate, documented (`// mandatory-to-implement (OIDC Discovery §3)`) compatibility choice, not a security regression.
+- **Rejected** (chunk 3, front door/config — `internal/serveredition/setup.go:156`): the identical `PublicURLHTTPS: cfg.PublicURLIsHTTPS() || tlsEnabled` finding already verified and rejected in round 3 (see above) — re-raised because each opencode invocation reviews the diff fresh with no memory of prior verdicts. Same reasoning stands: FR-026 explicitly OR's three sources (public_url, in-process TLS, trusted `X-Forwarded-Proto: https`) for the Secure decision; FR-025's "sole source" sentence scopes the redirect_uri and connect-flow base URL, not the cookie.
+- Chunk 2 (handler/subject binding): **VERDICT: CLEAN**, no findings.
+
+Verification for the fix: `go build -tags server -o /dev/null ./cmd/mcpproxy` and `go build -o /dev/null ./cmd/mcpproxy` (both editions), `gofmt -l internal/telemetry/telemetry.go` (clean), `go vet -tags server ./internal/telemetry/...` (clean), `go test -race -tags server ./internal/telemetry/...` and `go test -race -tags server ./internal/serveredition/... ./tests/oauthserver/...` — all green. Only `internal/telemetry/telemetry.go` changed this round, so the heavier `./internal/server/...` race sweep (unaffected, no import of `internal/telemetry` in this diff's call path beyond the already-green package) was not re-run.
+
+Round 4 commit: see the `fix(spec-107): cross-review round 4 for PR-B` commit on this branch. Rounds used so far: 4/10.
+
+**Round 5** (2026-09-17, reviewer: `opencode run --model github-copilot/gpt-5.6-sol`, four briefs — provider+verification / handler+pages+subject binding / front door+config / telemetry+rig+frontend, run sequentially under the single-flight lock): 4 findings, 3 genuine after verification against the live tree, 1 rejected.
+
+- **Fixed** (chunk 1, provider — `internal/serveredition/auth/oauth_providers.go`):
+  - (P2) `newGenericOIDCProvider` added the required `openid` scope only when `Scopes` was empty; an explicit `scopes: [...]` list missing `openid` reached the authorization request unchanged. Reachable in production because `internal/serveredition/setup.go`'s `serverEditionConfig` provider (read by `NewOAuthHandler` at construction) prefers the LIVE, non-`ApplyDefaults()`'d `config.ServerEditionConfig` from `deps.ConfigProvider()` over the defaulted clone — the openid-injection `ApplyDefaults()` already does for an explicit list never runs on the block the handler actually resolves the provider from. Fixed: `newGenericOIDCProvider` now injects `openid` itself when an explicit scope list omits it (`containsFoldOIDC`, mirroring `config.containsFold`), so it no longer assumes its input already passed through `ApplyDefaults()`. Red test first (`TestNewGenericOIDCProvider_ForcesOpenIDScope` — failed before the fix, `[]string{"profile","email"}` did not contain `"openid"`).
+- **Fixed** (chunk 3, front door/config — `internal/serveredition/setup.go`):
+  - (P2) The credential-store master key was resolved as `broker.ResolveMasterKey(cfg.CredentialEncryptionKey)`, but `cfg.CredentialEncryptionKey` already went through `ServerEditionConfig.ApplyDefaults()` (explicit config value wins, env `MCPPROXY_CRED_KEY` is the fallback only when the config value is empty — matching `docs/configuration/config-file.md`'s "An explicit value wins over the environment"). `broker.ResolveMasterKey` has the opposite precedence by its own separate, deliberate, tested design (`TestResolveMasterKey`: "env should override config") — applying it a second time on the already-resolved value silently discarded an explicit `server_edition.credential_encryption_key` whenever `MCPPROXY_CRED_KEY` was also set, contradicting the documented precedence for this specific key and risking previously-encrypted credentials becoming unreadable after a restart with both set. Fixed with a new `credentialMasterKey(cfg)` helper in `setup.go` that returns `cfg.CredentialEncryptionKey` directly (no `broker.ResolveMasterKey` call), leaving `broker.ResolveMasterKey`'s own contract and test untouched for its own purpose. Red test first (`TestCredentialMasterKey_ExplicitConfigWinsOverEnv` — compile-red, `credentialMasterKey` undefined, then behaviour-red before the fix).
+  - (P3) `docs/configuration/config-file.md`'s Server Edition intro said the edition is distributed as "the Docker image / `.deb`", contradicting FR-036 ("no server `.deb`/tar.gz") and the already-corrected `CLAUDE.md` editions row ("Docker image (`ghcr.io`) only — no .deb / tar.gz"). Fixed the sentence to match.
+- **Fixed** (chunk 4, telemetry/rig — `scripts/dev-server-edition.sh`):
+  - (P3) `--idp-args` treated ANY non-empty value as a login-refusal tamper case (`TAMPER="1"`, expects 403 or a listed 503), but `-groups-error absent|non-array|overage` (FR-008 fail-closed fixtures) is a SUCCESS case — the login completes and groups land as `[]`; the script would have `die`d expecting a refusal. Separately, `-token-error invalid_client|invalid_grant|invalid_scope|server_error` are HTTP-level token-endpoint failures (`ExchangeCode` returns an error on a non-200 response, mapped to `LoginProviderError`/503 in `oauth_handler.go`), not ID-token content defects, but were missing from the script's 503 bucket and so defaulted to the wrong "403" expectation. Fixed: `-groups-error` flags now set a separate `GROUPS_TAMPER` flag that asserts the successful-login path with `groups==[]` instead of the tamper-refusal path; the four HTTP-level `-token-error` values were added to the existing 503 case list alongside the discovery/userinfo-transport cases. `bash -n` and `shellcheck` clean.
+- **Rejected** (chunk 2, handler/subject binding — `internal/serveredition/auth/oauth_handler.go:372-375`): "a callback with a live state but neither `code` nor an RFC 6749 `error` is classified `authorization_denied`/403; FR-024 requires the unavailability (503) class for failures not attributable to the user". FR-024's 503 class is explicitly scoped to "IdP-side failures (`discovery_failed`, `provider_error`)" and "proxy-side failures after verification" — infrastructure/transport failures, not a malformed callback request. A callback with a live, still-pending `state` but no `code`/`error` is far more consistent with a stale bookmark, replay, or direct/forged hit on the callback URL than with an IdP that itself misbehaved; the same code path's doc comment (`oauth_handler.go:340-342`) documents this as a deliberate classification decision, and a dedicated, already-passing test (`oauth_handler_refusal_test.go:606`, "live state with neither code nor error is refused with the generic page") explicitly asserts the 403-class vocabulary for this exact case, matching `state_invalid`'s existing 403 treatment for a comparably malformed request. This code was last touched in round 1 (`fd27d276f`) and unchanged since; re-raised with no memory of the prior design decision, same pattern as round 4's two re-raised-and-rejected findings.
+
+Verification for the fixes: `go build -tags server -o /dev/null ./cmd/mcpproxy` and `go build -o /dev/null ./cmd/mcpproxy` (both editions), `gofmt -l` clean on all six touched files, `go test -tags server ./internal/serveredition/... ./internal/telemetry/... ./tests/oauthserver/...` and `go test -race -tags server -skip "E2E|Binary|MCPProtocol|TestInfoEndpoint|TestGracefulShutdownNoPanic|TestSocketInfoEndpoint" ./internal/serveredition/...` — all green. `bash -n` and `shellcheck` clean on `scripts/dev-server-edition.sh`. `wc -l internal/serveredition/auth/oidc_jwks.go` = 142 (untouched this round, still under the 150-line budget). Only `internal/serveredition/...`, `docs/configuration/config-file.md` and `scripts/dev-server-edition.sh` changed, so the heavier `./internal/server/...`/`./internal/httpapi/...` race sweep (unaffected, no changes to those packages or their call paths) was not re-run.
+
+Round 5 commit: see the `fix(spec-107): cross-review round 5 for PR-B` commit on this branch. Rounds used so far: 5/10.
+
+**Round 6** (2026-09-17, reviewer: `opencode run --model github-copilot/gpt-5.6-sol`, four briefs — provider+verification / handler+pages+subject binding / front door+config / telemetry+rig+frontend, run sequentially under the single-flight lock): 5 findings across chunks 1, 3 and 4 (chunk 2 clean), 4 genuine after verification against the live tree, 1 rejected.
+
+- **Fixed** (chunk 1, provider — `internal/config/server_edition_config.go`, `internal/serveredition/auth/oauth_providers.go`):
+  - (P2) `newGenericOIDCProvider`'s (and `ApplyDefaults`'s) openid-scope injection used a case-INSENSITIVE membership check (`containsFold`/`containsFoldOIDC`) before deciding whether to append the literal `"openid"` scope. OAuth/OIDC scope values are case-sensitive (RFC 6749 §3.3): an operator-configured `"OpenID"`/`"OPENID"` was treated as already satisfying the requirement and the exact-case `"openid"` was never appended, so a compliant IdP — which does not recognise the differently-cased value as the OIDC scope — could return no `id_token` and every login for that (accepted-at-boot) config would fail. Fixed: both call sites now use a new case-sensitive `containsExact`/`containsExactOIDC`, so the literal `"openid"` is always appended when not present byte-for-byte, even alongside a differently-cased lookalike (harmless duplicate scope). The now-unused `containsFold` was removed. `go test -tags server ./internal/config/... ./internal/serveredition/auth/...` green.
+- **Fixed** (chunk 3, front door/config — `internal/config/server_edition_config.go`, `internal/config/loader.go`, `internal/config/serveredition_accessors_stub.go`, `internal/serveredition/auth/oauth_handler.go`):
+  - (P2, the round's most consequential finding) `expandServerEditionSecrets` resolved `server_edition.oauth.client_id`/`client_secret` `${env:...}`/`${keyring:...}` references IN PLACE on the `*Config` `LoadFromFile` returns — and that exact object is `r.cfg`/`r.desiredCfg`, the merge base `GetDesiredConfig` hands `handlePatchConfig` and the object `ApplyConfig` marshals straight to disk via `config.SaveConfig`. So ANY later `PATCH /api/v1/config` or `POST /api/v1/config/apply` — even one editing a field with nothing to do with OAuth — round-tripped the already-resolved client secret back through `SaveConfig` and permanently overwrote the operator's `${env:...}` reference in `mcp_config.json` with the plaintext secret, defeating `docs/configuration/config-file.md`'s documented purpose of keeping it out of the file (and every other doc page for this block that tells the operator to write `${env:OIDC_CLIENT_SECRET}`). Verified end-to-end by tracing `LoadFromFile` → `r.cfg`/`r.desiredCfg` (`runtime.go` boot assignment) → `handlePatchConfig`'s `desiredConfigForPatch`/`GetDesiredConfig` (a JSON copy of the SAME already-resolved value, not a fresh unexpanded load) → `ApplyConfig`'s `config.SaveConfig(newCfg, savePath)`. Fixed by moving resolution out of the generic Load path entirely, to the one place that actually needs the live secret: `expandServerEditionSecrets` became a non-mutating `resolveOAuthSecretRef` helper, called (a) read-only inside `ServerEditionConfig.Validate()` to keep the existing "client_secret is required" refusal on a missing env var (rounds 1/2's contract, now self-contained in `Validate()` instead of depending on Load-time ordering) and (b) in `auth.NewOAuthHandler`, on its own private, never-persisted `h.oauthCfg` clone, to produce the actual value the token endpoint receives. `expandServerEditionSecrets`'s personal-build stub was removed with it (function no longer exists). New tests: `TestLoadFromFile_DoesNotResolveOAuthSecretIntoTheReturnedConfig` (the loaded `Config` keeps the `${env:...}` text; a `SaveConfig` immediately after load — exactly `ApplyConfig`'s call — writes the reference back to disk, never the secret) and `TestNewOAuthHandler_ResolvesEnvSecretRefForTokenExchange` (the handler's own clone resolves the reference and a real token exchange against the mock IdP succeeds with it). `go test -tags server ./internal/config/... ./internal/serveredition/...` green; both editions build.
+  - (P2) `ServerEditionConfig.Validate()`'s `issuer_url` check (`IsAllowedOIDCEndpoint`, shared with the discovered endpoints, which have no such restriction) admitted a query or fragment component, but OpenID Connect Discovery 1.0 §2 requires the Issuer Identifier to carry neither. An issuer_url with either passed validation at boot and only failed later, at login time: `fetchDiscovery` builds the discovery request by string-appending `/.well-known/openid-configuration` to `issuer_url` — for `https://idp.example/issuer?tenant=x` that produces `.../issuer?tenant=x/.well-known/openid-configuration`, a URL whose well-known suffix lands inside the query string instead of the path, so discovery (and every login) failed for that (accepted-at-boot) config. Fixed with an explicit `url.RawQuery`/`Fragment`/`RawFragment` check in `validateOIDC`, refusing the same way at boot/PATCH/apply. New tests: `TestServerEditionOIDC_IssuerURLRejectsQueryAndFragment` (query, fragment, both) and `TestServerEditionOIDC_IssuerURLWithoutQueryOrFragmentStillAdmitted` (no false-positive on a normal path-only issuer). `go test -tags server ./internal/config/...` green.
+- **Fixed** (chunk 4, telemetry/rig — `tests/oauthserver/authorize.go`, `scripts/dev-server-edition.sh`):
+  - (P3) `handleAuthorizePOST` never checked `ErrorMode.AuthAccessDenied`/`AuthInvalidRequest` (only `handleAuthorizeGET` did), so a caller that POSTs straight to the authorize endpoint without a preceding GET — exactly what `scripts/dev-server-edition.sh`'s `headless_login` does — silently bypassed both injected knobs; the production Go test suite was unaffected because `oauth_handler_refusal_test.go`'s `AuthAccessDenied` fixture uses `rig.authorizeGET`, not a POST-only path. Fixed by mirroring the same two checks at the top of `handleAuthorizePOST`, before the consent/credential logic — a real IdP decides these at the authorization request, before any login form is shown, regardless of whether the caller GETs the form or (as a headless script simulating the submission) POSTs directly. New tests: `TestOIDC_ErrorModeKnobs/AuthAccessDenied_on_a_POST-only_caller` and `.../AuthInvalidRequest_on_a_POST-only_caller`, both driving `authorizePOST` (no preceding GET) and asserting the injected `error` reaches the redirect. `go test -tags server ./tests/oauthserver/...` green.
+- **Rejected** (chunk 4, telemetry — `internal/telemetry/telemetry.go:385`): "the wire key `member_count_bucket` breaks the FR-038 `user_count_bucket` contract". Genuine as a literal-text divergence from spec.md, but the file's own header comment (`telemetry.go:145-151`) documents this as a deliberate, load-bearing rename: `ScanForPII` rule 2 substring-matches the home-dir basename against the WHOLE wire form, keys included, and `"user"` is the username of every `USER user` container image (the server edition's own topology) — a key containing `"user"` would have had every heartbeat from such an install refused before it left the machine (`TestPayloadV13_PassesScanWithCommonUsernameBlocked` pins this). HARD RULE 9: when task text and code disagree, the code wins.
+  - Note: an earlier attempt at the chunk-4 GroupsNonArray finding below ("a JSON string groups claim silently tests the valid single-group path instead of a genuinely malformed one") was itself a false positive — `internal/serveredition/auth/oidc_verify_test.go`'s existing, already-passing `TestOIDCVerify_GroupsClaimMissingFailsClosed/single_string_is_one_group` fixture proves a bare-string groups claim is INTENDED to be one valid group (FR-008's "non-array/non-string shape" phrasing admits array-or-string), matching `groupsFromClaims`'s `case string:`. Changing `tests/oauthserver/token.go`'s `GroupsNonArray` to emit a genuinely non-array/non-string value (as the reviewer's framing implied it should) broke that fixture and `TestOIDC_ErrorModeKnobs/GroupsNonArray`; reverted to the original `joinGroups`-based string. The REAL, narrower bug — confirmed genuine — was only in `scripts/dev-server-edition.sh`: it folded `-groups-error non-array` into the same `GROUPS_TAMPER="1"` bucket as `absent`/`overage` and asserted `groups==[]`, but a single-group user's joined string (e.g. alice's `"eng"`) round-trips through `groupsFromClaims` back to `["eng"]` — the same non-empty value the ordinary (non-tamper) path already asserts, never `[]`. Fixed by carving `-groups-error non-array` out of the `GROUPS_TAMPER` case into its own no-op case (neither `TAMPER` nor `GROUPS_TAMPER`), falling through to the script's existing `groups==["eng"]` assertion, which already matches what this claim shape actually produces. `bash -n` and `shellcheck` clean.
+
+Verification for the fixes: `go build -tags server -o /dev/null ./cmd/mcpproxy` and `go build -o /dev/null ./cmd/mcpproxy` (both editions), `gofmt -l` clean on all eleven touched files, `go test -tags server -count=1 ./internal/config/... ./internal/serveredition/... ./internal/telemetry/... ./tests/oauthserver/...` all green, `go test -tags server -skip "E2E|Binary|MCPProtocol|TestInfoEndpoint|TestGracefulShutdownNoPanic|TestSocketInfoEndpoint" ./internal/server/... ./internal/httpapi/...` (the wider sweep, since `oauth_handler.go` and the config load path both changed this round) also green. `bash -n` and `shellcheck` clean on `scripts/dev-server-edition.sh`.
+
+Round 6 commit: see the `fix(spec-107): cross-review round 6 for PR-B` commit on this branch. Rounds used so far: 6/10.
+
+**Round 7** (2026-09-17, reviewer: `opencode run --model github-copilot/gpt-5.6-sol`, four briefs — provider+verification / handler+pages+subject binding / front door+config / telemetry+rig+frontend, run sequentially under the single-flight lock; round 6's briefs re-issued unmodified since HEAD had not moved when round 7 started): 7 findings across all four chunks, all 7 genuine after verification against the live tree, none rejected. (Round 7 was interrupted mid-run on a prior attempt before any verdict — chunk 1's stale log carried no `VERDICT:` line and was re-run in full rather than trusted.)
+
+- **Fixed** (chunk 1, provider — `internal/serveredition/auth/oidc_provider.go`):
+  - (P2) `verifyIDToken` read `claims["email_verified"].(bool)` with the two-value form and treated a failed type assertion exactly like an absent claim (`ok == false` either way). A present-but-non-boolean value (e.g. the JSON string `"false"`, or `0`) was therefore silently dropped to `nil`, and under the default `refuse_false` policy `nil` login is allowed — so a malformed claim whose plain-text value clearly means "not verified" logged the user in anyway; only `require_true` (which also refuses `nil`) happened to catch it. Fixed: a present, non-null, non-boolean `email_verified` is now refused as `id_token_invalid` before any policy is applied, instead of being silently reinterpreted as absent (JSON `null` — the fake IdP's existing stand-in for "absent" — still maps to `nil`/absent, unchanged). New test `TestOIDCVerify_EmailVerifiedMalformedType`. `go test -tags server ./internal/serveredition/auth/...` green (including the full `TestOIDCVerify_EmailVerifiedPolicy` matrix, unaffected).
+- **Fixed** (chunk 2, handler — `internal/serveredition/auth/oauth_handler.go`):
+  - (P3) `HandleCallback`'s own doc comment promises "the pending state is consumed FIRST; only then is the response classified", but the code checked `h.providerErr` (set once, restart-pinned, at handler construction) before `consumePendingState`. A broken provider config therefore made every callback — including one with a missing, unknown or garbage `state` — answer 503 `internal_error` instead of 403 `state_invalid`, contradicting the documented contract and letting an unauthenticated caller distinguish "OAuth is misconfigured" from "OAuth is fine, your state is bad" purely from the HTTP status. Fixed by moving the `providerErr` check to after state consumption, matching the doc comment (in practice `h.providerErr` being restart-pinned means `HandleLogin` — which checks it first — never stores a pending state when the provider is broken, so this now reads as `state_invalid` for any callback in that condition, exactly as the contract requires). New test `TestHandleCallback_BrokenProviderStillStateFirst`. `go test -tags server ./internal/serveredition/auth/... -run TestHandleCallback` green (16 cases incl. the two existing 503-provider/internal-error suites, unaffected).
+- **Fixed** (chunk 3, front door/config — `internal/serveredition/api/connector_provider.go`, `internal/serveredition/auth/oidc_provider.go`):
+  - (P2) `connectorProvider.connector` caches one `*broker.OAuthConnector` (plus its in-memory PKCE/state) per `serverKey + "|" + base`, unbounded. With `server_edition.public_url` unset, `base` comes from `config.ForwardedHeaders(r, trusted).Host`, which defaults to `r.Host` regardless of trusted-proxy status — and `r.Host` is caller-controlled on every direct HTTP/1.1 request (any client can set an arbitrary `Host` header, no forwarded-header trust needed). A caller could therefore mint and permanently cache one connector per distinct `Host` value it sends, an unbounded memory-growth DoS. Fixed with a 256-entry FIFO-eviction bound (`connectorCacheCap` + an insertion-order slice) — generous for any real deployment's handful of origins, but no longer unbounded. New tests `TestConnectorProvider_CacheIsBounded` (cap holds under 266 distinct Host values) and `TestConnectorProvider_CacheKeepsRecentEntries` (the base in active use survives eviction).
+  - (P3) `docs/development/server-edition-multiuser-auth.md` and `docs/configuration/config-file.md` both state that an OIDC discovery issuer mismatch logs the configured and discovered issuer values — matching spec.md's Edge Cases requirement ("the log line names both values (they are not secrets) with the fix") — but `fetchDiscovery` only ever emitted the fixed string `"discovery issuer does not equal issuer_url"`, naming neither. Fixed: the check text now names both (`discovery issuer %q does not equal issuer_url %q`), delivering what the docs and spec already promised. New test `TestOIDCDiscovery_IssuerMismatchNamesBothValues`, driving `fetchDiscovery` against a local server serving a mismatched issuer.
+- **Fixed** (chunk 4, rig — `scripts/dev-server-edition.sh`):
+  - (P2) `--phase b` exited right after the open-redirect check (§4d), before the `/mcp` session-cookie-401 and no-credential-401 assertions that then lived under §6 (gated behind `--phase d`). T035/T062 explicitly scope those two checks to phase b itself (they need nothing from PR-C/PR-D — MCP auth gating is PR-B's own FR-003/FR-029). Fixed by moving both checks to a new §4e, run unconditionally before the phase-b exit; the duplicate copy under §6 was removed. Verified live: `--phase b` now prints "§4e /mcp refuses a session cookie and refuses no credential" before "phase b complete".
+  - (P2) `--idp-args "-discovery-http-token-endpoint"` is documented as one of the tamper flags expecting a 503 at the callback, but that flag makes discovery fail synchronously inside `/auth/login` itself (discovery runs before the redirect to the IdP is built) — `headless_login`'s step 4a unconditionally required a 302/303/307 there and `die`d otherwise, so this tamper case's downstream `want="503"` handling was unreachable dead code. Fixed: when `TAMPER=1` and `/auth/login` itself answers something other than a redirect, `headless_login` now returns that response directly instead of dying, letting the existing downstream 503 assertion actually run. Verified live: `--idp-args "-discovery-http-token-endpoint"` now reaches and passes "4c tamper case refused with 503 and no session", where it previously died at step 4a before that assertion ran.
+  - (P2) Phase D's token-mint step read `jq -r '.raw_token // empty'`, but `POST /api/v1/user/tokens`' `AgentTokenResponse.RawToken` serializes as `json:"token,omitempty"` — the field is `.token`, never `.raw_token` — so `--phase d` always failed "6 token mint as alice returned no raw_token" before exercising `/mcp` or the audit log at all. Fixed: `.raw_token` → `.token`. (Confirmed by source inspection, not a live phase-d run: this branch's `--phase c`/`--phase d` already fail earlier, at §5's tenant-REST checks, because PR-C has not merged into this worktree yet — a pre-existing, unrelated gap, not caused or masked by this fix.)
+  - `bash -n` and `shellcheck` clean throughout.
+
+Verification for the fixes: `go build -tags server -o /dev/null ./cmd/mcpproxy` and `go build -o /dev/null ./cmd/mcpproxy` (both editions) clean; `gofmt -l` clean on all seven touched/added Go files; `go vet -tags server ./internal/serveredition/...` clean; `go test -tags server -race ./internal/serveredition/...` and `go test -tags server -count=1 ./internal/config/... ./internal/serveredition/... ./tests/oauthserver/...` all green; golangci-lint v2.9.0 (module-cache pinned, same tooling note as prior rounds) `run --config .github/.golangci.yml --build-tags server --timeout=10m ./internal/serveredition/... ./scripts/...` — `0 issues`. `bash -n` and `shellcheck` clean on `scripts/dev-server-edition.sh`. Live reruns of the rig: `--phase b` (clean, includes the new §4e check), `--phase b --idp-args "-discovery-http-token-endpoint"` (now correctly exercises and passes the 503 path), `--phase d` (fails at §5, pre-existing PR-C-not-merged gap, unrelated to this round's fixes).
+
+Round 7 commit: see the `fix(spec-107): cross-review round 7 for PR-B` commit on this branch. Rounds used so far: 7/10.
+
+**Round 8** (2026-09-17, reviewer: `opencode run --model github-copilot/gpt-5.6-sol`, four briefs reused unmodified from round 7 — provider+verification / handler+pages+subject binding / front door+config / telemetry+rig+frontend, run sequentially under the single-flight lock): 6 findings across all four chunks, all 6 genuine after verification against the live tree, none rejected.
+
+- **Fixed** (chunk 1, provider — `internal/serveredition/auth/oidc_provider.go`):
+  - (P2) `verifyIDToken` read `claims["azp"].(string)` with the two-value form and, exactly like round 7's `email_verified` bug, treated a failed type assertion as absent. A present-but-non-string `azp` (e.g. a JSON number) on a single-audience token therefore skipped the azp check entirely — `hasAzp` was `false`, so neither the "multi-aud without azp" branch nor the equality branch ran — even though OIDC defines `azp`, when present, as a string that must identify this client. Fixed: a present, non-null, non-string `azp` is now refused as `audience_mismatch` before the existing `hasAzp`/equality logic runs (JSON `null` still maps to absent, matching the codebase's existing convention). New test case `TestOIDCVerify_TamperMatrix/azp_present_but_non-string` plus a new `oauthserver.ErrorMode.IDTokenAzpNonString` tamper knob (`tests/oauthserver/options.go`, `token.go`) since the existing token minter always overwrites `azp` with a valid client ID absent a dedicated knob. `go test -tags server ./internal/serveredition/auth/... -run TestOIDCVerify_TamperMatrix` green (all 14 cases).
+- **Fixed** (chunk 2, handler — `internal/serveredition/auth/oauth_handler.go`):
+  - (P2) `HandleCallback` set `attempt.emailHash` right after the email claim was verified and left it set on the `default` branch of the `UpdateUserLogin` error switch (any store error other than `ErrSubjectMismatch`/`ErrUserDisabled`), so an `internal_error` event carried `email_hash` even though the store HAD been consulted (and failed) — FR-013 reserves `email_hash` for reasons where the store was NOT yet consulted (`domain_not_allowed`, `userinfo_subject_mismatch`, a userinfo-stage `provider_error`), and the existing failing-store test only asserted `UserID`, leaving this untested. Fixed with a new `loginAttempt.clearEmailHash()` helper, called on the `default` branch before `attempt.unavailable`. New assertion added to the existing `TestHandleCallback_Unavailable_InternalErrorRenders503/failing_loginStore` sub-test. `go test -tags server ./internal/serveredition/auth/... -run TestHandleCallback_Unavailable_InternalErrorRenders503` green.
+- **Fixed** (chunk 3, front door/config — `internal/serveredition/api/connector_provider.go`, `internal/serveredition/broker/oauth_connector.go`, `internal/config/trusted_proxies.go`):
+  - (P2) Round 7's FIFO-eviction bound on `connectorProvider.cache` protected memory but not availability: with `public_url` unset, an authenticated tenant could mint distinct `Host`-keyed connectors to force eviction of the OLDEST entry regardless of whether it held another user's in-flight connect flow (PKCE state issued, callback not yet received) — turning a memory-growth defense into a cross-user denial-of-service against a real, in-progress login. Fixed: `broker.OAuthConnector` gained an exported `HasPendingFlow()` (GC's expired flows, then reports whether any remain); `connectorProvider.connector`'s eviction (`evictOneLocked`) now scans insertion order for the oldest entry WITHOUT a pending flow and evicts that instead of blindly evicting index 0 (falling back to the absolute oldest only if every cached connector somehow has a pending flow, which never happens in practice at the 256 cap — the bound itself is never violated). New test `TestConnectorProvider_EvictionSparesPendingFlow` (fills the cache, seeds a pending flow on the oldest entry, forces one more eviction, asserts the pending entry survives and an idle one is dropped instead, and that the pending flow is still resolvable through the surviving connector). `go test -tags server ./internal/serveredition/api/... ./internal/serveredition/broker/...` green.
+  - (P2) `config.ForwardedHeaders`'s X-Forwarded-For walk set `chosen = hop` for EVERY hop it visited, including ones that failed `net.ParseIP` — so the right-most hop being a non-IP token (`"unknown"`, `"garbage"`, or an address still carrying its port like `"203.0.113.5:1234"`) won the walk and was written straight into `ForwardedInfo.ClientIP`, feeding the session record and every audit line with a non-IP string instead of skipping the unparsable hop and continuing left for a real one. The X-Real-IP fallback had the same gap: any string was accepted verbatim with no `net.ParseIP` check at all. Fixed: the XFF loop now calls `net.ParseIP(hop)` before considering a hop a candidate (skipping unparsable ones outright, falling back to the trusted peer's own address when every hop is unparsable) and X-Real-IP is accepted only when it parses as an IP. New test cases in `TestForwardedHeadersTrustedPeer`: unparsable right-most hop skipped, hop-with-port skipped, entirely-unparsable XFF falls back to the peer, unparsable X-Real-IP falls back to the peer. `go test ./internal/config/... -run 'TestForwardedHeaders|TestIsTrustedProxy'` green (23 sub-tests).
+- **Fixed** (chunk 4, rig — `scripts/dev-server-edition.sh`):
+  - (P2) §5's `c -b "$J" "$BASE/api/v1/servers" | jq -e '[.servers[].name]==["a"]'` read the servers array at the response's top level, but `GET /api/v1/servers` (the core `httpapi` handler, unlike the serveredition-only `/user/servers`/`/user/tokens` routes used elsewhere in the same section) wraps its payload in the standard `contracts.SuccessResponse{success, data}` envelope (confirmed by source inspection of `handleGetServers`/`writeSuccess`/`contracts.NewSuccessResponse`) — so the array actually lives at `.data.servers`, and this assertion always failed with `jq: Cannot iterate over null (null)` once PR-C makes tenant filtering reachable, never validating entitlement filtering at all. Fixed: `.servers[]` → `.data.servers[]`. Live-verified: `--phase c` now fails later, at this exact line's `die`, with the corrected jq path reaching and correctly reporting `Cannot iterate over null (null)` against the real (pre-PR-C) response body rather than being masked by the same symptom the old, wrong path would have also produced — the fix cannot be end-to-end verified against a real tenant-filtered list until PR-C merges into this worktree (same pre-existing gap round 7 documented for phase d), but is grounded in the handler's source, not guesswork.
+  - (P2) §6's `hidden="$(mcp ... b:echo ...)" ` captured the hidden server's refusal text but never asserted it WAS a refusal — an authorization regression letting Alice's token (scoped to `["a"]`) call server `b` would pass the rig silently. Fixed: capture the full JSON response and assert `.result.isError==true` before proceeding, so a regression that let `b:echo` through (isError=false) now fails the rig instead of only being visible in a log line a human has to read.
+  - `bash -n` and `shellcheck` clean.
+
+Verification for the fixes: `go build -tags server -o /dev/null ./cmd/mcpproxy` and `go build -o /dev/null ./cmd/mcpproxy` (both editions) clean; `gofmt -l` clean on all eleven touched/added Go files; `go vet -tags server ./internal/serveredition/... ./internal/config/...` clean; `go test -tags server -race -count=1 ./internal/serveredition/...` and `go test -tags server -count=1 ./internal/config/... ./internal/serveredition/... ./tests/oauthserver/...` all green; `go test -tags server -skip "E2E|Binary|MCPProtocol|TestInfoEndpoint|TestGracefulShutdownNoPanic|TestSocketInfoEndpoint" ./internal/server/... ./internal/httpapi/...` (wider sweep, since `oauth_handler.go`, `connector_provider.go` and the shared `trusted_proxies.go` all changed this round) also green. golangci-lint could not run this round: the pinned v2 binary (2.5.0, built with go1.25.1) refuses to load `.github/.golangci.yml` against this module's `go 1.26.0` directive ("the Go language version used to build golangci-lint is lower than the targeted Go version") — a pre-existing local-tooling/go-toolchain mismatch unrelated to this round's changes (see `go-toolchain-bump-traps` project memory); `go vet` stood in as the static-analysis gate instead. `bash -n` and `shellcheck` clean on `scripts/dev-server-edition.sh`. Live reruns of the rig: `--phase b` (clean, unaffected by this round's script changes since they live in the §5/§6 block gated behind `--phase c`/`--phase d`); `--phase c` reaches the corrected `.data.servers` assertion and fails there exactly as round 7's phase-d gap predicts (pre-existing PR-C-not-merged gap, not a regression from this round).
+
+Round 8 commit: see the `fix(spec-107): cross-review round 8 for PR-B` commit on this branch. Rounds used so far: 8/10.
+
 ## PR-C — entitlement predicate, group grants, tenant Web UI session
 
 ### Real instance
diff --git a/tests/oauthserver/authorize.go b/tests/oauthserver/authorize.go
index 4d03b63c6..81b5a0c65 100644
--- a/tests/oauthserver/authorize.go
+++ b/tests/oauthserver/authorize.go
@@ -27,6 +27,7 @@ type LoginPageData struct {
 	CodeChallenge       string
 	CodeChallengeMethod string
 	Resource            string
+	Nonce               string // OIDC nonce, carried through the form and echoed in the id_token
 	Scopes              []string
 	Error               string
 }
@@ -55,6 +56,7 @@ func (s *OAuthTestServer) handleAuthorizeGET(w http.ResponseWriter, r *http.Requ
 	codeChallenge := query.Get("code_challenge")
 	codeChallengeMethod := query.Get("code_challenge_method")
 	resource := query.Get("resource")
+	nonce := query.Get("nonce")
 
 	// Validate required parameters
 	if responseType != "code" {
@@ -127,6 +129,7 @@ func (s *OAuthTestServer) handleAuthorizeGET(w http.ResponseWriter, r *http.Requ
 		CodeChallenge:       codeChallenge,
 		CodeChallengeMethod: codeChallengeMethod,
 		Resource:            resource,
+		Nonce:               nonce,
 		Scopes:              scopes,
 	}
 
@@ -148,6 +151,7 @@ func (s *OAuthTestServer) handleAuthorizePOST(w http.ResponseWriter, r *http.Req
 	codeChallenge := r.FormValue("code_challenge")
 	codeChallengeMethod := r.FormValue("code_challenge_method")
 	resource := r.FormValue("resource")
+	nonce := r.FormValue("nonce") // body field from the form, or query param on a headless POST
 
 	// Get user credentials
 	username := r.FormValue("username")
@@ -173,6 +177,24 @@ func (s *OAuthTestServer) handleAuthorizePOST(w http.ResponseWriter, r *http.Req
 		return
 	}
 
+	// Same injected authorization-time errors as handleAuthorizeGET, mirrored
+	// here: a real IdP decides these at the authorization request, before any
+	// login form is shown, so they apply the same way whether a caller GETs
+	// the authorize endpoint (renders the form) or POSTs straight to it — a
+	// caller that never performed the intermediate GET (a headless script
+	// simulating the form submission directly, as scripts/dev-server-edition.sh
+	// does) must still observe them (cross-review round 6, chunk 4 P3: they
+	// were checked on GET only, so `-auth-error access_denied`/`invalid_request`
+	// were silently bypassed by any POST-only caller).
+	if s.options.ErrorMode.AuthInvalidRequest {
+		s.authorizeError(w, redirectURI, state, "invalid_request", "Injected error")
+		return
+	}
+	if s.options.ErrorMode.AuthAccessDenied {
+		s.authorizeError(w, redirectURI, state, "access_denied", "Injected error")
+		return
+	}
+
 	// Check if user denied
 	if action == "deny" || consent != "on" {
 		s.authorizeRedirect(w, redirectURI, "", state, "access_denied", "User denied the authorization request")
@@ -191,6 +213,7 @@ func (s *OAuthTestServer) handleAuthorizePOST(w http.ResponseWriter, r *http.Req
 			CodeChallenge:       codeChallenge,
 			CodeChallengeMethod: codeChallengeMethod,
 			Resource:            resource,
+			Nonce:               nonce,
 			Scopes:              s.parseScopes(scope),
 			Error:               "Invalid username or password",
 		}
@@ -211,6 +234,7 @@ func (s *OAuthTestServer) handleAuthorizePOST(w http.ResponseWriter, r *http.Req
 		CodeChallengeMethod: codeChallengeMethod,
 		Resource:            resource,
 		State:               state,
+		Nonce:               nonce,
 		Subject:             username,
 		ExpiresAt:           time.Now().Add(s.options.AuthCodeExpiry),
 		Used:                false,
diff --git a/tests/oauthserver/cmd/server/main.go b/tests/oauthserver/cmd/server/main.go
index a209b9722..ff1693760 100644
--- a/tests/oauthserver/cmd/server/main.go
+++ b/tests/oauthserver/cmd/server/main.go
@@ -6,20 +6,35 @@
 //	go run ./tests/oauthserver/cmd/server -port 9000 -no-dcr -no-device-code
 //	go run ./tests/oauthserver/cmd/server -port 9000 -detection=www-authenticate
 //
+// Fake OpenID Provider for the server edition (Spec 107, research D2):
+//
+//	go run ./tests/oauthserver/cmd/server -port 9000 -oidc \
+//	  -redirect-uri http://127.0.0.1:18080/api/v1/auth/callback \
+//	  -user 'alice@example.com:pass:eng,sre' -user 'bob@example.com:pass:' \
+//	  -groups-claim groups
+//
+// Tamper knobs for the US2 matrix: -token-error <name>, -groups-error <name>,
+// -userinfo-error <name>, -userinfo-sub-mismatch, -email-verified=false,
+// -discovery-http-token-endpoint, -token-endpoint-redirect (see -help).
+//
 // This starts the OAuth test server on http://localhost:9000 with:
 //   - Authorization endpoint: /authorize
 //   - Token endpoint: /token
-//   - Discovery: /.well-known/oauth-authorization-server
-//   - JWKS: /.well-known/jwks.json
+//   - Discovery: /.well-known/oauth-authorization-server and /.well-known/openid-configuration
+//   - JWKS: /jwks.json
 //   - DCR: /registration (if enabled)
 //   - Device code: /device_authorization (if enabled)
+//   - Userinfo: /userinfo (with -oidc)
 //
-// Test credentials: testuser / testpass
+// Test credentials: testuser / testpass (or the -user entries)
 package main
 
 import (
+	"crypto/sha256"
+	"encoding/hex"
 	"flag"
 	"fmt"
+	"io"
 	"log"
 	"os"
 	"os/signal"
@@ -30,39 +45,79 @@ import (
 	"github.com/smart-mcp-proxy/mcpproxy-go/tests/oauthserver"
 )
 
-func main() {
+// cliConfig is everything main needs beyond the server options.
+type cliConfig struct {
+	Port          int
+	DetectionName string
+	Options       oauthserver.Options
+}
+
+// stringList is a repeatable string flag.
+type stringList []string
+
+func (l *stringList) String() string     { return strings.Join(*l, ",") }
+func (l *stringList) Set(v string) error { *l = append(*l, v); return nil }
+
+// parseFlags maps the CLI arguments onto oauthserver.Options (T034).
+func parseFlags(args []string) (oauthserver.Options, error) {
+	cfg, err := parseCLI(args, io.Discard)
+	return cfg.Options, err
+}
+
+// parseCLI parses args (without the program name) with a private FlagSet so
+// it is reusable from tests; usage and parse errors are written to usageOut.
+func parseCLI(args []string, usageOut io.Writer) (cliConfig, error) {
+	fs := flag.NewFlagSet("oauthserver", flag.ContinueOnError)
+	fs.SetOutput(usageOut)
+
 	// Server settings
-	port := flag.Int("port", 9000, "Port to listen on")
+	port := fs.Int("port", 9000, "Port to listen on")
 
 	// Feature toggles
-	noAuthCode := flag.Bool("no-auth-code", false, "Disable authorization code flow")
-	noDeviceCode := flag.Bool("no-device-code", false, "Disable device code flow (RFC 8628)")
-	noDCR := flag.Bool("no-dcr", false, "Disable dynamic client registration (RFC 7591)")
-	noClientCreds := flag.Bool("no-client-credentials", false, "Disable client credentials flow")
-	noRefreshToken := flag.Bool("no-refresh-token", false, "Disable refresh tokens")
+	noAuthCode := fs.Bool("no-auth-code", false, "Disable authorization code flow")
+	noDeviceCode := fs.Bool("no-device-code", false, "Disable device code flow (RFC 8628)")
+	noDCR := fs.Bool("no-dcr", false, "Disable dynamic client registration (RFC 7591)")
+	noClientCreds := fs.Bool("no-client-credentials", false, "Disable client credentials flow")
+	noRefreshToken := fs.Bool("no-refresh-token", false, "Disable refresh tokens")
 
 	// Security settings
-	requirePKCE := flag.Bool("require-pkce", true, "Require PKCE for authorization code flow (RFC 7636)")
-	requireResource := flag.Bool("require-resource", false, "Require RFC 8707 resource indicator")
+	requirePKCE := fs.Bool("require-pkce", true, "Require PKCE for authorization code flow (RFC 7636)")
+	requireResource := fs.Bool("require-resource", false, "Require RFC 8707 resource indicator")
 
 	// Compatibility modes
-	runlayerMode := flag.Bool("runlayer-mode", false, "Mimic Runlayer's strict validation (implies -require-resource, returns Pydantic-style 422 errors)")
+	runlayerMode := fs.Bool("runlayer-mode", false, "Mimic Runlayer's strict validation (implies -require-resource, returns Pydantic-style 422 errors)")
 
 	// Detection mode
-	detectionMode := flag.String("detection", "both", "OAuth detection mode: discovery, www-authenticate, explicit, both")
+	detectionMode := fs.String("detection", "both", "OAuth detection mode: discovery, www-authenticate, explicit, both")
 
 	// Per-method MCP authorisation (GH #1271 repro)
-	perMethodAuth := flag.Bool("per-method-auth", false, "Serve initialize/tools/list on /mcp anonymously and require a token only for tools/call (Google Gmail MCP behaviour)")
+	perMethodAuth := fs.Bool("per-method-auth", false, "Serve initialize/tools/list on /mcp anonymously and require a token only for tools/call (Google Gmail MCP behaviour)")
 
 	// Token lifetimes
-	accessTokenTTL := flag.Duration("access-token-ttl", time.Hour, "Access token expiry duration")
-	refreshTokenTTL := flag.Duration("refresh-token-ttl", 24*time.Hour, "Refresh token expiry duration")
+	accessTokenTTL := fs.Duration("access-token-ttl", time.Hour, "Access token expiry duration")
+	refreshTokenTTL := fs.Duration("refresh-token-ttl", 24*time.Hour, "Refresh token expiry duration")
+
+	// OIDC (Spec 107)
+	oidc := fs.Bool("oidc", false, "Act as an OpenID Provider: id_token in the auth-code response, /userinfo, EC key in the JWKS")
+	var users stringList
+	fs.Var(&users, "user", "OIDC user as email:password[:group1,group2] (repeatable; groups may be empty)")
+	var redirectURIs stringList
+	fs.Var(&redirectURIs, "redirect-uri", "Extra redirect URI accepted for every pre-registered client (repeatable)")
+	groupsClaim := fs.String("groups-claim", "groups", "Name of the groups claim in the id_token and /userinfo")
 
 	// Error injection
-	tokenError := flag.String("token-error", "", "Inject token endpoint error: invalid_client, invalid_grant, invalid_scope, server_error")
-	authError := flag.String("auth-error", "", "Inject auth endpoint error: access_denied, invalid_request")
+	tokenError := fs.String("token-error", "", "Inject token endpoint error: invalid_client, invalid_grant, invalid_scope, server_error; with -oidc also an id_token defect: bad-signature, wrong-iss, wrong-aud, multi-aud-no-azp, expired, nbf-future, no-nonce, alg-none, hs256, unknown-kid, key-alg-mismatch")
+	authError := fs.String("auth-error", "", "Inject auth endpoint error: access_denied, invalid_request")
+	groupsError := fs.String("groups-error", "", "Groups-claim defect (with -oidc): non-array, overage, absent")
+	userinfoError := fs.String("userinfo-error", "", "Userinfo defect (with -oidc): sub-mismatch, redirect, non-json, unavailable")
+	userinfoSubMismatch := fs.Bool("userinfo-sub-mismatch", false, "Alias of -userinfo-error sub-mismatch")
+	emailVerified := fs.Bool("email-verified", true, "email_verified claim value (with -oidc); false injects EmailVerifiedFalse")
+	discoveryHTTPTokenEndpoint := fs.Bool("discovery-http-token-endpoint", false, "Discovery advertises a plain-http, non-loopback token_endpoint (with -oidc)")
+	tokenEndpointRedirect := fs.Bool("token-endpoint-redirect", false, "/token answers 302 to another origin (with -oidc)")
 
-	flag.Parse()
+	if err := fs.Parse(args); err != nil {
+		return cliConfig{}, err
+	}
 
 	// Parse detection mode
 	var dm oauthserver.DetectionMode
@@ -76,31 +131,91 @@ func main() {
 	case "both":
 		dm = oauthserver.Both
 	default:
-		log.Fatalf("Invalid detection mode: %s (valid: discovery, www-authenticate, explicit, both)", *detectionMode)
+		return cliConfig{}, fmt.Errorf("invalid -detection %q (valid: discovery, www-authenticate, explicit, both)", *detectionMode)
 	}
 
 	// Build error mode
 	var errMode oauthserver.ErrorMode
-	switch *tokenError {
-	case "invalid_client":
-		errMode.TokenInvalidClient = true
-	case "invalid_grant":
-		errMode.TokenInvalidGrant = true
-	case "invalid_scope":
-		errMode.TokenInvalidScope = true
-	case "server_error":
-		errMode.TokenServerError = true
+	if err := applyTokenError(&errMode, *tokenError, *oidc); err != nil {
+		return cliConfig{}, err
 	}
 	switch *authError {
+	case "":
 	case "access_denied":
 		errMode.AuthAccessDenied = true
 	case "invalid_request":
 		errMode.AuthInvalidRequest = true
+	default:
+		return cliConfig{}, fmt.Errorf("invalid -auth-error %q (valid: access_denied, invalid_request)", *authError)
+	}
+	switch *groupsError {
+	case "":
+	case "non-array":
+		errMode.GroupsNonArray = true
+	case "overage":
+		errMode.GroupsOverageMarker = true
+	case "absent":
+		errMode.GroupsAbsentEverywhere = true
+	default:
+		return cliConfig{}, fmt.Errorf("invalid -groups-error %q (valid: non-array, overage, absent)", *groupsError)
+	}
+	switch *userinfoError {
+	case "":
+	case "sub-mismatch":
+		errMode.UserinfoSubMismatch = true
+	case "redirect":
+		errMode.UserinfoRedirect = true
+	case "non-json":
+		errMode.UserinfoNonJSON = true
+	case "unavailable":
+		errMode.UserinfoUnavailable = true
+	default:
+		return cliConfig{}, fmt.Errorf("invalid -userinfo-error %q (valid: sub-mismatch, redirect, non-json, unavailable)", *userinfoError)
+	}
+	if *userinfoSubMismatch {
+		errMode.UserinfoSubMismatch = true
+	}
+	errMode.EmailVerifiedFalse = !*emailVerified
+	errMode.DiscoveryHTTPTokenEndpoint = *discoveryHTTPTokenEndpoint
+	errMode.TokenEndpointRedirect = *tokenEndpointRedirect
+	if !*oidc && (*groupsError != "" || *userinfoError != "" || *userinfoSubMismatch || !*emailVerified ||
+		*discoveryHTTPTokenEndpoint || *tokenEndpointRedirect) {
+		return cliConfig{}, fmt.Errorf("the OIDC tamper flags need -oidc")
+	}
+
+	// Users: email:password[:group1,group2]
+	validUsers := map[string]string{}
+	var userClaims map[string]map[string]any
+	for _, spec := range users {
+		email, password, claims, err := parseUserSpec(spec, *groupsClaim)
+		if err != nil {
+			return cliConfig{}, err
+		}
+		validUsers[email] = password
+		if userClaims == nil {
+			userClaims = map[string]map[string]any{}
+		}
+		userClaims[email] = claims
+	}
+	if len(validUsers) == 0 {
+		validUsers = nil // keep the testuser/testpass default
 	}
 
 	// Runlayer mode implies require-resource
 	effectiveRequireResource := *requireResource || *runlayerMode
 
+	testClientRedirects := []string{
+		"http://127.0.0.1/callback",
+		"http://localhost/callback",
+		"http://127.0.0.1:9000/callback", // Allow callback on same port as OAuth server
+		// mcpproxy's own loopback callback path (internal/oauth
+		// DefaultRedirectPath) — needed to drive a real login
+		// against this server.
+		"http://127.0.0.1/oauth/callback",
+		"http://localhost/oauth/callback",
+	}
+	testClientRedirects = append(testClientRedirects, redirectURIs...)
+
 	opts := oauthserver.Options{
 		// Feature toggles (inverted from no-* flags)
 		EnableAuthCode:          !*noAuthCode,
@@ -127,31 +242,117 @@ func main() {
 		// Error injection
 		ErrorMode: errMode,
 
+		// OIDC
+		OIDC:               *oidc,
+		ValidUsers:         validUsers,
+		UserClaims:         userClaims,
+		ClientRedirectURIs: []string(redirectURIs),
+		GroupsClaim:        *groupsClaim,
+
 		// Pre-register test-client for Playwright tests
 		Clients: []oauthserver.ClientConfig{
 			{
-				ClientID:   "test-client",
-				ClientName: "Test Client",
-				RedirectURIs: []string{
-					"http://127.0.0.1/callback",
-					"http://localhost/callback",
-					"http://127.0.0.1:9000/callback", // Allow callback on same port as OAuth server
-					// mcpproxy's own loopback callback path (internal/oauth
-					// DefaultRedirectPath) — needed to drive a real login
-					// against this server.
-					"http://127.0.0.1/oauth/callback",
-					"http://localhost/oauth/callback",
-				},
+				ClientID:     "test-client",
+				ClientName:   "Test Client",
+				RedirectURIs: testClientRedirects,
 			},
 		},
 	}
 
-	server := oauthserver.StartOnPort(nil, *port, opts)
+	return cliConfig{Port: *port, DetectionName: *detectionMode, Options: opts}, nil
+}
+
+// applyTokenError maps -token-error onto ErrorMode.
+func applyTokenError(errMode *oauthserver.ErrorMode, name string, oidc bool) error {
+	switch name {
+	case "":
+		return nil
+	case "invalid_client":
+		errMode.TokenInvalidClient = true
+		return nil
+	case "invalid_grant":
+		errMode.TokenInvalidGrant = true
+		return nil
+	case "invalid_scope":
+		errMode.TokenInvalidScope = true
+		return nil
+	case "server_error":
+		errMode.TokenServerError = true
+		return nil
+	}
+
+	idTokenKnobs := map[string]*bool{
+		"bad-signature":    &errMode.IDTokenBadSignature,
+		"wrong-iss":        &errMode.IDTokenWrongIssuer,
+		"wrong-aud":        &errMode.IDTokenWrongAudience,
+		"multi-aud-no-azp": &errMode.IDTokenMultiAudNoAzp,
+		"expired":          &errMode.IDTokenExpired,
+		"nbf-future":       &errMode.IDTokenNbfFuture,
+		"no-nonce":         &errMode.IDTokenNoNonce,
+		"alg-none":         &errMode.IDTokenAlgNone,
+		"hs256":            &errMode.IDTokenHS256,
+		"unknown-kid":      &errMode.IDTokenUnknownKid,
+		"key-alg-mismatch": &errMode.IDTokenKeyAlgMismatch,
+	}
+	knob, ok := idTokenKnobs[name]
+	if !ok {
+		return fmt.Errorf("invalid -token-error %q (valid: invalid_client, invalid_grant, invalid_scope, server_error, bad-signature, wrong-iss, wrong-aud, multi-aud-no-azp, expired, nbf-future, no-nonce, alg-none, hs256, unknown-kid, key-alg-mismatch)", name)
+	}
+	if !oidc {
+		return fmt.Errorf("-token-error %q is an id_token defect and needs -oidc", name)
+	}
+	*knob = true
+	return nil
+}
+
+// parseUserSpec parses "email:password[:group1,group2]" into the ValidUsers
+// entry and the UserClaims record (sub derived from the email, name = the
+// local part, email_verified true, groups under groupsClaim).
+func parseUserSpec(spec, groupsClaim string) (email, password string, claims map[string]any, err error) {
+	parts := strings.SplitN(spec, ":", 3)
+	if len(parts) < 2 || parts[0] == "" || parts[1] == "" {
+		return "", "", nil, fmt.Errorf("invalid -user %q: want email:password[:group1,group2]", spec)
+	}
+	email, password = parts[0], parts[1]
+	groups := []any{}
+	if len(parts) == 3 {
+		for _, g := range strings.Split(parts[2], ",") {
+			if g = strings.TrimSpace(g); g != "" {
+				groups = append(groups, g)
+			}
+		}
+	}
+	sum := sha256.Sum256([]byte(email))
+	claims = map[string]any{
+		"sub":            "sub-" + hex.EncodeToString(sum[:8]),
+		"email":          email,
+		"email_verified": true,
+		"name":           strings.SplitN(email, "@", 2)[0],
+		groupsClaim:      groups,
+	}
+	return email, password, claims, nil
+}
+
+func main() {
+	cfg, err := parseCLI(os.Args[1:], os.Stderr)
+	if err != nil {
+		if err == flag.ErrHelp {
+			os.Exit(0) // usage already printed
+		}
+		log.Fatalf("%v", err)
+	}
+	opts := cfg.Options
+
+	server := oauthserver.StartOnPort(nil, cfg.Port, opts)
 
 	fmt.Println("========================================")
-	fmt.Println("OAuth Test Server")
+	if opts.OIDC {
+		fmt.Println("OAuth Test Server (OpenID Provider mode)")
+	} else {
+		fmt.Println("OAuth Test Server")
+	}
 	fmt.Println("========================================")
-	fmt.Printf("Listening on:      http://localhost:%d\n", *port)
+	fmt.Printf("Listening on:      http://localhost:%d\n", cfg.Port)
 	fmt.Printf("Issuer:            %s\n", server.IssuerURL)
 	fmt.Println("")
 	fmt.Println("Endpoints:")
@@ -160,8 +361,15 @@ func main() {
 	}
 	fmt.Printf("  Token:           %s\n", server.TokenEndpoint)
 	fmt.Printf("  JWKS:            %s\n", server.JWKSURL)
+	dm := opts.DetectionMode
 	if dm == oauthserver.Discovery || dm == oauthserver.Both {
 		fmt.Printf("  Discovery:       %s/.well-known/oauth-authorization-server\n", server.IssuerURL)
+		if opts.OIDC {
+			fmt.Printf("  OIDC Discovery:  %s/.well-known/openid-configuration\n", server.IssuerURL)
+		}
+	}
+	if opts.OIDC {
+		fmt.Printf("  Userinfo:        %s\n", server.UserinfoEndpoint)
 	}
 	if dm == oauthserver.WWWAuthenticate || dm == oauthserver.Both {
 		fmt.Printf("  Protected:       %s/protected (for WWW-Authenticate detection)\n", server.IssuerURL)
@@ -182,9 +390,26 @@ func main() {
 	fmt.Printf("  PKCE Required:   %s (RFC 7636)\n", boolToEnabled(opts.RequirePKCE))
 	fmt.Printf("  Resource Req:    %s (RFC 8707)\n", boolToEnabled(opts.RequireResourceIndicator))
 	fmt.Printf("  Runlayer Mode:   %s (Pydantic 422 errors)\n", boolToEnabled(opts.RunlayerMode))
-	fmt.Printf("  Detection Mode:  %s\n", *detectionMode)
+	fmt.Printf("  Detection Mode:  %s\n", cfg.DetectionName)
+	fmt.Printf("  OIDC:            %s\n", boolToEnabled(opts.OIDC))
+	if opts.OIDC {
+		fmt.Printf("  Groups Claim:    %s\n", opts.GroupsClaim)
+		for _, uri := range opts.ClientRedirectURIs {
+			fmt.Printf("  Redirect URI:    %s\n", uri)
+		}
+		if tamper := describeTamper(opts.ErrorMode); tamper != "" {
+			fmt.Printf("  Tamper:          %s\n", tamper)
+		}
+	}
 	fmt.Println("")
-	fmt.Println("Test Credentials:  testuser / testpass")
+	if len(opts.ValidUsers) == 0 {
+		fmt.Println("Test Credentials:  testuser / testpass")
+	} else {
+		fmt.Println("Test Credentials (username / password / groups):")
+		for user, pass := range opts.ValidUsers {
+			fmt.Printf("  %s / %s / %v\n", user, pass, opts.UserClaims[user][opts.GroupsClaim])
+		}
+	}
 	fmt.Printf("Public Client ID:  %s\n", server.PublicClientID)
 	fmt.Printf("Confidential ID:   %s\n", server.ClientID)
 	fmt.Printf("Confidential Secret: %s\n", server.ClientSecret)
@@ -202,6 +427,29 @@ func main() {
 	log.Println("OAuth test server stopped")
 }
 
+// describeTamper names the active OIDC tamper knobs for the banner.
+func describeTamper(m oauthserver.ErrorMode) string {
+	var on []string
+	for name, set := range map[string]bool{
+		"IDTokenBadSignature": m.IDTokenBadSignature, "IDTokenWrongIssuer": m.IDTokenWrongIssuer,
+		"IDTokenWrongAudience": m.IDTokenWrongAudience, "IDTokenMultiAudNoAzp": m.IDTokenMultiAudNoAzp,
+		"IDTokenExpired": m.IDTokenExpired, "IDTokenNbfFuture": m.IDTokenNbfFuture,
+		"IDTokenNoNonce": m.IDTokenNoNonce, "IDTokenAlgNone": m.IDTokenAlgNone,
+		"IDTokenHS256": m.IDTokenHS256, "IDTokenUnknownKid": m.IDTokenUnknownKid,
+		"IDTokenKeyAlgMismatch": m.IDTokenKeyAlgMismatch, "EmailVerifiedFalse": m.EmailVerifiedFalse,
+		"GroupsNonArray": m.GroupsNonArray, "GroupsOverageMarker": m.GroupsOverageMarker,
+		"GroupsAbsentEverywhere": m.GroupsAbsentEverywhere, "UserinfoSubMismatch": m.UserinfoSubMismatch,
+		"UserinfoRedirect": m.UserinfoRedirect, "UserinfoNonJSON": m.UserinfoNonJSON,
+		"UserinfoUnavailable": m.UserinfoUnavailable, "DiscoveryHTTPTokenEndpoint": m.DiscoveryHTTPTokenEndpoint,
+		"TokenEndpointRedirect": m.TokenEndpointRedirect, "AuthAccessDenied": m.AuthAccessDenied,
+	} {
+		if set {
+			on = append(on, name)
+		}
+	}
+	return strings.Join(on, ", ")
+}
+
 func boolToEnabled(b bool) string {
 	if b {
 		return "enabled"
diff --git a/tests/oauthserver/cmd/server/main_test.go b/tests/oauthserver/cmd/server/main_test.go
new file mode 100644
index 000000000..879982f3c
--- /dev/null
+++ b/tests/oauthserver/cmd/server/main_test.go
@@ -0,0 +1,156 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/tests/oauthserver"
+)
+
+// Spec 107 T034a — parseFlags maps the standalone CLI onto oauthserver.Options.
+
+func TestParseFlags_Defaults(t *testing.T) {
+	opts, err := parseFlags(nil)
+	require.NoError(t, err)
+	assert.False(t, opts.OIDC)
+	assert.True(t, opts.EnableAuthCode)
+	assert.True(t, opts.EnableDeviceCode)
+	assert.True(t, opts.EnableDCR)
+	assert.True(t, opts.RequirePKCE)
+	assert.Equal(t, oauthserver.Both, opts.DetectionMode)
+	assert.Equal(t, oauthserver.ErrorMode{}, opts.ErrorMode)
+	assert.Empty(t, opts.ClientRedirectURIs)
+	assert.Empty(t, opts.UserClaims)
+	require.Len(t, opts.Clients, 1, "the Playwright test-client stays pre-registered")
+	assert.Equal(t, "test-client", opts.Clients[0].ClientID)
+}
+
+func TestParseFlags_OIDC(t *testing.T) {
+	opts, err := parseFlags([]string{
+		"-oidc",
+		"-user", "alice@example.com:pass:eng,sre",
+		"-user", "bob@example.com:pw:",
+		"-user", "carol@example.com:pw2",
+		"-redirect-uri", "http://127.0.0.1:18080/api/v1/auth/callback",
+		"-redirect-uri", "http://localhost:18080/api/v1/auth/callback",
+		"-groups-claim", "roles",
+	})
+	require.NoError(t, err)
+
+	assert.True(t, opts.OIDC)
+	assert.Equal(t, "roles", opts.GroupsClaim)
+	assert.Equal(t, []string{
+		"http://127.0.0.1:18080/api/v1/auth/callback",
+		"http://localhost:18080/api/v1/auth/callback",
+	}, opts.ClientRedirectURIs)
+
+	assert.Equal(t, map[string]string{
+		"alice@example.com": "pass",
+		"bob@example.com":   "pw",
+		"carol@example.com": "pw2",
+	}, opts.ValidUsers)
+
+	require.Contains(t, opts.UserClaims, "alice@example.com")
+	alice := opts.UserClaims["alice@example.com"]
+	assert.Equal(t, "alice@example.com", alice["email"])
+	assert.Equal(t, []any{"eng", "sre"}, alice["roles"], "groups land under the configured claim name")
+	assert.Equal(t, true, alice["email_verified"])
+	assert.NotEmpty(t, alice["sub"])
+	assert.NotEmpty(t, alice["name"])
+
+	assert.Equal(t, []any{}, opts.UserClaims["bob@example.com"]["roles"], "trailing ':' means no groups")
+	assert.Equal(t, []any{}, opts.UserClaims["carol@example.com"]["roles"], "omitted groups field means no groups")
+
+	// -redirect-uri also reaches the Playwright test-client.
+	require.Len(t, opts.Clients, 1)
+	assert.Contains(t, opts.Clients[0].RedirectURIs, "http://127.0.0.1:18080/api/v1/auth/callback")
+}
+
+func TestParseFlags_OIDCDefaultsGroupsClaim(t *testing.T) {
+	opts, err := parseFlags([]string{"-oidc", "-user", "alice@example.com:pass:eng"})
+	require.NoError(t, err)
+	assert.Equal(t, "groups", opts.GroupsClaim)
+	assert.Equal(t, []any{"eng"}, opts.UserClaims["alice@example.com"]["groups"])
+}
+
+func TestParseFlags_UserWithoutPasswordIsAnError(t *testing.T) {
+	_, err := parseFlags([]string{"-oidc", "-user", "alice@example.com"})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "-user")
+}
+
+func TestParseFlags_TamperFlags(t *testing.T) {
+	cases := []struct {
+		name string
+		args []string
+		want oauthserver.ErrorMode
+	}{
+		// existing knobs keep working
+		{"token invalid_client", []string{"-token-error", "invalid_client"}, oauthserver.ErrorMode{TokenInvalidClient: true}},
+		{"token invalid_grant", []string{"-token-error", "invalid_grant"}, oauthserver.ErrorMode{TokenInvalidGrant: true}},
+		{"token invalid_scope", []string{"-token-error", "invalid_scope"}, oauthserver.ErrorMode{TokenInvalidScope: true}},
+		{"token server_error", []string{"-token-error", "server_error"}, oauthserver.ErrorMode{TokenServerError: true}},
+		{"auth access_denied", []string{"-auth-error", "access_denied"}, oauthserver.ErrorMode{AuthAccessDenied: true}},
+		{"auth invalid_request", []string{"-auth-error", "invalid_request"}, oauthserver.ErrorMode{AuthInvalidRequest: true}},
+
+		// id_token knobs (research D2 / quickstart §1)
+		{"bad-signature", []string{"-oidc", "-token-error", "bad-signature"}, oauthserver.ErrorMode{IDTokenBadSignature: true}},
+		{"wrong-iss", []string{"-oidc", "-token-error", "wrong-iss"}, oauthserver.ErrorMode{IDTokenWrongIssuer: true}},
+		{"wrong-aud", []string{"-oidc", "-token-error", "wrong-aud"}, oauthserver.ErrorMode{IDTokenWrongAudience: true}},
+		{"multi-aud-no-azp", []string{"-oidc", "-token-error", "multi-aud-no-azp"}, oauthserver.ErrorMode{IDTokenMultiAudNoAzp: true}},
+		{"expired", []string{"-oidc", "-token-error", "expired"}, oauthserver.ErrorMode{IDTokenExpired: true}},
+		{"nbf-future", []string{"-oidc", "-token-error", "nbf-future"}, oauthserver.ErrorMode{IDTokenNbfFuture: true}},
+		{"no-nonce", []string{"-oidc", "-token-error", "no-nonce"}, oauthserver.ErrorMode{IDTokenNoNonce: true}},
+		{"alg-none", []string{"-oidc", "-token-error", "alg-none"}, oauthserver.ErrorMode{IDTokenAlgNone: true}},
+		{"hs256", []string{"-oidc", "-token-error", "hs256"}, oauthserver.ErrorMode{IDTokenHS256: true}},
+		{"unknown-kid", []string{"-oidc", "-token-error", "unknown-kid"}, oauthserver.ErrorMode{IDTokenUnknownKid: true}},
+		{"key-alg-mismatch", []string{"-oidc", "-token-error", "key-alg-mismatch"}, oauthserver.ErrorMode{IDTokenKeyAlgMismatch: true}},
+
+		// claims knobs
+		{"email-verified=false", []string{"-oidc", "-email-verified=false"}, oauthserver.ErrorMode{EmailVerifiedFalse: true}},
+		{"email-verified default", []string{"-oidc"}, oauthserver.ErrorMode{}},
+		{"groups non-array", []string{"-oidc", "-groups-error", "non-array"}, oauthserver.ErrorMode{GroupsNonArray: true}},
+		{"groups overage", []string{"-oidc", "-groups-error", "overage"}, oauthserver.ErrorMode{GroupsOverageMarker: true}},
+		{"groups absent", []string{"-oidc", "-groups-error", "absent"}, oauthserver.ErrorMode{GroupsAbsentEverywhere: true}},
+
+		// userinfo knobs
+		{"userinfo-sub-mismatch (quickstart alias)", []string{"-oidc", "-userinfo-sub-mismatch"}, oauthserver.ErrorMode{UserinfoSubMismatch: true}},
+		{"userinfo sub-mismatch", []string{"-oidc", "-userinfo-error", "sub-mismatch"}, oauthserver.ErrorMode{UserinfoSubMismatch: true}},
+		{"userinfo redirect", []string{"-oidc", "-userinfo-error", "redirect"}, oauthserver.ErrorMode{UserinfoRedirect: true}},
+		{"userinfo non-json", []string{"-oidc", "-userinfo-error", "non-json"}, oauthserver.ErrorMode{UserinfoNonJSON: true}},
+		{"userinfo unavailable", []string{"-oidc", "-userinfo-error", "unavailable"}, oauthserver.ErrorMode{UserinfoUnavailable: true}},
+
+		// hostile metadata / token endpoint
+		{"discovery-http-token-endpoint", []string{"-oidc", "-discovery-http-token-endpoint"}, oauthserver.ErrorMode{DiscoveryHTTPTokenEndpoint: true}},
+		{"token-endpoint-redirect", []string{"-oidc", "-token-endpoint-redirect"}, oauthserver.ErrorMode{TokenEndpointRedirect: true}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			opts, err := parseFlags(tc.args)
+			require.NoError(t, err)
+			assert.Equal(t, tc.want, opts.ErrorMode)
+		})
+	}
+}
+
+func TestParseFlags_UnknownTamperNameIsAnError(t *testing.T) {
+	for _, args := range [][]string{
+		{"-token-error", "bogus"},
+		{"-auth-error", "bogus"},
+		{"-oidc", "-groups-error", "bogus"},
+		{"-oidc", "-userinfo-error", "bogus"},
+		{"-detection", "bogus"},
+		{"-no-such-flag"},
+	} {
+		_, err := parseFlags(args)
+		assert.Error(t, err, "args=%v", args)
+	}
+}
+
+func TestParseFlags_IDTokenTamperRequiresOIDC(t *testing.T) {
+	_, err := parseFlags([]string{"-token-error", "bad-signature"})
+	require.Error(t, err, "an id_token knob without -oidc would silently do nothing")
+	assert.Contains(t, err.Error(), "-oidc")
+}
diff --git a/tests/oauthserver/discovery.go b/tests/oauthserver/discovery.go
index b7d57fe79..116d4d105 100644
--- a/tests/oauthserver/discovery.go
+++ b/tests/oauthserver/discovery.go
@@ -8,12 +8,12 @@ import (
 // buildDiscoveryMetadata constructs the OAuth 2.0 Authorization Server Metadata.
 func (s *OAuthTestServer) buildDiscoveryMetadata() *DiscoveryMetadata {
 	metadata := &DiscoveryMetadata{
-		Issuer:                s.issuerURL,
-		AuthorizationEndpoint: s.issuerURL + "/authorize",
-		TokenEndpoint:         s.issuerURL + "/token",
-		JWKSURI:               s.issuerURL + "/jwks.json",
-		ScopesSupported:       s.options.SupportedScopes,
-		ResponseTypesSupported: []string{"code"},
+		Issuer:                        s.issuerURL,
+		AuthorizationEndpoint:         s.issuerURL + "/authorize",
+		TokenEndpoint:                 s.issuerURL + "/token",
+		JWKSURI:                       s.issuerURL + "/jwks.json",
+		ScopesSupported:               s.options.SupportedScopes,
+		ResponseTypesSupported:        []string{"code"},
 		CodeChallengeMethodsSupported: []string{"S256"},
 		TokenEndpointAuthMethodsSupported: []string{
 			"client_secret_basic",
@@ -46,6 +46,22 @@ func (s *OAuthTestServer) buildDiscoveryMetadata() *DiscoveryMetadata {
 		metadata.DeviceAuthorizationEndpoint = s.issuerURL + "/device_authorization"
 	}
 
+	// OpenID Provider Metadata (Options.OIDC): the same document is served on
+	// /.well-known/openid-configuration.
+	if s.options.OIDC {
+		metadata.UserinfoEndpoint = s.issuerURL + "/userinfo"
+		metadata.IDTokenSigningAlgValuesSupported = []string{"RS256"}
+		metadata.SubjectTypesSupported = []string{"public"}
+		metadata.ClaimsSupported = []string{"sub", "iss", "aud", "exp", "iat", "nonce", "email", "email_verified", "name", s.options.GroupsClaim}
+
+		// FR-020 hostile-metadata knob: a plain-http token endpoint on a
+		// non-loopback host (loopback http is legitimately allowed under
+		// allow_insecure_issuer, so the fake's own origin would not do).
+		if s.errorMode().DiscoveryHTTPTokenEndpoint {
+			metadata.TokenEndpoint = "http://idp.invalid/token"
+		}
+	}
+
 	return metadata
 }
 
@@ -70,9 +86,9 @@ func (s *OAuthTestServer) handleDiscovery(w http.ResponseWriter, r *http.Request
 // buildProtectedResourceMetadata constructs RFC 9728 Protected Resource Metadata.
 func (s *OAuthTestServer) buildProtectedResourceMetadata() *ProtectedResourceMetadata {
 	return &ProtectedResourceMetadata{
-		Resource:              s.issuerURL + "/mcp",
-		AuthorizationServers:  []string{s.issuerURL},
-		ScopesSupported:       s.options.SupportedScopes,
+		Resource:               s.issuerURL + "/mcp",
+		AuthorizationServers:   []string{s.issuerURL},
+		ScopesSupported:        s.options.SupportedScopes,
 		BearerMethodsSupported: []string{"header"},
 	}
 }
diff --git a/tests/oauthserver/jwks.go b/tests/oauthserver/jwks.go
index 53ffcd705..3920b7be2 100644
--- a/tests/oauthserver/jwks.go
+++ b/tests/oauthserver/jwks.go
@@ -1,6 +1,8 @@
 package oauthserver
 
 import (
+	"crypto/ecdsa"
+	"crypto/elliptic"
 	"crypto/rand"
 	"crypto/rsa"
 	"encoding/base64"
@@ -12,20 +14,28 @@ import (
 )
 
 // KeyRing manages RSA key pairs for JWT signing with rotation support.
+// With Options.OIDC it also holds EC (P-256) keys, published in the JWKS and
+// used only by the IDTokenKeyAlgMismatch tamper knob and by tests that mint
+// their own tokens; access tokens and id_tokens are always RS256.
 type KeyRing struct {
 	keys      map[string]*rsa.PrivateKey
+	ecKeys    map[string]*ecdsa.PrivateKey
+	ecKids    []string // insertion order, so GetJWKS is deterministic
 	activeKid string
 	mu        sync.RWMutex
 }
 
-// JWK represents a JSON Web Key.
+// JWK represents a JSON Web Key (RSA: n,e; EC: crv,x,y).
 type JWK struct {
 	Kty string `json:"kty"`
 	Use string `json:"use"`
 	Kid string `json:"kid"`
 	Alg string `json:"alg"`
-	N   string `json:"n"`
-	E   string `json:"e"`
+	N   string `json:"n,omitempty"`
+	E   string `json:"e,omitempty"`
+	Crv string `json:"crv,omitempty"`
+	X   string `json:"x,omitempty"`
+	Y   string `json:"y,omitempty"`
 }
 
 // JWKS represents a JSON Web Key Set.
@@ -36,7 +46,8 @@ type JWKS struct {
 // NewKeyRing creates a new KeyRing with an initial RSA key.
 func NewKeyRing() (*KeyRing, error) {
 	kr := &KeyRing{
-		keys: make(map[string]*rsa.PrivateKey),
+		keys:   make(map[string]*rsa.PrivateKey),
+		ecKeys: make(map[string]*ecdsa.PrivateKey),
 	}
 
 	// Generate initial key
@@ -135,13 +146,39 @@ func (kr *KeyRing) GetKey(kid string) (*rsa.PrivateKey, bool) {
 	return key, exists
 }
 
-// GetJWKS returns the public keys in JWK Set format.
+// AddECKey generates a P-256 key, adds it to the ring and returns its ID.
+// The RSA signing key stays active; the EC key is only published.
+func (kr *KeyRing) AddECKey() (string, error) {
+	kr.mu.Lock()
+	defer kr.mu.Unlock()
+
+	kid := fmt.Sprintf("ec-%d", len(kr.ecKeys)+1)
+	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		return "", fmt.Errorf("failed to generate EC key: %w", err)
+	}
+	kr.ecKeys[kid] = key
+	kr.ecKids = append(kr.ecKids, kid)
+	return kid, nil
+}
+
+// GetECKey returns the first EC key and its ID, or ("", nil) when none exists.
+func (kr *KeyRing) GetECKey() (string, *ecdsa.PrivateKey) {
+	kr.mu.RLock()
+	defer kr.mu.RUnlock()
+	if len(kr.ecKids) == 0 {
+		return "", nil
+	}
+	return kr.ecKids[0], kr.ecKeys[kr.ecKids[0]]
+}
+
+// GetJWKS returns the public keys in JWK Set format (RSA keys first, then EC).
 func (kr *KeyRing) GetJWKS() *JWKS {
 	kr.mu.RLock()
 	defer kr.mu.RUnlock()
 
 	jwks := &JWKS{
-		Keys: make([]JWK, 0, len(kr.keys)),
+		Keys: make([]JWK, 0, len(kr.keys)+len(kr.ecKeys)),
 	}
 
 	for kid, key := range kr.keys {
@@ -156,6 +193,20 @@ func (kr *KeyRing) GetJWKS() *JWKS {
 		jwks.Keys = append(jwks.Keys, jwk)
 	}
 
+	for _, kid := range kr.ecKids {
+		pub := kr.ecKeys[kid].PublicKey
+		size := (pub.Curve.Params().BitSize + 7) / 8
+		jwks.Keys = append(jwks.Keys, JWK{
+			Kty: "EC",
+			Use: "sig",
+			Kid: kid,
+			Alg: "ES256",
+			Crv: "P-256",
+			X:   base64.RawURLEncoding.EncodeToString(pub.X.FillBytes(make([]byte, size))),
+			Y:   base64.RawURLEncoding.EncodeToString(pub.Y.FillBytes(make([]byte, size))),
+		})
+	}
+
 	return jwks
 }
 
diff --git a/tests/oauthserver/oidc_test.go b/tests/oauthserver/oidc_test.go
new file mode 100644
index 000000000..93c021c5c
--- /dev/null
+++ b/tests/oauthserver/oidc_test.go
@@ -0,0 +1,675 @@
+package oauthserver
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"io"
+	"math/big"
+	"net/http"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// Spec 107 T032 — the fake OIDC IdP (research D2). Every ErrorMode tamper
+// knob has its own sub-test so an unimplemented knob is a named failure.
+
+const (
+	oidcUser        = "alice@example.com"
+	oidcPass        = "pass"
+	oidcRedirectURI = "http://127.0.0.1/api/v1/auth/callback"
+)
+
+var oidcAliceClaims = map[string]any{
+	"sub":            "alice-sub-1",
+	"email":          "alice@example.com",
+	"email_verified": true,
+	"name":           "Alice Example",
+	"groups":         []any{"eng", "sre"},
+}
+
+type oidcRig struct {
+	t      *testing.T
+	srv    *ServerResult
+	client *http.Client // never follows redirects
+}
+
+func oidcOptions(mode ErrorMode) Options {
+	return Options{
+		OIDC:               true,
+		ValidUsers:         map[string]string{oidcUser: oidcPass},
+		UserClaims:         map[string]map[string]any{oidcUser: oidcAliceClaims},
+		ClientRedirectURIs: []string{oidcRedirectURI},
+		GroupsClaim:        "groups",
+		ErrorMode:          mode,
+	}
+}
+
+func startOIDC(t *testing.T, mode ErrorMode) *oidcRig {
+	t.Helper()
+	srv := Start(t, oidcOptions(mode))
+	t.Cleanup(func() { _ = srv.Shutdown() })
+	return &oidcRig{
+		t:   t,
+		srv: srv,
+		client: &http.Client{
+			Timeout: 5 * time.Second,
+			CheckRedirect: func(*http.Request, []*http.Request) error {
+				return http.ErrUseLastResponse
+			},
+		},
+	}
+}
+
+func (r *oidcRig) discovery() map[string]any {
+	r.t.Helper()
+	resp, err := r.client.Get(r.srv.IssuerURL + "/.well-known/openid-configuration")
+	require.NoError(r.t, err)
+	defer resp.Body.Close()
+	require.Equal(r.t, http.StatusOK, resp.StatusCode)
+	var doc map[string]any
+	require.NoError(r.t, json.NewDecoder(resp.Body).Decode(&doc))
+	return doc
+}
+
+func (r *oidcRig) jwks() JWKS {
+	r.t.Helper()
+	resp, err := r.client.Get(r.srv.JWKSURL)
+	require.NoError(r.t, err)
+	defer resp.Body.Close()
+	var set JWKS
+	require.NoError(r.t, json.NewDecoder(resp.Body).Decode(&set))
+	return set
+}
+
+func pkcePair() (verifier, challenge string) {
+	b := make([]byte, 32)
+	_, _ = rand.Read(b)
+	verifier = base64.RawURLEncoding.EncodeToString(b)
+	h := sha256.Sum256([]byte(verifier))
+	return verifier, base64.RawURLEncoding.EncodeToString(h[:])
+}
+
+func (r *oidcRig) authorizeQuery(nonce, challenge string) url.Values {
+	q := url.Values{}
+	q.Set("response_type", "code")
+	q.Set("client_id", r.srv.ClientID)
+	q.Set("redirect_uri", oidcRedirectURI)
+	q.Set("scope", "openid profile email groups")
+	q.Set("state", "st-123")
+	q.Set("nonce", nonce)
+	q.Set("code_challenge", challenge)
+	q.Set("code_challenge_method", "S256")
+	return q
+}
+
+// authorizeGET renders the login page (200) or redirects with an error.
+func (r *oidcRig) authorizeGET(nonce, challenge string) *http.Response {
+	r.t.Helper()
+	resp, err := r.client.Get(r.srv.AuthorizationEndpoint + "?" + r.authorizeQuery(nonce, challenge).Encode())
+	require.NoError(r.t, err)
+	_, _ = io.Copy(io.Discard, resp.Body)
+	resp.Body.Close()
+	return resp
+}
+
+// authorizePOST submits the headless login form and returns the redirect Location.
+func (r *oidcRig) authorizePOST(nonce, challenge string) *url.URL {
+	r.t.Helper()
+	form := r.authorizeQuery(nonce, challenge)
+	form.Set("username", oidcUser)
+	form.Set("password", oidcPass)
+	form.Set("consent", "on")
+	form.Set("action", "approve")
+	resp, err := r.client.PostForm(r.srv.AuthorizationEndpoint, form)
+	require.NoError(r.t, err)
+	_, _ = io.Copy(io.Discard, resp.Body)
+	resp.Body.Close()
+	require.Equal(r.t, http.StatusFound, resp.StatusCode)
+	loc, err := url.Parse(resp.Header.Get("Location"))
+	require.NoError(r.t, err)
+	return loc
+}
+
+func (r *oidcRig) exchangeRaw(code, verifier string) *http.Response {
+	r.t.Helper()
+	form := url.Values{}
+	form.Set("grant_type", "authorization_code")
+	form.Set("code", code)
+	form.Set("redirect_uri", oidcRedirectURI)
+	form.Set("code_verifier", verifier)
+	req, err := http.NewRequest(http.MethodPost, r.srv.TokenEndpoint, strings.NewReader(form.Encode()))
+	require.NoError(r.t, err)
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.SetBasicAuth(r.srv.ClientID, r.srv.ClientSecret)
+	resp, err := r.client.Do(req)
+	require.NoError(r.t, err)
+	return resp
+}
+
+// login drives GET /authorize → POST /authorize → POST /token and returns the token response.
+func (r *oidcRig) login(nonce string) map[string]any {
+	r.t.Helper()
+	verifier, challenge := pkcePair()
+	require.Equal(r.t, http.StatusOK, r.authorizeGET(nonce, challenge).StatusCode, "redirect_uri from ClientRedirectURIs must be accepted")
+	loc := r.authorizePOST(nonce, challenge)
+	require.Equal(r.t, "st-123", loc.Query().Get("state"))
+	code := loc.Query().Get("code")
+	require.NotEmpty(r.t, code, "location=%s", loc)
+	resp := r.exchangeRaw(code, verifier)
+	defer resp.Body.Close()
+	require.Equal(r.t, http.StatusOK, resp.StatusCode)
+	var body map[string]any
+	require.NoError(r.t, json.NewDecoder(resp.Body).Decode(&body))
+	return body
+}
+
+func (r *oidcRig) userinfo(accessToken string) *http.Response {
+	r.t.Helper()
+	req, err := http.NewRequest(http.MethodGet, r.srv.IssuerURL+"/userinfo", nil)
+	require.NoError(r.t, err)
+	req.Header.Set("Authorization", "Bearer "+accessToken)
+	resp, err := r.client.Do(req)
+	require.NoError(r.t, err)
+	return resp
+}
+
+func (r *oidcRig) userinfoJSON(accessToken string) map[string]any {
+	r.t.Helper()
+	resp := r.userinfo(accessToken)
+	defer resp.Body.Close()
+	require.Equal(r.t, http.StatusOK, resp.StatusCode)
+	var body map[string]any
+	require.NoError(r.t, json.NewDecoder(resp.Body).Decode(&body))
+	return body
+}
+
+func idTokenOf(t *testing.T, tok map[string]any) string {
+	t.Helper()
+	raw, _ := tok["id_token"].(string)
+	require.NotEmpty(t, raw, "token response must carry id_token: %v", tok)
+	return raw
+}
+
+// decodeJWT splits a compact JWS without verifying it.
+func decodeJWT(t *testing.T, raw string) (header, claims map[string]any, sig string) {
+	t.Helper()
+	parts := strings.Split(raw, ".")
+	require.Len(t, parts, 3, "compact JWS must have three parts: %q", raw)
+	hb, err := base64.RawURLEncoding.DecodeString(parts[0])
+	require.NoError(t, err)
+	cb, err := base64.RawURLEncoding.DecodeString(parts[1])
+	require.NoError(t, err)
+	require.NoError(t, json.Unmarshal(hb, &header))
+	require.NoError(t, json.Unmarshal(cb, &claims))
+	return header, claims, parts[2]
+}
+
+// verifyAgainstJWKS verifies an RS256 token against the published JWKS by kid.
+func (r *oidcRig) verifyAgainstJWKS(raw string) error {
+	set := r.jwks()
+	_, err := jwt.NewParser(jwt.WithoutClaimsValidation(), jwt.WithValidMethods([]string{"RS256"})).
+		Parse(raw, func(tok *jwt.Token) (any, error) {
+			kid, _ := tok.Header["kid"].(string)
+			for _, k := range set.Keys {
+				if k.Kid == kid && k.Kty == "RSA" {
+					return jwkToRSAPublic(k)
+				}
+			}
+			return nil, errors.New("kid not in JWKS")
+		})
+	return err
+}
+
+func jwkKty(set JWKS, kid string) string {
+	for _, k := range set.Keys {
+		if k.Kid == kid {
+			return k.Kty
+		}
+	}
+	return ""
+}
+
+func TestOIDC_HappyPath(t *testing.T) {
+	r := startOIDC(t, ErrorMode{})
+
+	t.Run("discovery", func(t *testing.T) {
+		doc := r.discovery()
+		assert.Equal(t, r.srv.IssuerURL+"/userinfo", doc["userinfo_endpoint"])
+		assert.Contains(t, doc["id_token_signing_alg_values_supported"], "RS256")
+		assert.Equal(t, r.srv.IssuerURL, doc["issuer"])
+		assert.Equal(t, r.srv.JWKSURL, doc["jwks_uri"])
+		assert.Contains(t, doc["scopes_supported"], "openid")
+	})
+
+	t.Run("jwks has RSA and EC keys", func(t *testing.T) {
+		set := r.jwks()
+		var kty []string
+		for _, k := range set.Keys {
+			kty = append(kty, k.Kty)
+			assert.NotEmpty(t, k.Kid)
+			if k.Kty == "EC" {
+				assert.Equal(t, "P-256", k.Crv)
+				assert.NotEmpty(t, k.X)
+				assert.NotEmpty(t, k.Y)
+				assert.Equal(t, "ES256", k.Alg)
+			}
+		}
+		assert.Contains(t, kty, "RSA")
+		assert.Contains(t, kty, "EC")
+	})
+
+	tok := r.login("nonce-abc")
+	assert.Equal(t, "Bearer", tok["token_type"])
+	raw := idTokenOf(t, tok)
+	header, claims, _ := decodeJWT(t, raw)
+
+	t.Run("id_token is RS256 by a JWKS key", func(t *testing.T) {
+		assert.Equal(t, "RS256", header["alg"])
+		assert.Equal(t, r.srv.Server.KeyRing().GetActiveKid(), header["kid"])
+		require.NoError(t, r.verifyAgainstJWKS(raw))
+	})
+
+	t.Run("id_token claims match UserClaims", func(t *testing.T) {
+		assert.Equal(t, r.srv.IssuerURL, claims["iss"])
+		assert.Equal(t, "alice-sub-1", claims["sub"])
+		assert.Equal(t, r.srv.ClientID, claims["aud"])
+		assert.Equal(t, r.srv.ClientID, claims["azp"])
+		assert.Equal(t, "nonce-abc", claims["nonce"])
+		assert.Equal(t, "alice@example.com", claims["email"])
+		assert.Equal(t, true, claims["email_verified"])
+		assert.Equal(t, "Alice Example", claims["name"])
+		assert.Equal(t, []any{"eng", "sre"}, claims["groups"])
+		exp, _ := claims["exp"].(float64)
+		iat, _ := claims["iat"].(float64)
+		assert.Greater(t, exp, float64(time.Now().Unix()))
+		assert.LessOrEqual(t, iat, float64(time.Now().Unix()))
+	})
+
+	t.Run("userinfo returns the same claims", func(t *testing.T) {
+		ui := r.userinfoJSON(tok["access_token"].(string))
+		assert.Equal(t, "alice-sub-1", ui["sub"])
+		assert.Equal(t, "alice@example.com", ui["email"])
+		assert.Equal(t, true, ui["email_verified"])
+		assert.Equal(t, "Alice Example", ui["name"])
+		assert.Equal(t, []any{"eng", "sre"}, ui["groups"])
+	})
+
+	t.Run("userinfo rejects a bad token", func(t *testing.T) {
+		resp := r.userinfo("not-a-token")
+		resp.Body.Close()
+		assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
+		assert.Contains(t, resp.Header.Get("WWW-Authenticate"), "Bearer")
+	})
+
+	t.Run("kid rotation", func(t *testing.T) {
+		oldKid := header["kid"].(string)
+		newKid, err := r.srv.Server.KeyRing().RotateKey()
+		require.NoError(t, err)
+		require.NotEqual(t, oldKid, newKid)
+		h2, _, _ := decodeJWT(t, idTokenOf(t, r.login("nonce-2")))
+		assert.Equal(t, newKid, h2["kid"])
+		set := r.jwks()
+		assert.Equal(t, "RSA", jwkKty(set, oldKid), "old kid stays published for verification")
+		assert.Equal(t, "RSA", jwkKty(set, newKid))
+		require.NoError(t, r.verifyAgainstJWKS(raw), "token under the old kid still verifies")
+	})
+}
+
+// TestOIDC_DefaultClaims: a ValidUsers entry without UserClaims still yields
+// a usable identity (sub/email/name derived, email_verified true, no groups).
+func TestOIDC_DefaultClaims(t *testing.T) {
+	srv := Start(t, Options{OIDC: true, ClientRedirectURIs: []string{oidcRedirectURI}})
+	t.Cleanup(func() { _ = srv.Shutdown() })
+	r := &oidcRig{t: t, srv: srv, client: &http.Client{CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}}
+	// default ValidUsers = testuser/testpass; log in as that user
+	verifier, challenge := pkcePair()
+	form := r.authorizeQuery("n", challenge)
+	form.Set("username", "testuser")
+	form.Set("password", "testpass")
+	form.Set("consent", "on")
+	form.Set("action", "approve")
+	resp, err := r.client.PostForm(srv.AuthorizationEndpoint, form)
+	require.NoError(t, err)
+	resp.Body.Close()
+	loc, _ := url.Parse(resp.Header.Get("Location"))
+	tr := r.exchangeRaw(loc.Query().Get("code"), verifier)
+	defer tr.Body.Close()
+	var body map[string]any
+	require.NoError(t, json.NewDecoder(tr.Body).Decode(&body))
+	_, claims, _ := decodeJWT(t, idTokenOf(t, body))
+	assert.NotEmpty(t, claims["sub"])
+	assert.Equal(t, "testuser@example.com", claims["email"])
+	assert.Equal(t, true, claims["email_verified"])
+	assert.NotEmpty(t, claims["name"])
+	assert.Equal(t, "n", claims["nonce"])
+	assert.Equal(t, []any{}, claims["groups"])
+}
+
+func TestOIDC_ErrorModeKnobs(t *testing.T) {
+	now := func() float64 { return float64(time.Now().Unix()) }
+
+	t.Run("IDTokenBadSignature", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{IDTokenBadSignature: true})
+		raw := idTokenOf(t, r.login("n"))
+		header, _, _ := decodeJWT(t, raw)
+		assert.Equal(t, "RS256", header["alg"])
+		assert.Equal(t, "RSA", jwkKty(r.jwks(), header["kid"].(string)), "kid still resolves to a published key")
+		assert.Error(t, r.verifyAgainstJWKS(raw))
+	})
+
+	t.Run("IDTokenWrongIssuer", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{IDTokenWrongIssuer: true})
+		raw := idTokenOf(t, r.login("n"))
+		_, claims, _ := decodeJWT(t, raw)
+		assert.NotEqual(t, r.srv.IssuerURL, claims["iss"])
+		assert.NotEmpty(t, claims["iss"])
+		assert.NoError(t, r.verifyAgainstJWKS(raw), "only the claim is wrong")
+	})
+
+	t.Run("IDTokenWrongAudience", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{IDTokenWrongAudience: true})
+		raw := idTokenOf(t, r.login("n"))
+		_, claims, _ := decodeJWT(t, raw)
+		assert.NotEqual(t, r.srv.ClientID, claims["aud"])
+		assert.NotContains(t, []any{claims["aud"]}, r.srv.ClientID)
+		assert.NoError(t, r.verifyAgainstJWKS(raw))
+	})
+
+	t.Run("IDTokenMultiAudNoAzp", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{IDTokenMultiAudNoAzp: true})
+		raw := idTokenOf(t, r.login("n"))
+		_, claims, _ := decodeJWT(t, raw)
+		aud, ok := claims["aud"].([]any)
+		require.True(t, ok, "aud must be an array: %v", claims["aud"])
+		assert.GreaterOrEqual(t, len(aud), 2)
+		assert.Contains(t, aud, r.srv.ClientID)
+		_, hasAzp := claims["azp"]
+		assert.False(t, hasAzp, "azp must be absent")
+		assert.NoError(t, r.verifyAgainstJWKS(raw))
+	})
+
+	t.Run("IDTokenExpired", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{IDTokenExpired: true})
+		raw := idTokenOf(t, r.login("n"))
+		_, claims, _ := decodeJWT(t, raw)
+		exp, _ := claims["exp"].(float64)
+		assert.Less(t, exp, now()-120, "exp must be past the 60 s leeway")
+		assert.NoError(t, r.verifyAgainstJWKS(raw))
+	})
+
+	t.Run("IDTokenNbfFuture", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{IDTokenNbfFuture: true})
+		raw := idTokenOf(t, r.login("n"))
+		_, claims, _ := decodeJWT(t, raw)
+		nbf, _ := claims["nbf"].(float64)
+		assert.Greater(t, nbf, now()+120, "nbf must be past the 60 s leeway")
+		exp, _ := claims["exp"].(float64)
+		assert.Greater(t, exp, nbf)
+		assert.NoError(t, r.verifyAgainstJWKS(raw))
+	})
+
+	t.Run("IDTokenNoNonce", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{IDTokenNoNonce: true})
+		raw := idTokenOf(t, r.login("n"))
+		_, claims, _ := decodeJWT(t, raw)
+		_, has := claims["nonce"]
+		assert.False(t, has, "nonce must be absent")
+		assert.NoError(t, r.verifyAgainstJWKS(raw))
+	})
+
+	t.Run("IDTokenAlgNone", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{IDTokenAlgNone: true})
+		raw := idTokenOf(t, r.login("n"))
+		header, claims, sig := decodeJWT(t, raw)
+		assert.Equal(t, "none", header["alg"])
+		assert.Empty(t, sig)
+		assert.Equal(t, "n", claims["nonce"])
+		assert.Error(t, r.verifyAgainstJWKS(raw))
+	})
+
+	t.Run("IDTokenHS256", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{IDTokenHS256: true})
+		raw := idTokenOf(t, r.login("n"))
+		header, _, sig := decodeJWT(t, raw)
+		assert.Equal(t, "HS256", header["alg"])
+		assert.NotEmpty(t, sig)
+		assert.Error(t, r.verifyAgainstJWKS(raw))
+	})
+
+	t.Run("IDTokenUnknownKid", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{IDTokenUnknownKid: true})
+		raw := idTokenOf(t, r.login("n"))
+		header, _, _ := decodeJWT(t, raw)
+		kid, _ := header["kid"].(string)
+		assert.NotEmpty(t, kid)
+		assert.Equal(t, "", jwkKty(r.jwks(), kid), "kid must not be in the JWKS")
+		assert.Equal(t, "RS256", header["alg"])
+	})
+
+	t.Run("IDTokenKeyAlgMismatch", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{IDTokenKeyAlgMismatch: true})
+		raw := idTokenOf(t, r.login("n"))
+		header, _, _ := decodeJWT(t, raw)
+		assert.Equal(t, "ES256", header["alg"])
+		kid, _ := header["kid"].(string)
+		assert.Equal(t, "RSA", jwkKty(r.jwks(), kid), "header names an RSA kid with an EC alg")
+	})
+
+	t.Run("EmailVerifiedFalse", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{EmailVerifiedFalse: true})
+		tok := r.login("n")
+		_, claims, _ := decodeJWT(t, idTokenOf(t, tok))
+		assert.Equal(t, false, claims["email_verified"])
+		ui := r.userinfoJSON(tok["access_token"].(string))
+		assert.Equal(t, false, ui["email_verified"])
+	})
+
+	t.Run("GroupsNonArray", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{GroupsNonArray: true})
+		tok := r.login("n")
+		_, claims, _ := decodeJWT(t, idTokenOf(t, tok))
+		_, isStr := claims["groups"].(string)
+		assert.True(t, isStr, "groups must be a non-array: %v", claims["groups"])
+		ui := r.userinfoJSON(tok["access_token"].(string))
+		_, isStr = ui["groups"].(string)
+		assert.True(t, isStr)
+	})
+
+	t.Run("GroupsOverageMarker", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{GroupsOverageMarker: true})
+		tok := r.login("n")
+		_, claims, _ := decodeJWT(t, idTokenOf(t, tok))
+		_, has := claims["groups"]
+		assert.False(t, has, "groups absent when overage marker set")
+		names, _ := claims["_claim_names"].(map[string]any)
+		assert.Contains(t, names, "groups")
+		_, hasSrc := claims["_claim_sources"]
+		assert.True(t, hasSrc)
+		ui := r.userinfoJSON(tok["access_token"].(string))
+		_, has = ui["groups"]
+		assert.False(t, has)
+		uiNames, _ := ui["_claim_names"].(map[string]any)
+		assert.Contains(t, uiNames, "groups")
+	})
+
+	t.Run("GroupsAbsentEverywhere", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{GroupsAbsentEverywhere: true})
+		tok := r.login("n")
+		_, claims, _ := decodeJWT(t, idTokenOf(t, tok))
+		_, has := claims["groups"]
+		assert.False(t, has)
+		ui := r.userinfoJSON(tok["access_token"].(string))
+		_, has = ui["groups"]
+		assert.False(t, has)
+		assert.Equal(t, claims["sub"], ui["sub"])
+	})
+
+	t.Run("UserinfoSubMismatch", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{UserinfoSubMismatch: true})
+		tok := r.login("n")
+		_, claims, _ := decodeJWT(t, idTokenOf(t, tok))
+		_, has := claims["groups"]
+		assert.False(t, has, "token must lack groups so the verifier consults userinfo")
+		ui := r.userinfoJSON(tok["access_token"].(string))
+		assert.NotEqual(t, claims["sub"], ui["sub"])
+		assert.NotEmpty(t, ui["sub"])
+		assert.Equal(t, []any{"eng", "sre"}, ui["groups"])
+	})
+
+	t.Run("UserinfoRedirect", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{UserinfoRedirect: true})
+		tok := r.login("n")
+		_, claims, _ := decodeJWT(t, idTokenOf(t, tok))
+		_, has := claims["groups"]
+		assert.False(t, has)
+		resp := r.userinfo(tok["access_token"].(string))
+		resp.Body.Close()
+		assert.Equal(t, http.StatusFound, resp.StatusCode)
+		loc, err := url.Parse(resp.Header.Get("Location"))
+		require.NoError(t, err)
+		assert.True(t, loc.IsAbs())
+		assert.NotEqual(t, r.srv.Server.addr, loc.Host, "redirect must leave the issuer origin")
+	})
+
+	t.Run("UserinfoNonJSON", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{UserinfoNonJSON: true})
+		tok := r.login("n")
+		_, claims, _ := decodeJWT(t, idTokenOf(t, tok))
+		_, has := claims["groups"]
+		assert.False(t, has)
+		resp := r.userinfo(tok["access_token"].(string))
+		body, _ := io.ReadAll(resp.Body)
+		resp.Body.Close()
+		assert.Equal(t, http.StatusOK, resp.StatusCode)
+		assert.NotContains(t, resp.Header.Get("Content-Type"), "json")
+		var any map[string]any
+		assert.Error(t, json.Unmarshal(body, &any), "body must not be JSON: %s", body)
+	})
+
+	t.Run("UserinfoUnavailable", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{UserinfoUnavailable: true})
+		tok := r.login("n")
+		_, claims, _ := decodeJWT(t, idTokenOf(t, tok))
+		_, has := claims["groups"]
+		assert.False(t, has)
+		resp := r.userinfo(tok["access_token"].(string))
+		resp.Body.Close()
+		assert.Equal(t, http.StatusServiceUnavailable, resp.StatusCode)
+	})
+
+	t.Run("DiscoveryHTTPTokenEndpoint", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{DiscoveryHTTPTokenEndpoint: true})
+		doc := r.discovery()
+		te, _ := doc["token_endpoint"].(string)
+		u, err := url.Parse(te)
+		require.NoError(t, err, te)
+		assert.Equal(t, "http", u.Scheme)
+		assert.NotContains(t, []string{"127.0.0.1", "localhost", "::1"}, u.Hostname(), "must not be loopback (loopback http is allowed by allow_insecure_issuer)")
+		assert.NotEqual(t, r.srv.Server.addr, u.Host)
+	})
+
+	t.Run("TokenEndpointRedirect", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{TokenEndpointRedirect: true})
+		verifier, challenge := pkcePair()
+		loc := r.authorizePOST("n", challenge)
+		resp := r.exchangeRaw(loc.Query().Get("code"), verifier)
+		resp.Body.Close()
+		assert.Equal(t, http.StatusFound, resp.StatusCode)
+		target, err := url.Parse(resp.Header.Get("Location"))
+		require.NoError(t, err)
+		assert.True(t, target.IsAbs())
+		assert.NotEqual(t, r.srv.Server.addr, target.Host, "redirect must leave the issuer origin")
+	})
+
+	t.Run("AuthAccessDenied", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{AuthAccessDenied: true})
+		_, challenge := pkcePair()
+		resp := r.authorizeGET("n", challenge)
+		assert.Equal(t, http.StatusFound, resp.StatusCode)
+		loc, err := url.Parse(resp.Header.Get("Location"))
+		require.NoError(t, err)
+		assert.Equal(t, "access_denied", loc.Query().Get("error"))
+		assert.Equal(t, "st-123", loc.Query().Get("state"))
+	})
+
+	// A real IdP decides an injected authorization-time error at the
+	// authorization request, before any login form is shown, so it must
+	// apply the same way to a caller that POSTs straight to the authorize
+	// endpoint (simulating the form submission) without ever GETting it
+	// first — scripts/dev-server-edition.sh's headless_login does exactly
+	// that. Before this fix, handleAuthorizePOST never checked
+	// ErrorMode.AuthAccessDenied/AuthInvalidRequest at all, so a POST-only
+	// caller silently bypassed both knobs (cross-review round 6, chunk 4 P3).
+	t.Run("AuthAccessDenied on a POST-only caller (no preceding GET)", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{AuthAccessDenied: true})
+		_, challenge := pkcePair()
+		loc := r.authorizePOST("n", challenge)
+		assert.Equal(t, "access_denied", loc.Query().Get("error"))
+		assert.Equal(t, "st-123", loc.Query().Get("state"))
+	})
+
+	t.Run("AuthInvalidRequest on a POST-only caller (no preceding GET)", func(t *testing.T) {
+		r := startOIDC(t, ErrorMode{AuthInvalidRequest: true})
+		_, challenge := pkcePair()
+		loc := r.authorizePOST("n", challenge)
+		assert.Equal(t, "invalid_request", loc.Query().Get("error"))
+		assert.Equal(t, "st-123", loc.Query().Get("state"))
+	})
+}
+
+// TestOIDC_ExistingBehaviourUntouched: with OIDC off nothing changes — no
+// id_token, no userinfo route, no EC key in the JWKS.
+func TestOIDC_ExistingBehaviourUntouched(t *testing.T) {
+	srv := Start(t, Options{})
+	t.Cleanup(func() { _ = srv.Shutdown() })
+	resp, err := http.Get(srv.IssuerURL + "/.well-known/openid-configuration")
+	require.NoError(t, err)
+	var doc map[string]any
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&doc))
+	resp.Body.Close()
+	_, has := doc["userinfo_endpoint"]
+	assert.False(t, has)
+	_, has = doc["id_token_signing_alg_values_supported"]
+	assert.False(t, has)
+
+	resp, err = http.Get(srv.IssuerURL + "/userinfo")
+	require.NoError(t, err)
+	resp.Body.Close()
+	assert.Equal(t, http.StatusNotFound, resp.StatusCode)
+}
+
+// jwkToRSAPublic converts a published RSA JWK back into a public key (test-local, stdlib only).
+func jwkToRSAPublic(k JWK) (*rsa.PublicKey, error) {
+	n, err := base64.RawURLEncoding.DecodeString(k.N)
+	if err != nil {
+		return nil, err
+	}
+	e, err := base64.RawURLEncoding.DecodeString(k.E)
+	if err != nil {
+		return nil, err
+	}
+	return &rsa.PublicKey{N: new(big.Int).SetBytes(n), E: int(new(big.Int).SetBytes(e).Int64())}, nil
+}
+
+// TestOIDC_LoginFormCarriesNonce: a browser submits the rendered form (not
+// the query string), so the nonce must ride a hidden field.
+func TestOIDC_LoginFormCarriesNonce(t *testing.T) {
+	r := startOIDC(t, ErrorMode{})
+	_, challenge := pkcePair()
+	resp, err := r.client.Get(r.srv.AuthorizationEndpoint + "?" + r.authorizeQuery("nonce-form-1", challenge).Encode())
+	require.NoError(t, err)
+	body, _ := io.ReadAll(resp.Body)
+	resp.Body.Close()
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	assert.Contains(t, string(body), `name="nonce" value="nonce-form-1"`)
+}
diff --git a/tests/oauthserver/options.go b/tests/oauthserver/options.go
index fa8f79e34..56ff67e27 100644
--- a/tests/oauthserver/options.go
+++ b/tests/oauthserver/options.go
@@ -47,6 +47,47 @@ type ErrorMode struct {
 	MCPRateLimitCount      int  // Return 429 this many times before real response
 	MCPRateLimitRetryAfter int  // Retry-After header value (seconds, 0 = omit header)
 	MCPRateLimitUseResetAt bool // Use JSON body with reset_at instead of Retry-After header
+
+	// OIDC tamper knobs (Spec 107 research D2, one per T037 network/integration
+	// case). Each takes effect only when Options.OIDC is on and produces exactly
+	// the defect its name states; everything else about the flow stays valid so
+	// a verifier's refusal is attributable to that one check.
+	IDTokenBadSignature   bool // id_token signed by a key that is NOT in the JWKS (kid still names a published key)
+	IDTokenWrongIssuer    bool // id_token `iss` is another origin
+	IDTokenWrongAudience  bool // id_token `aud` is another client_id
+	IDTokenMultiAudNoAzp  bool // id_token `aud` has two members and no `azp`
+	IDTokenAzpNonString   bool // id_token `azp` is present but not a string (a number)
+	IDTokenExpired        bool // id_token `exp` one hour in the past
+	IDTokenNbfFuture      bool // id_token `nbf` one hour in the future
+	IDTokenNoNonce        bool // id_token omits `nonce`
+	IDTokenAlgNone        bool // id_token is an unsigned `alg: none` JWT
+	IDTokenHS256          bool // id_token is HMAC-signed (HS256) with the client secret
+	IDTokenUnknownKid     bool // id_token header `kid` names a key that is not in the JWKS
+	IDTokenKeyAlgMismatch bool // id_token header says ES256 (signed by the EC key) but `kid` names the RSA key
+	EmailVerifiedFalse    bool // `email_verified: false` in the id_token and userinfo
+
+	// Groups-claim knobs (apply to the id_token and to /userinfo alike).
+	GroupsNonArray         bool // groups claim is a string, not an array
+	GroupsOverageMarker    bool // groups claim absent; Entra `_claim_names`/`_claim_sources` overage marker present
+	GroupsAbsentEverywhere bool // groups claim absent from the id_token and from /userinfo
+
+	// Userinfo knobs. Each also strips the groups claim from the id_token so a
+	// verifier that only consults /userinfo when the token lacks groups is
+	// forced onto the endpoint.
+	UserinfoSubMismatch bool // /userinfo answers with a different `sub`
+	UserinfoRedirect    bool // /userinfo answers 302 to another origin
+	UserinfoNonJSON     bool // /userinfo answers 200 with a non-JSON body
+	UserinfoUnavailable bool // /userinfo answers 503
+
+	// Provider-metadata / token-endpoint knobs (FR-020 hostile discovery).
+	DiscoveryHTTPTokenEndpoint bool // discovery advertises a plain-http, non-loopback token_endpoint
+	TokenEndpointRedirect      bool // /token answers 302 to another origin instead of a token response
+}
+
+// userinfoConsulted reports whether a knob needs the id_token to lack the
+// groups claim so that the verifier is driven onto /userinfo.
+func (e ErrorMode) userinfoConsulted() bool {
+	return e.UserinfoSubMismatch || e.UserinfoRedirect || e.UserinfoNonJSON || e.UserinfoUnavailable
 }
 
 // Options configures the OAuth test server behavior.
@@ -92,6 +133,30 @@ type Options struct {
 	// Test credentials
 	ValidUsers map[string]string // Default: {"testuser": "testpass"}
 
+	// OIDC turns the fake into an OpenID Provider (Spec 107, research D2):
+	// discovery advertises userinfo_endpoint and
+	// id_token_signing_alg_values_supported, the auth-code token response
+	// carries an RS256 id_token signed by the KeyRing, /userinfo answers for a
+	// valid access token, the JWKS also publishes an EC (P-256) key, and the
+	// authorize request's nonce is echoed in the id_token. Default: off, in
+	// which case none of this exists and the server behaves as before.
+	OIDC bool
+
+	// UserClaims holds the identity claims per ValidUsers entry (keyed by
+	// username): sub, email, email_verified, name and the groups claim (under
+	// GroupsClaim, or "groups"). Missing entries and missing keys are derived:
+	// sub from the username, email = username (or username@example.com),
+	// email_verified = true, name = the local part, groups = [].
+	UserClaims map[string]map[string]any
+
+	// ClientRedirectURIs are appended to the redirect URIs of both
+	// pre-registered test clients (e.g. mcpproxy's /api/v1/auth/callback).
+	ClientRedirectURIs []string
+
+	// GroupsClaim is the name of the groups claim in the id_token and
+	// /userinfo. Default: "groups".
+	GroupsClaim string
+
 	// Pre-registered clients (in addition to auto-generated test client)
 	Clients []ClientConfig
 }
@@ -156,6 +221,16 @@ func (o *Options) applyDefaults() {
 	if len(o.ValidUsers) == 0 {
 		o.ValidUsers = defaults.ValidUsers
 	}
+	if o.OIDC {
+		if o.GroupsClaim == "" {
+			o.GroupsClaim = "groups"
+		}
+		for _, sc := range []string{"openid", "profile", "email", "groups"} {
+			if !containsString(o.SupportedScopes, sc) {
+				o.SupportedScopes = append(o.SupportedScopes, sc)
+			}
+		}
+	}
 
 	// Enable all flows by default if none explicitly set
 	// (This is a heuristic: if all are false, enable defaults)
@@ -169,3 +244,12 @@ func (o *Options) applyDefaults() {
 		o.RequirePKCE = defaults.RequirePKCE
 	}
 }
+
+func containsString(list []string, want string) bool {
+	for _, s := range list {
+		if s == want {
+			return true
+		}
+	}
+	return false
+}
diff --git a/tests/oauthserver/server.go b/tests/oauthserver/server.go
index 58bd3b538..8d93e6258 100644
--- a/tests/oauthserver/server.go
+++ b/tests/oauthserver/server.go
@@ -3,6 +3,7 @@ package oauthserver
 import (
 	"context"
 	"crypto/rand"
+	"crypto/rsa"
 	"encoding/hex"
 	"fmt"
 	"net"
@@ -33,6 +34,9 @@ type OAuthTestServer struct {
 	// Rate limit tracking
 	mcpRateLimitHits int
 
+	// bogusKey signs id_tokens under IDTokenBadSignature; never published.
+	bogusKey *rsa.PrivateKey
+
 	mu sync.RWMutex
 
 	// Test reference
@@ -52,6 +56,7 @@ type ServerResult struct {
 	MCPURL                       string // MCP endpoint URL (for resource auto-detection testing)
 	SSEURL                       string // Legacy SSE MCP endpoint (same tools, same auth middleware)
 	ProtectedResourceMetadataURL string // RFC 9728 metadata URL
+	UserinfoEndpoint             string // OIDC userinfo (empty unless Options.OIDC)
 
 	// Pre-registered test client (confidential)
 	ClientID     string
@@ -83,6 +88,13 @@ func StartOnPort(t *testing.T, port int, opts Options) *ServerResult {
 		panic(fmt.Sprintf("Failed to create key ring: %v", err))
 	}
 
+	if err := addOIDCKeys(keyRing, opts); err != nil {
+		if t != nil {
+			t.Fatalf("Failed to create EC key: %v", err)
+		}
+		panic(fmt.Sprintf("Failed to create EC key: %v", err))
+	}
+
 	// Create listener on specific port
 	addr := fmt.Sprintf("127.0.0.1:%d", port)
 	listener, err := net.Listen("tcp", addr)
@@ -162,6 +174,9 @@ func StartOnPort(t *testing.T, port int, opts Options) *ServerResult {
 	if opts.EnableDeviceCode {
 		result.DeviceAuthorizationEndpoint = issuerURL + "/device_authorization"
 	}
+	if opts.OIDC {
+		result.UserinfoEndpoint = issuerURL + "/userinfo"
+	}
 
 	return result
 }
@@ -182,6 +197,10 @@ func Start(t *testing.T, opts Options) *ServerResult {
 		t.Fatalf("Failed to create key ring: %v", err)
 	}
 
+	if err := addOIDCKeys(keyRing, opts); err != nil {
+		t.Fatalf("Failed to create EC key: %v", err)
+	}
+
 	// Create listener on ephemeral port
 	listener, err := net.Listen("tcp", "127.0.0.1:0")
 	if err != nil {
@@ -256,6 +275,9 @@ func Start(t *testing.T, opts Options) *ServerResult {
 	if opts.EnableDeviceCode {
 		result.DeviceAuthorizationEndpoint = issuerURL + "/device_authorization"
 	}
+	if opts.OIDC {
+		result.UserinfoEndpoint = issuerURL + "/userinfo"
+	}
 
 	return result
 }
@@ -296,6 +318,11 @@ func (s *OAuthTestServer) setupRoutes(mux *http.ServeMux) {
 		mux.HandleFunc("/protected", s.handleProtected)
 	}
 
+	// OIDC userinfo (Options.OIDC only)
+	if s.options.OIDC {
+		mux.HandleFunc("/userinfo", s.handleUserinfo)
+	}
+
 	// Callback endpoint for testing - displays received OAuth parameters
 	mux.HandleFunc("/callback", s.handleCallback)
 
@@ -389,7 +416,7 @@ func (s *OAuthTestServer) registerTestClient(isPublic bool) *Client {
 	client := &Client{
 		ClientID:      clientID,
 		ClientSecret:  clientSecret,
-		RedirectURIs:  []string{"http://127.0.0.1/callback", "http://localhost/callback"},
+		RedirectURIs:  append([]string{"http://127.0.0.1/callback", "http://localhost/callback"}, s.options.ClientRedirectURIs...),
 		GrantTypes:    []string{"authorization_code", "refresh_token"},
 		ResponseTypes: []string{"code"},
 		Scopes:        s.options.SupportedScopes,
@@ -464,6 +491,19 @@ func (s *OAuthTestServer) GetClient(clientID string) (*Client, bool) {
 	return client, exists
 }
 
+// KeyRing exposes the signing keys so tests can rotate keys or mint their own
+// tokens (Spec 107 T037 crafts alg:none/HS256 tokens against the real JWKS).
+func (s *OAuthTestServer) KeyRing() *KeyRing {
+	return s.keyRing
+}
+
+// errorMode returns a snapshot of the current error injection settings.
+func (s *OAuthTestServer) errorMode() ErrorMode {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.options.ErrorMode
+}
+
 // SetErrorMode updates error injection at runtime.
 func (s *OAuthTestServer) SetErrorMode(mode ErrorMode) {
 	s.mu.Lock()
@@ -506,6 +546,15 @@ type AuthCodeInfo struct {
 	Used      bool
 }
 
+// addOIDCKeys publishes the EC key the OIDC mode needs (JWKS with RSA and EC).
+func addOIDCKeys(keyRing *KeyRing, opts Options) error {
+	if !opts.OIDC {
+		return nil
+	}
+	_, err := keyRing.AddECKey()
+	return err
+}
+
 // generateRandomString creates a random hex string of specified length.
 func generateRandomString(length int) string {
 	b := make([]byte, length/2)
diff --git a/tests/oauthserver/templates/login.html b/tests/oauthserver/templates/login.html
index 021b45bed..20fb204f8 100644
--- a/tests/oauthserver/templates/login.html
+++ b/tests/oauthserver/templates/login.html
@@ -268,6 +268,7 @@ <h3>Application requesting access:</h3>
             <input type="hidden" name="code_challenge" value="{{.CodeChallenge}}">
             <input type="hidden" name="code_challenge_method" value="{{.CodeChallengeMethod}}">
             <input type="hidden" name="resource" value="{{.Resource}}">
+            <input type="hidden" name="nonce" value="{{.Nonce}}">
             <input type="hidden" id="actionInput" name="action" value="approve">
 
             <div class="form-group">
diff --git a/tests/oauthserver/token.go b/tests/oauthserver/token.go
index f030760a1..4cecaa3cb 100644
--- a/tests/oauthserver/token.go
+++ b/tests/oauthserver/token.go
@@ -1,10 +1,17 @@
 package oauthserver
 
 import (
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/sha256"
+	"encoding/hex"
 	"encoding/json"
+	"fmt"
 	"net/http"
 	"strings"
 	"time"
+
+	"github.com/golang-jwt/jwt/v5"
 )
 
 // handleToken handles POST /token requests.
@@ -69,6 +76,15 @@ func (s *OAuthTestServer) handleAuthCodeGrant(w http.ResponseWriter, r *http.Req
 		return
 	}
 
+	// FR-020 knob: the token endpoint answers 302 to another origin. A
+	// back-channel client that follows it would leak the code and the client
+	// secret; the fake answers before it even looks at the credentials.
+	if s.options.OIDC && s.errorMode().TokenEndpointRedirect {
+		w.Header().Set("Location", "https://token.invalid/token")
+		w.WriteHeader(http.StatusFound)
+		return
+	}
+
 	// Try to get client credentials from Basic auth header
 	if clientID == "" {
 		var ok bool
@@ -179,9 +195,210 @@ func (s *OAuthTestServer) handleAuthCodeGrant(w http.ResponseWriter, r *http.Req
 		resp.RefreshToken = refreshToken
 	}
 
+	// OIDC: the auth-code response carries an id_token (Options.OIDC).
+	if s.options.OIDC {
+		idToken, err := s.mintIDToken(authCode, client)
+		if err != nil {
+			s.tokenError(w, http.StatusInternalServerError, "server_error", "Failed to generate id_token")
+			return
+		}
+		resp.IDToken = idToken
+	}
+
 	s.sendTokenResponse(w, resp)
 }
 
+// mintIDToken builds the OIDC id_token for an authorization code (research
+// D2): RS256 by the active KeyRing key with iss, sub, aud, azp, exp, iat,
+// nonce, email, email_verified, name and the groups claim from UserClaims.
+// Every ErrorMode tamper knob changes exactly one thing about the result.
+func (s *OAuthTestServer) mintIDToken(authCode *AuthorizationCode, client *Client) (string, error) {
+	mode := s.errorMode()
+	claims := s.identityClaims(authCode.Subject)
+	now := time.Now()
+
+	claims["iss"] = s.issuerURL
+	if mode.IDTokenWrongIssuer {
+		claims["iss"] = "https://issuer.invalid"
+	}
+
+	claims["aud"] = client.ClientID
+	claims["azp"] = client.ClientID
+	switch {
+	case mode.IDTokenWrongAudience:
+		claims["aud"] = "not-" + client.ClientID
+		claims["azp"] = "not-" + client.ClientID
+	case mode.IDTokenMultiAudNoAzp:
+		claims["aud"] = []string{client.ClientID, "second-audience"}
+		delete(claims, "azp")
+	case mode.IDTokenAzpNonString:
+		claims["azp"] = 12345
+	}
+
+	claims["iat"] = now.Unix()
+	claims["exp"] = now.Add(time.Hour).Unix()
+	switch {
+	case mode.IDTokenExpired:
+		claims["iat"] = now.Add(-2 * time.Hour).Unix()
+		claims["exp"] = now.Add(-time.Hour).Unix()
+	case mode.IDTokenNbfFuture:
+		claims["nbf"] = now.Add(time.Hour).Unix()
+		claims["exp"] = now.Add(2 * time.Hour).Unix()
+	}
+
+	if authCode.Nonce != "" && !mode.IDTokenNoNonce {
+		claims["nonce"] = authCode.Nonce
+	}
+
+	// The userinfo knobs need the verifier to consult /userinfo, which it
+	// only does when the token lacks the groups claim.
+	if mode.userinfoConsulted() {
+		delete(claims, s.options.GroupsClaim)
+	}
+
+	return s.signIDToken(claims, client, mode)
+}
+
+// signIDToken signs the claims per the tamper knobs; the default is RS256 by
+// the active key with its kid in the header.
+func (s *OAuthTestServer) signIDToken(claims jwt.MapClaims, client *Client, mode ErrorMode) (string, error) {
+	activeKid, activeKey := s.keyRing.GetActiveKey()
+
+	switch {
+	case mode.IDTokenAlgNone:
+		tok := jwt.NewWithClaims(jwt.SigningMethodNone, claims)
+		tok.Header["kid"] = activeKid
+		return tok.SignedString(jwt.UnsafeAllowNoneSignatureType)
+
+	case mode.IDTokenHS256:
+		tok := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
+		tok.Header["kid"] = activeKid
+		secret := client.ClientSecret
+		if secret == "" {
+			secret = "public-client-has-no-secret"
+		}
+		return tok.SignedString([]byte(secret))
+
+	case mode.IDTokenKeyAlgMismatch:
+		ecKid, ecKey := s.keyRing.GetECKey()
+		if ecKey == nil {
+			return "", fmt.Errorf("no EC key in the ring (kid %q)", ecKid)
+		}
+		tok := jwt.NewWithClaims(jwt.SigningMethodES256, claims)
+		tok.Header["kid"] = activeKid // names the RSA key, alg says ES256
+		return tok.SignedString(ecKey)
+
+	case mode.IDTokenBadSignature:
+		tok := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)
+		tok.Header["kid"] = activeKid // published kid, unpublished key
+		return tok.SignedString(s.bogusSigningKey())
+
+	case mode.IDTokenUnknownKid:
+		tok := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)
+		tok.Header["kid"] = "no-such-kid"
+		return tok.SignedString(activeKey)
+
+	default:
+		tok := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)
+		tok.Header["kid"] = activeKid
+		return tok.SignedString(activeKey)
+	}
+}
+
+// bogusSigningKey returns a lazily generated RSA key that is never published
+// in the JWKS (IDTokenBadSignature).
+func (s *OAuthTestServer) bogusSigningKey() *rsa.PrivateKey {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.bogusKey == nil {
+		key, err := rsa.GenerateKey(rand.Reader, 2048)
+		if err != nil {
+			panic(fmt.Sprintf("failed to generate bogus RSA key: %v", err))
+		}
+		s.bogusKey = key
+	}
+	return s.bogusKey
+}
+
+// identityClaims returns the OIDC identity claims for a ValidUsers entry:
+// UserClaims first, derived defaults for anything missing, then the
+// EmailVerified/Groups tamper knobs. Shared by the id_token and /userinfo.
+func (s *OAuthTestServer) identityClaims(username string) jwt.MapClaims {
+	mode := s.errorMode()
+	groupsClaim := s.options.GroupsClaim
+	claims := jwt.MapClaims{}
+	for k, v := range s.options.UserClaims[username] {
+		claims[k] = v
+	}
+
+	if _, ok := claims["email"]; !ok {
+		if strings.Contains(username, "@") {
+			claims["email"] = username
+		} else {
+			claims["email"] = username + "@example.com"
+		}
+	}
+	if _, ok := claims["sub"]; !ok {
+		sum := sha256.Sum256([]byte(username))
+		claims["sub"] = "sub-" + hex.EncodeToString(sum[:8])
+	}
+	if _, ok := claims["email_verified"]; !ok {
+		claims["email_verified"] = true
+	}
+	if _, ok := claims["name"]; !ok {
+		email, _ := claims["email"].(string)
+		claims["name"] = strings.SplitN(email, "@", 2)[0]
+	}
+	// Groups may be given under the configured claim name or plain "groups".
+	if _, ok := claims[groupsClaim]; !ok {
+		if g, ok := claims["groups"]; ok {
+			claims[groupsClaim] = g
+		} else {
+			claims[groupsClaim] = []any{}
+		}
+	}
+	if groupsClaim != "groups" {
+		delete(claims, "groups")
+	}
+
+	if mode.EmailVerifiedFalse {
+		claims["email_verified"] = false
+	}
+	switch {
+	case mode.GroupsNonArray:
+		claims[groupsClaim] = joinGroups(claims[groupsClaim])
+	case mode.GroupsOverageMarker:
+		delete(claims, groupsClaim)
+		sub, _ := claims["sub"].(string)
+		claims["_claim_names"] = map[string]any{groupsClaim: "src1"}
+		claims["_claim_sources"] = map[string]any{
+			"src1": map[string]any{"endpoint": s.issuerURL + "/users/" + sub + "/getMemberObjects"},
+		}
+	case mode.GroupsAbsentEverywhere:
+		delete(claims, groupsClaim)
+	}
+	return claims
+}
+
+// joinGroups renders a groups value as a single comma-joined string.
+func joinGroups(v any) string {
+	var parts []string
+	switch g := v.(type) {
+	case []string:
+		parts = g
+	case []any:
+		for _, item := range g {
+			parts = append(parts, fmt.Sprint(item))
+		}
+	default:
+		return fmt.Sprint(v)
+	}
+	if len(parts) == 0 {
+		return "eng"
+	}
+	return strings.Join(parts, ",")
+}
+
 // handleRefreshTokenGrant handles refresh_token grant type.
 func (s *OAuthTestServer) handleRefreshTokenGrant(w http.ResponseWriter, r *http.Request) {
 	refreshToken := r.FormValue("refresh_token")
diff --git a/tests/oauthserver/types.go b/tests/oauthserver/types.go
index 352516c13..3807cefca 100644
--- a/tests/oauthserver/types.go
+++ b/tests/oauthserver/types.go
@@ -39,6 +39,7 @@ type AuthorizationCode struct {
 	CodeChallengeMethod string
 	Resource            string // RFC 8707 resource indicator
 	State               string
+	Nonce               string // OIDC nonce from the authorize request, echoed in the id_token
 	Subject             string // Username who authorized
 	ExpiresAt           time.Time
 	Used                bool
@@ -77,6 +78,7 @@ type TokenResponse struct {
 	ExpiresIn    int    `json:"expires_in"`
 	RefreshToken string `json:"refresh_token,omitempty"`
 	Scope        string `json:"scope,omitempty"`
+	IDToken      string `json:"id_token,omitempty"` // OIDC (Options.OIDC) auth-code responses only
 }
 
 // TokenErrorResponse represents a token error response.
@@ -88,9 +90,9 @@ type TokenErrorResponse struct {
 
 // ProtectedResourceMetadata represents OAuth 2.0 Protected Resource Metadata (RFC 9728).
 type ProtectedResourceMetadata struct {
-	Resource              string   `json:"resource"`
-	AuthorizationServers  []string `json:"authorization_servers"`
-	ScopesSupported       []string `json:"scopes_supported,omitempty"`
+	Resource               string   `json:"resource"`
+	AuthorizationServers   []string `json:"authorization_servers"`
+	ScopesSupported        []string `json:"scopes_supported,omitempty"`
 	BearerMethodsSupported []string `json:"bearer_methods_supported,omitempty"`
 }
 
@@ -107,6 +109,12 @@ type DiscoveryMetadata struct {
 	GrantTypesSupported               []string `json:"grant_types_supported"`
 	CodeChallengeMethodsSupported     []string `json:"code_challenge_methods_supported"`
 	TokenEndpointAuthMethodsSupported []string `json:"token_endpoint_auth_methods_supported"`
+
+	// OpenID Provider Metadata additions (Options.OIDC only).
+	UserinfoEndpoint                 string   `json:"userinfo_endpoint,omitempty"`
+	IDTokenSigningAlgValuesSupported []string `json:"id_token_signing_alg_values_supported,omitempty"`
+	SubjectTypesSupported            []string `json:"subject_types_supported,omitempty"`
+	ClaimsSupported                  []string `json:"claims_supported,omitempty"`
 }
 
 // DeviceAuthorizationResponse represents the response from the device authorization endpoint.
@@ -121,12 +129,12 @@ type DeviceAuthorizationResponse struct {
 
 // ClientRegistrationRequest represents a DCR request.
 type ClientRegistrationRequest struct {
-	RedirectURIs              []string `json:"redirect_uris"`
-	GrantTypes                []string `json:"grant_types,omitempty"`
-	ResponseTypes             []string `json:"response_types,omitempty"`
-	ClientName                string   `json:"client_name,omitempty"`
-	Scope                     string   `json:"scope,omitempty"`
-	TokenEndpointAuthMethod   string   `json:"token_endpoint_auth_method,omitempty"`
+	RedirectURIs            []string `json:"redirect_uris"`
+	GrantTypes              []string `json:"grant_types,omitempty"`
+	ResponseTypes           []string `json:"response_types,omitempty"`
+	ClientName              string   `json:"client_name,omitempty"`
+	Scope                   string   `json:"scope,omitempty"`
+	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`
 }
 
 // ClientRegistrationResponse represents a successful DCR response.
diff --git a/tests/oauthserver/userinfo.go b/tests/oauthserver/userinfo.go
new file mode 100644
index 000000000..36dc2c069
--- /dev/null
+++ b/tests/oauthserver/userinfo.go
@@ -0,0 +1,90 @@
+package oauthserver
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/golang-jwt/jwt/v5"
+)
+
+// handleUserinfo handles GET/POST /userinfo (OpenID Connect Core §5.3).
+// Registered only when Options.OIDC is on. It answers the identity claims of
+// the user behind a valid access token, or 401 with a Bearer challenge.
+func (s *OAuthTestServer) handleUserinfo(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet && r.Method != http.MethodPost {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	authHeader := r.Header.Get("Authorization")
+	if !strings.HasPrefix(authHeader, "Bearer ") {
+		s.userinfoUnauthorized(w, "invalid_request", "Bearer token required")
+		return
+	}
+	username, ok := s.accessTokenSubject(strings.TrimPrefix(authHeader, "Bearer "))
+	if !ok {
+		s.userinfoUnauthorized(w, "invalid_token", "Access token is invalid or expired")
+		return
+	}
+
+	// Tamper knobs (research D2): each is one transport defect.
+	mode := s.errorMode()
+	switch {
+	case mode.UserinfoUnavailable:
+		http.Error(w, "userinfo temporarily unavailable", http.StatusServiceUnavailable)
+		return
+	case mode.UserinfoRedirect:
+		w.Header().Set("Location", "https://userinfo.invalid/userinfo")
+		w.WriteHeader(http.StatusFound)
+		return
+	case mode.UserinfoNonJSON:
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("<html><body>not json</body></html>"))
+		return
+	}
+
+	claims := s.identityClaims(username)
+	if mode.UserinfoSubMismatch {
+		sub, _ := claims["sub"].(string)
+		claims["sub"] = "someone-else-" + sub
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Cache-Control", "no-store")
+	if err := json.NewEncoder(w).Encode(claims); err != nil {
+		http.Error(w, "Failed to encode userinfo", http.StatusInternalServerError)
+	}
+}
+
+// userinfoUnauthorized answers 401 with an RFC 6750 challenge.
+func (s *OAuthTestServer) userinfoUnauthorized(w http.ResponseWriter, code, description string) {
+	w.Header().Set("WWW-Authenticate", fmt.Sprintf(`Bearer realm="userinfo", error="%s", error_description="%s"`, code, description))
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusUnauthorized)
+	_ = json.NewEncoder(w).Encode(OAuthError{Error: code, ErrorDescription: description})
+}
+
+// accessTokenSubject verifies an access token issued by this server (RS256,
+// key looked up by kid so tokens survive rotation) and returns its subject —
+// the ValidUsers username the code was authorised as.
+func (s *OAuthTestServer) accessTokenSubject(tokenStr string) (string, bool) {
+	claims := &TokenClaims{}
+	tok, err := jwt.ParseWithClaims(tokenStr, claims, func(t *jwt.Token) (any, error) {
+		if _, ok := t.Method.(*jwt.SigningMethodRSA); !ok {
+			return nil, fmt.Errorf("unexpected signing method: %v", t.Header["alg"])
+		}
+		if kid, _ := t.Header["kid"].(string); kid != "" {
+			if key, ok := s.keyRing.GetKey(kid); ok {
+				return &key.PublicKey, nil
+			}
+		}
+		return s.keyRing.GetPublicKey(), nil
+	}, jwt.WithValidMethods([]string{"RS256"}), jwt.WithIssuer(s.issuerURL))
+	if err != nil || !tok.Valid || claims.Subject == "" {
+		return "", false
+	}
+	return claims.Subject, true
+}