llm-cli-gateway 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -4,6 +4,76 @@ All notable changes to the llm-cli-gateway project.
 
 ## Unreleased
 
+## [2.5.0] - 2026-06-08: Remote connector OAuth and workspaces
+
+- Added remote connector OAuth discovery and authorization-code support with
+  hash-only static client/shared-secret configuration, copy-once local secret
+  commands, and OAuth-first ChatGPT setup guidance.
+- Added workspace registry and workspace creation surfaces so provider requests
+  can select registered repo aliases and create local folders/Git repos only
+  under configured allowed roots.
+
+## [2.4.0] - 2026-06-08: Direct Grok API provider and provider-owned sessions
+
+### Added
+
+- Direct xAI Grok API provider support:
+  - new `ProviderType` split so stored sessions, metrics, flight-recorder rows,
+    and migrations can represent the non-CLI `grok-api` provider alongside the
+    existing CLI providers;
+  - `[providers.xai]` config loading with API-key env indirection and provider
+    enablement gating;
+  - `grok_api_request`, registered only when xAI API config and credentials are
+    present, backed by the xAI Responses API;
+  - xAI response parsing, retry/circuit-breaker handling, usage/cost metadata,
+    and `previous_response_id` session metadata;
+  - focused migration, session-manager, provider-config, and Grok API tests.
+- Provider subcommand contract resources and tooling:
+  - provider subcommand catalog/detail resource generation;
+  - `provider_subcommands_list`, `provider_subcommand_contract`, and
+    `provider_subcommand_drift` surfaces exercised through MCP Inspector.
+- Host auto-upgrade operations:
+  - `scripts/host-upgrade.sh` for staged, atomic npm-based host upgrades with
+    rollback support;
+  - user systemd service/timer units for scheduled gateway auto-upgrade checks.
+- Direct Grok API provider design draft documenting the follow-on async-runner
+  and capability-table design work.
+
+### Fixed
+
+- Provider-owned stored session enforcement now rejects cross-provider reuse for
+  all request handlers, including `claude_request`, `codex_request`,
+  `gemini_request`, `grok_request`, `mistral_request`, their async variants,
+  `codex_fork_session`, and `grok_api_request`.
+- `sessions://all` now reports active sessions across all provider types,
+  including `grok-api`.
+- MCP resource URI schemes now use standards-valid hyphenated forms:
+  `cache-state://...` and `provider-subcommands://...`. MCP Inspector exposed
+  the previous underscore schemes as invalid URL schemes for standard MCP
+  clients. Legacy direct `provider_subcommands://...` reads remain accepted for
+  internal compatibility tests/callers, but advertised resources now use only
+  valid URI schemes.
+- `src/executor.ts` avoids pidless child-process kill attempts.
+
+### Changed
+
+- GitHub Actions pins were refreshed to current pinned action SHAs.
+- Provider subcommand support remains CLI-only where appropriate; the direct
+  API provider is excluded from spawnable-CLI contract paths.
+
+### Verification
+
+- Dirty-tree stack split and release evidence recorded in
+  `docs/reviews/dirty-tree-stack-split-verification-2026-06-08.md`.
+- MCP Inspector smoke covered tools/list, resources/list, read-only tool calls,
+  session lifecycle, direct xAI API registration through a loopback mock, and
+  exhaustive advertised-resource reads.
+- Multi-LLM review completed with Claude, Codex, Gemini, Grok, and Mistral
+  approvals for the main stack and the Inspector-discovered URI-scheme fix.
+- Final merged `master` verification before mirror push:
+  `npm run check` passed, including build, lint, format check, 67 test files /
+  1124 tests, and the release security audit.
+
 ## [2.3.0] - 2026-06-08: MCP tool annotations and client safety hints
 
 ### Added
@@ -1512,7 +1582,7 @@ boundary bypass); all are addressed in the two follow-up fix commits.
 Closes the two telemetry gaps that v1.6.0 explicitly deferred: async-path
 flight-recorder integration and Codex parser support for the actual
 `cached_input_tokens` field the current Codex CLI emits. Both ship
-together because they jointly close out `cache_state://*` completeness
+together because they jointly close out `cache-state://*` completeness
 for the async tools and the codex CLI.
 
 ### Added — async-path flight recorder writes
@@ -1552,9 +1622,9 @@ stderr, exitCode }> }` so the manager constructor can write FR
   `{ count: 0, orphaned: [] }` (in-process state can't be orphaned).
   Breaking change to the `JobStore` interface; the `PostgresJobStore`
   stub was updated to match (the impl is still not yet shipped).
-- `cache_state://global`, `cache_state://session/{id}`, and
-  `cache_state://prefix/{hash}` aggregates now include async-job
-  activity. No query changes — `cache_state://*` already didn't filter
+- `cache-state://global`, `cache-state://session/{id}`, and
+  `cache-state://prefix/{hash}` aggregates now include async-job
+  activity. No query changes — `cache-state://*` already didn't filter
   on `asyncJobId`, so the new rows participate naturally.
 
 ### Fixed — Codex parser accepts current CLI's cache-token field
@@ -1585,7 +1655,7 @@ distinguishing `errorMessage`. The underlying `jobs` table in JobStore
 retains the distinct `"canceled"` / `"orphaned"` statuses for
 `getJobSnapshot` callers. External consumers of `~/.llm-cli-gateway/
 logs.db` that filter `status='failed'` will count cancels and boot-time
-orphans as errors; `cache_state://*` aggregation does not distinguish.
+orphans as errors; `cache-state://*` aggregation does not distinguish.
 
 ### No config or schema changes
 
@@ -1647,7 +1717,7 @@ Pure documentation release; zero source-code changes since 1.6.0.
 ### Changed — 12 SKILL.md files current with v1.6.0
 
 - All 12 skills (7 under `skills/`, 5 under `.agents/skills/`) extended
-  with `promptParts`, `cache_state://` MCP resources, and (where the
+  with `promptParts`, `cache-state://` MCP resources, and (where the
   skill's centre of gravity is session continuity) the
   `cache_ttl_expiring_soon` warning. Depth tiered by skill audience:
   multi-llm-orchestration, model-routing, multi-llm-consensus,
@@ -1754,9 +1824,9 @@ Also includes (beyond cache-awareness):
   `requests`, plus `idx_requests_stable_hash`. Legacy rows keep NULL.
 - **Cache-state MCP resources** (read-only, tokens/hashes/aggregates only —
   never raw prompt text):
-  - `cache_state://global` (last 24h aggregates + per-CLI breakdown).
-  - `cache_state://session/{sessionId}` (per-session).
-  - `cache_state://prefix/{hash}` (per-stable-prefix-hash).
+  - `cache-state://global` (last 24h aggregates + per-CLI breakdown).
+  - `cache-state://session/{sessionId}` (per-session).
+  - `cache-state://prefix/{hash}` (per-stable-prefix-hash).
 - **`session_get.cacheState`** projection: compact hit-rate / hit-count /
   cache-token-totals / estimated-savings-USD block, present only when the
   session has prior requests. Omitted entirely (not null, not empty) for

package/README.md

@@ -44,6 +44,8 @@ Or use directly with `npx` from an MCP client:
 - Supports cache-aware `promptParts`, including explicit Claude `cache_control` when opted in.
 - Can run requests inside gateway-managed git worktrees for isolated multi-agent review and implementation loops.
 - Ships personal-appliance setup surfaces: HTTP transport with bearer-token auth, `doctor --json`, setup UI artifacts, provider setup snippets, Docker fallback, and checked release bundles.
+- Remote web connectors use MCP OAuth discovery and authorization-code setup with static client or shared-secret gates. Client secrets are generated locally, stored only as hashes, and printed only by explicit copy-once commands.
+- Provider CLI requests can select registered workspaces by alias via `workspace`; remote requests should use aliases, not arbitrary filesystem paths. New local folder/Git workspaces can be created only under configured allowed roots.
 
 ## Workflow Assets
 
@@ -164,7 +166,7 @@ docker compose -f docker/personal.compose.yml run --rm doctor
 
 - **SQLite Flight Recorder**: Every request/response logged to `~/.llm-cli-gateway/logs.db` with correlation IDs, token usage, duration, retry counts, and circuit breaker state. Browse with [Datasette](https://datasette.io/): `datasette ~/.llm-cli-gateway/logs.db`
 - **Structured Metadata**: Tool responses include machine-readable `structuredContent` (model, cli, correlationId, sessionId, durationMs, token counts)
-- **Cache observability resources**: `cache_state://global`, `cache_state://session/{id}`, and `cache_state://prefix/{hash}` MCP resources return aggregate cache hit/miss/savings — tokens and hashes only, no prompt text. `session_get` includes a `cacheState` block when the session has prior requests.
+- **Cache observability resources**: `cache-state://global`, `cache-state://session/{id}`, and `cache-state://prefix/{hash}` MCP resources return aggregate cache hit/miss/savings — tokens and hashes only, no prompt text. `session_get` includes a `cacheState` block when the session has prior requests.
 
 ### Cache-aware operation
 

package/dist/auth.d.ts

@@ -8,8 +8,51 @@ export interface AuthResult {
     ok: boolean;
     status?: number;
     message?: string;
+    kind?: "disabled" | "gateway_bearer" | "oauth";
+    scopes?: string[];
+    clientId?: string;
 }
+export type OAuthRegistrationPolicy = "static_clients" | "shared_secret" | "open_dev";
+export interface RemoteOAuthClientConfig {
+    clientId: string;
+    clientSecretHash: string | null;
+    allowedRedirectUris: string[];
+    scopes: string[];
+}
+export interface RemoteOAuthSharedSecretConfig {
+    enabled: boolean;
+    secretHash: string | null;
+    promptLabel: string;
+}
+export interface RemoteOAuthConfig {
+    enabled: boolean;
+    issuer: string | "auto";
+    requirePkce: boolean;
+    allowPlainPkce: boolean;
+    registrationPolicy: OAuthRegistrationPolicy;
+    allowPublicClients: boolean;
+    tokenTtlSeconds: number;
+    clients: RemoteOAuthClientConfig[];
+    sharedSecret: RemoteOAuthSharedSecretConfig | null;
+    sources: {
+        configFile: string | null;
+        envOverrides: string[];
+    };
+}
+export declare function timingSafeStringEqual(left: string, right: string): boolean;
 export declare function loadAuthConfig(env?: NodeJS.ProcessEnv): AuthConfig;
 export declare function getRequiredBearerToken(env?: NodeJS.ProcessEnv): string | null;
+export declare function issueOAuthAccessToken(args: {
+    clientId: string;
+    scopes: string[];
+    ttlSeconds: number;
+    now?: number;
+}): {
+    accessToken: string;
+    expiresIn: number;
+    scope: string;
+};
 export declare function authorizeBearerRequest(req: IncomingMessage, token?: string | null): AuthResult;
-export declare function writeAuthFailure(res: ServerResponse, result: AuthResult): void;
+export declare function writeAuthFailure(res: ServerResponse, result: AuthResult, options?: {
+    resourceMetadataUrl?: string;
+}): void;

package/dist/auth.js

@@ -1,4 +1,15 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
 const AUTH_SCHEME = "Bearer ";
+const OAUTH_ACCESS_TOKEN_BYTES = 32;
+const oauthAccessTokens = new Map();
+export function timingSafeStringEqual(left, right) {
+    const leftBuffer = Buffer.from(left, "utf8");
+    const rightBuffer = Buffer.from(right, "utf8");
+    if (leftBuffer.length !== rightBuffer.length) {
+        return false;
+    }
+    return timingSafeEqual(leftBuffer, rightBuffer);
+}
 export function loadAuthConfig(env = process.env) {
     const token = env.LLM_GATEWAY_AUTH_TOKEN;
     const disabled = env.LLM_GATEWAY_AUTH_DISABLED === "1";
@@ -14,16 +25,32 @@ export function getRequiredBearerToken(env = process.env) {
         return null;
     return env.LLM_GATEWAY_AUTH_TOKEN || null;
 }
+export function issueOAuthAccessToken(args) {
+    const now = args.now ?? Date.now();
+    const ttlSeconds = Math.max(1, Math.floor(args.ttlSeconds));
+    const scopes = [...new Set(args.scopes.length ? args.scopes : ["mcp"])];
+    const accessToken = `oauth_${randomBytes(OAUTH_ACCESS_TOKEN_BYTES).toString("base64url")}`;
+    oauthAccessTokens.set(accessToken, {
+        clientId: args.clientId,
+        scopes,
+        issuedAt: now,
+        expiresAt: now + ttlSeconds * 1000,
+    });
+    return { accessToken, expiresIn: ttlSeconds, scope: scopes.join(" ") };
+}
+function validateOAuthAccessToken(token, now = Date.now()) {
+    const entry = oauthAccessTokens.get(token);
+    if (!entry)
+        return null;
+    if (entry.expiresAt <= now) {
+        oauthAccessTokens.delete(token);
+        return null;
+    }
+    return entry;
+}
 export function authorizeBearerRequest(req, token = getRequiredBearerToken()) {
     if (!loadAuthConfig().required) {
-        return { ok: true };
-    }
-    if (!token) {
-        return {
-            ok: false,
-            status: 503,
-            message: "HTTP transport requires LLM_GATEWAY_AUTH_TOKEN",
-        };
+        return { ok: true, kind: "disabled", scopes: [] };
     }
     const header = req.headers.authorization;
     const value = Array.isArray(header) ? header[0] : header;
@@ -31,16 +58,36 @@ export function authorizeBearerRequest(req, token = getRequiredBearerToken()) {
         return { ok: false, status: 401, message: "Unauthorized" };
     }
     const supplied = value.slice(AUTH_SCHEME.length);
-    if (supplied !== token) {
-        return { ok: false, status: 401, message: "Unauthorized" };
+    if (token && timingSafeStringEqual(supplied, token)) {
+        return { ok: true, kind: "gateway_bearer", scopes: [] };
     }
-    return { ok: true };
+    const oauthToken = validateOAuthAccessToken(supplied);
+    if (oauthToken) {
+        return {
+            ok: true,
+            kind: "oauth",
+            scopes: oauthToken.scopes,
+            clientId: oauthToken.clientId,
+        };
+    }
+    if (!token) {
+        return {
+            ok: false,
+            status: 503,
+            message: "HTTP transport requires LLM_GATEWAY_AUTH_TOKEN",
+        };
+    }
+    return { ok: false, status: 401, message: "Unauthorized" };
 }
-export function writeAuthFailure(res, result) {
+export function writeAuthFailure(res, result, options = {}) {
     const status = result.status ?? 401;
+    let wwwAuthenticate = 'Bearer realm="llm-cli-gateway"';
+    if (options.resourceMetadataUrl) {
+        wwwAuthenticate += `, resource_metadata="${options.resourceMetadataUrl}"`;
+    }
     res.writeHead(status, {
         "content-type": "application/json",
-        "www-authenticate": 'Bearer realm="llm-cli-gateway"',
+        "www-authenticate": wwwAuthenticate,
     });
     res.end(JSON.stringify({ error: result.message || "Unauthorized" }));
 }

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 import type { Logger } from "./logger.js";
+import type { RemoteOAuthConfig } from "./auth.js";
 export interface DatabaseConfig {
     connectionString: string;
     pool: {
@@ -32,6 +33,7 @@ export interface PersistenceConfigSources {
     configFile: string | null;
     envOverrides: string[];
 }
+export declare function defaultGatewayConfigPath(): string;
 export declare function loadPersistenceConfig(logger?: Logger): PersistenceConfig;
 export declare const ANTHROPIC_TTL_SECONDS_VALUES: readonly [300, 3600];
 export type AnthropicTtlSeconds = (typeof ANTHROPIC_TTL_SECONDS_VALUES)[number];
@@ -58,3 +60,20 @@ export interface CacheAwarenessConfig {
 }
 export declare function loadCacheAwarenessConfig(logger?: Logger): CacheAwarenessConfig;
 export declare function minStableTokensForModel(config: CacheAwarenessConfig, modelName: string): number;
+export declare const DEFAULT_XAI_API_KEY_ENV = "XAI_API_KEY";
+export declare const DEFAULT_XAI_BASE_URL = "https://api.x.ai/v1";
+export declare const DEFAULT_XAI_MODEL = "grok-build-0.1";
+export interface XaiProviderConfig {
+    apiKeyEnv: string;
+    baseUrl: string;
+    defaultModel: string;
+}
+export interface ProvidersConfig {
+    xai: XaiProviderConfig | null;
+    sources: {
+        configFile: string | null;
+    };
+}
+export declare function loadProvidersConfig(logger?: Logger): ProvidersConfig;
+export declare function isXaiProviderEnabled(config: ProvidersConfig, env?: NodeJS.ProcessEnv): boolean;
+export declare function loadRemoteOAuthConfig(logger?: Logger, env?: NodeJS.ProcessEnv): RemoteOAuthConfig;

package/dist/config.js

@@ -4,6 +4,7 @@ import path from "path";
 import { createRequire } from "module";
 import { z } from "zod/v3";
 import { logWarn, noopLogger } from "./logger.js";
+import { hashSecret, isSecretHash } from "./oauth.js";
 const DatabaseUrlSchema = z
     .string()
     .url()
@@ -56,6 +57,9 @@ const DEFAULT_SQLITE_PATH = path.join(os.homedir(), ".llm-cli-gateway", "logs.db
 function defaultPersistenceConfigPath() {
     return (process.env.LLM_GATEWAY_CONFIG ?? path.join(os.homedir(), ".llm-cli-gateway", "config.toml"));
 }
+export function defaultGatewayConfigPath() {
+    return defaultPersistenceConfigPath();
+}
 function readPersistenceFile(configPath, logger) {
     if (!existsSync(configPath)) {
         return { raw: undefined, sourcePath: null };
@@ -72,6 +76,21 @@ function readPersistenceFile(configPath, logger) {
         return { raw: undefined, sourcePath: null };
     }
 }
+function readGatewayTomlFile(configPath, logger, fallbackLabel) {
+    if (!existsSync(configPath)) {
+        return { parsed: null, sourcePath: null };
+    }
+    try {
+        const require = createRequire(import.meta.url);
+        const TOML = require("smol-toml");
+        const text = readFileSync(configPath, "utf-8");
+        return { parsed: TOML.parse(text), sourcePath: configPath };
+    }
+    catch (err) {
+        logger.error(`Failed to parse gateway config at ${configPath}; using ${fallbackLabel} defaults`, err);
+        return { parsed: null, sourcePath: null };
+    }
+}
 function applyEnvOverrides(base, logger, sources) {
     const out = { ...base };
     const jobsDbEnv = process.env.LLM_GATEWAY_JOBS_DB;
@@ -248,3 +267,219 @@ export function minStableTokensForModel(config, modelName) {
         return table.haiku;
     return table.default;
 }
+export const DEFAULT_XAI_API_KEY_ENV = "XAI_API_KEY";
+export const DEFAULT_XAI_BASE_URL = "https://api.x.ai/v1";
+export const DEFAULT_XAI_MODEL = "grok-build-0.1";
+function isHttpsOrLoopbackUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol === "https:")
+            return true;
+        if (url.protocol !== "http:")
+            return false;
+        return ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+const XaiProviderSchema = z
+    .object({
+    api_key_env: z.string().min(1).default(DEFAULT_XAI_API_KEY_ENV),
+    base_url: z
+        .string()
+        .url()
+        .refine(isHttpsOrLoopbackUrl, {
+        message: "base_url must use https unless it targets localhost/loopback for tests",
+    })
+        .default(DEFAULT_XAI_BASE_URL),
+    default_model: z.string().min(1).default(DEFAULT_XAI_MODEL),
+})
+    .strict();
+function readProvidersFile(configPath, logger) {
+    if (!existsSync(configPath)) {
+        return { raw: undefined, sourcePath: null };
+    }
+    try {
+        const require = createRequire(import.meta.url);
+        const TOML = require("smol-toml");
+        const text = readFileSync(configPath, "utf-8");
+        const parsed = TOML.parse(text);
+        return { raw: parsed?.providers, sourcePath: configPath };
+    }
+    catch (err) {
+        logger.error(`Failed to parse gateway config at ${configPath}; using provider defaults`, err);
+        return { raw: undefined, sourcePath: null };
+    }
+}
+export function loadProvidersConfig(logger = noopLogger) {
+    const configPath = defaultGatewayConfigPath();
+    const { raw, sourcePath } = readProvidersFile(configPath, logger);
+    const providers = raw ?? {};
+    const rawXai = providers.xai;
+    if (rawXai === undefined) {
+        return {
+            xai: null,
+            sources: { configFile: sourcePath },
+        };
+    }
+    const parsed = XaiProviderSchema.safeParse(rawXai);
+    if (!parsed.success) {
+        logWarn(logger, "Invalid [providers.xai] config; xAI API provider disabled", {
+            error: parsed.error.message,
+        });
+        return {
+            xai: null,
+            sources: { configFile: sourcePath },
+        };
+    }
+    return {
+        xai: {
+            apiKeyEnv: parsed.data.api_key_env,
+            baseUrl: parsed.data.base_url,
+            defaultModel: parsed.data.default_model,
+        },
+        sources: { configFile: sourcePath },
+    };
+}
+export function isXaiProviderEnabled(config, env = process.env) {
+    const keyEnv = config.xai?.apiKeyEnv;
+    if (!keyEnv)
+        return false;
+    return typeof env[keyEnv] === "string" && env[keyEnv].trim().length > 0;
+}
+const OAuthRegistrationPolicySchema = z.enum(["static_clients", "shared_secret", "open_dev"]);
+const OAuthClientSchema = z
+    .object({
+    client_id: z.string().min(1),
+    client_secret_hash: z.string().optional(),
+    allowed_redirect_uris: z.array(z.string().url()).default([]),
+    scopes: z.array(z.string().min(1)).default(["mcp"]),
+})
+    .strict();
+const OAuthSharedSecretSchema = z
+    .object({
+    enabled: z.boolean().default(false),
+    secret_hash: z.string().optional(),
+    prompt_label: z.string().min(1).default("Gateway access code"),
+})
+    .strict();
+const OAuthConfigSchema = z
+    .object({
+    enabled: z.boolean().default(false),
+    issuer: z.string().min(1).default("auto"),
+    require_pkce: z.boolean().default(true),
+    allow_plain_pkce: z.boolean().default(false),
+    registration_policy: OAuthRegistrationPolicySchema.default("static_clients"),
+    allow_public_clients: z.boolean().default(false),
+    token_ttl_seconds: z.number().int().positive().default(3600),
+    clients: z.array(OAuthClientSchema).default([]),
+    shared_secret: OAuthSharedSecretSchema.optional(),
+})
+    .strict();
+function disabledOAuthConfig(sourcePath = null, envOverrides = []) {
+    return {
+        enabled: false,
+        issuer: "auto",
+        requirePkce: true,
+        allowPlainPkce: false,
+        registrationPolicy: "static_clients",
+        allowPublicClients: false,
+        tokenTtlSeconds: 3600,
+        clients: [],
+        sharedSecret: null,
+        sources: { configFile: sourcePath, envOverrides },
+    };
+}
+function isSafeRedirectUri(uri) {
+    return isHttpsOrLoopbackUrl(uri);
+}
+export function loadRemoteOAuthConfig(logger = noopLogger, env = process.env) {
+    const configPath = defaultGatewayConfigPath();
+    const { parsed: configFile, sourcePath } = readGatewayTomlFile(configPath, logger, "OAuth");
+    const rawHttp = configFile?.http ?? {};
+    const rawOAuth = rawHttp.oauth ?? {};
+    const envOverrides = [];
+    const merged = { ...rawOAuth };
+    if (env.LLM_GATEWAY_OAUTH_ENABLED !== undefined) {
+        merged.enabled = env.LLM_GATEWAY_OAUTH_ENABLED === "1";
+        envOverrides.push("LLM_GATEWAY_OAUTH_ENABLED");
+    }
+    if (env.LLM_GATEWAY_OAUTH_REGISTRATION_SECRET || env.LLM_GATEWAY_OAUTH_SHARED_SECRET) {
+        const rawSecret = env.LLM_GATEWAY_OAUTH_REGISTRATION_SECRET || env.LLM_GATEWAY_OAUTH_SHARED_SECRET;
+        merged.registration_policy = "shared_secret";
+        merged.shared_secret = {
+            enabled: true,
+            secret_hash: rawSecret ? hashSecret(rawSecret) : undefined,
+            prompt_label: "Gateway access code",
+        };
+        envOverrides.push(env.LLM_GATEWAY_OAUTH_REGISTRATION_SECRET
+            ? "LLM_GATEWAY_OAUTH_REGISTRATION_SECRET"
+            : "LLM_GATEWAY_OAUTH_SHARED_SECRET");
+    }
+    const parsed = OAuthConfigSchema.safeParse(merged);
+    if (!parsed.success) {
+        logWarn(logger, "Invalid [http.oauth] config; remote OAuth disabled", {
+            error: parsed.error.message,
+        });
+        return disabledOAuthConfig(sourcePath, envOverrides);
+    }
+    const data = parsed.data;
+    if (data.issuer !== "auto" && !isHttpsOrLoopbackUrl(data.issuer)) {
+        logWarn(logger, "Invalid [http.oauth].issuer; remote OAuth disabled");
+        return disabledOAuthConfig(sourcePath, envOverrides);
+    }
+    for (const client of data.clients) {
+        if (!data.allow_public_clients && !client.client_secret_hash) {
+            logWarn(logger, "OAuth client secret hash is required when public clients are disabled", {
+                client_id: client.client_id,
+            });
+            return disabledOAuthConfig(sourcePath, envOverrides);
+        }
+        if (client.client_secret_hash && !isSecretHash(client.client_secret_hash)) {
+            logWarn(logger, "Invalid OAuth client secret hash; remote OAuth disabled", {
+                client_id: client.client_id,
+            });
+            return disabledOAuthConfig(sourcePath, envOverrides);
+        }
+        if (client.allowed_redirect_uris.length === 0 ||
+            client.allowed_redirect_uris.some(uri => !isSafeRedirectUri(uri))) {
+            logWarn(logger, "Invalid OAuth client redirect URI; remote OAuth disabled", {
+                client_id: client.client_id,
+            });
+            return disabledOAuthConfig(sourcePath, envOverrides);
+        }
+    }
+    if (data.shared_secret?.enabled) {
+        if (!data.shared_secret.secret_hash || !isSecretHash(data.shared_secret.secret_hash)) {
+            logWarn(logger, "Invalid [http.oauth.shared_secret] secret_hash; remote OAuth disabled");
+            return disabledOAuthConfig(sourcePath, envOverrides);
+        }
+    }
+    if (data.registration_policy === "open_dev" && env.LLM_GATEWAY_OAUTH_OPEN_DEV !== "1") {
+        logWarn(logger, "[http.oauth].registration_policy='open_dev' is intended for localhost/dev only");
+    }
+    return {
+        enabled: data.enabled,
+        issuer: data.issuer,
+        requirePkce: data.require_pkce,
+        allowPlainPkce: data.allow_plain_pkce,
+        registrationPolicy: data.registration_policy,
+        allowPublicClients: data.allow_public_clients,
+        tokenTtlSeconds: data.token_ttl_seconds,
+        clients: data.clients.map(client => ({
+            clientId: client.client_id,
+            clientSecretHash: client.client_secret_hash ?? null,
+            allowedRedirectUris: client.allowed_redirect_uris,
+            scopes: client.scopes,
+        })),
+        sharedSecret: data.shared_secret
+            ? {
+                enabled: data.shared_secret.enabled,
+                secretHash: data.shared_secret.secret_hash ?? null,
+                promptLabel: data.shared_secret.prompt_label,
+            }
+            : null,
+        sources: { configFile: sourcePath, envOverrides },
+    };
+}

package/dist/doctor.d.ts

@@ -69,6 +69,21 @@ export interface DoctorReport {
         required: boolean;
         token_configured: boolean;
         source: string;
+        oauth: {
+            enabled: boolean;
+            registration_policy: string;
+            clients_configured: number;
+            shared_secret_enabled: boolean;
+            pkce_required: boolean;
+            issuer: string | null;
+        };
+    };
+    workspaces: {
+        enabled: boolean;
+        default: string | null;
+        repo_count: number;
+        allowed_root_count: number;
+        gateway_app_dir_is_workspace: boolean;
     };
     providers: Record<"claude" | "codex" | "gemini" | "grok" | "mistral", {
         cli_available: boolean;

package/dist/doctor.js

@@ -6,7 +6,8 @@ import { loadAuthConfig } from "./auth.js";
 import { createEndpointExposureReport, redactDiagnosticUrl, } from "./endpoint-exposure.js";
 import { listProviderRuntimeStatuses, } from "./provider-status.js";
 import { CLAUDE_MCP_SERVER_NAMES } from "./claude-mcp-config.js";
-import { loadCacheAwarenessConfig } from "./config.js";
+import { loadCacheAwarenessConfig, loadRemoteOAuthConfig, } from "./config.js";
+import { loadWorkspaceRegistry } from "./workspace-registry.js";
 import { computeGlobalCacheStats } from "./cache-stats.js";
 import { FlightRecorder, resolveFlightRecorderDbPath } from "./flight-recorder.js";
 import { buildUpstreamContractReport } from "./upstream-contracts.js";
@@ -168,16 +169,7 @@ function chatGPTConnectorUrl(env, rawPublicUrl) {
         .find(value => value.startsWith("/") && !value.includes("?") && !value.includes("#"));
     if (!rawPublicUrl || !path)
         return null;
-    try {
-        const url = new URL(rawPublicUrl);
-        url.pathname = path;
-        url.search = "";
-        url.hash = "";
-        return redactDiagnosticUrl(url.toString());
-    }
-    catch {
-        return null;
-    }
+    return "<redacted>";
 }
 function buildCacheAwarenessReport(opts) {
     const enabled = [];
@@ -240,6 +232,8 @@ export function createDoctorReport(envOrOptions = process.env) {
         : { env: envOrOptions };
     const env = opts.env ?? process.env;
     const auth = loadAuthConfig(env);
+    const oauth = loadRemoteOAuthConfig(undefined, env);
+    const workspaceRegistry = loadWorkspaceRegistry();
     const transport = defaultTransport(env);
     const rawPublicUrl = env.LLM_GATEWAY_PUBLIC_URL || null;
     const publicUrl = redactDiagnosticUrl(rawPublicUrl);
@@ -294,6 +288,23 @@ export function createDoctorReport(envOrOptions = process.env) {
             required: auth.required,
             token_configured: auth.tokenConfigured,
             source: auth.source,
+            oauth: {
+                enabled: oauth.enabled,
+                registration_policy: oauth.registrationPolicy,
+                clients_configured: oauth.clients.length,
+                shared_secret_enabled: Boolean(oauth.sharedSecret?.enabled),
+                pkce_required: oauth.requirePkce,
+                issuer: oauth.issuer === "auto"
+                    ? publicUrl
+                    : redactDiagnosticUrl(oauth.issuer === "auto" ? null : oauth.issuer),
+            },
+        },
+        workspaces: {
+            enabled: workspaceRegistry.enabled,
+            default: workspaceRegistry.defaultAlias,
+            repo_count: workspaceRegistry.repos.length,
+            allowed_root_count: workspaceRegistry.allowedRoots.length,
+            gateway_app_dir_is_workspace: workspaceRegistry.repos.some(repo => repo.path === join(homedir(), ".llm-cli-gateway")),
         },
         providers: {
             claude: doctorProviderStatus(providerStatuses.claude),