llm-cli-gateway 2.13.1 → 2.13.2

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to the llm-cli-gateway project.
 
+## [2.13.2] - 2026-07-01: remote HTTP + OAuth connector UX and hardening
+
+### Added
+
+- **`remote_http_oauth` readiness projection in `doctor --json`.** A stable,
+  ordered 8-stage decision tree (`not_started`, `missing_public_url`,
+  `endpoint_unreachable`, `oauth_disabled`, `unsafe_oauth_config`,
+  `missing_oauth_client`, `missing_workspace`, `ready`) with deterministic,
+  secret-free `next_actions`, the copy-safe connector URLs, `oauth.consent_required`,
+  and a path-free workspace summary. Validated by `setup/status.schema.json`.
+- **`llm-cli-gateway connector setup` command.** Emits a copy-safe JSON connector
+  packet (MCP URL, authorization URL, token URL, client id, workspace guidance)
+  plus a human summary, reusing the readiness projection. The deprecated no-auth
+  connector URL is omitted unless `--include-legacy-no-auth` is passed.
+- **Centralized remote URL construction (`src/remote-url.ts`).** doctor, the
+  connector packet, the CLI OAuth output, the installer, and the runtime OAuth
+  well-known metadata + `WWW-Authenticate` challenge all derive URLs from one
+  helper so they cannot drift.
+
+### Changed
+
+- **OAuth-first remote connector docs and setup UI.** The ChatGPT guide,
+  endpoint-exposure runbook, `ENDPOINT_EXPOSURE.md`, and setup UI lead with the
+  OAuth path keyed on `remote_http_oauth.stage`; the no-auth connector is
+  compatibility-only. `oauth client add` validates the redirect URI and client
+  id before writing, refuses duplicate ids, and labels copy-once secret output.
+
+### Security
+
+- **F17 hardening.** The unsafe-OAuth (public clients / `open_dev`) start gate
+  now fails closed when the gateway is publicly exposed via a public URL or
+  tunnel, not only on a non-loopback bind.
+- **No local-path disclosure to remote clients.** Remote MCP `workspace_*`
+  tools, `session_get`, `sessions://*` resources, and worktree response paths
+  are path-redacted for remote HTTP/OAuth callers (local operators keep absolute
+  paths; resume metadata is unaffected). `workspace_register_existing_repo` no
+  longer acts as a filesystem existence oracle.
+- **Installer URL redaction.** The Go installer derives OAuth/MCP URLs from a
+  clean origin and strips userinfo/query/fragment from the stored public URL, so
+  no credential-bearing URL is emitted.
+- **gitleaks allowlist** now covers the `gateway-logger` redaction test fixtures
+  (deliberate fake tokens), restoring a green secret-scan gate.
+
 ## [2.13.1] - 2026-07-01: code-scanning hardening and review-gate discipline
 
 ### Security

package/dist/config.d.ts

@@ -162,4 +162,12 @@ export interface AcpConfig {
     };
 }
 export declare function loadAcpConfig(logger?: Logger): AcpConfig;
+export type RemoteOAuthConfigStatus = "absent" | "disabled" | "enabled" | "malformed";
+export interface RemoteOAuthConfigDiagnostics {
+    config: RemoteOAuthConfig;
+    status: RemoteOAuthConfigStatus;
+    configured: boolean;
+    issues: string[];
+}
+export declare function diagnoseRemoteOAuthConfig(logger?: Logger, env?: NodeJS.ProcessEnv): RemoteOAuthConfigDiagnostics;
 export declare function loadRemoteOAuthConfig(logger?: Logger, env?: NodeJS.ProcessEnv): RemoteOAuthConfig;

package/dist/config.js

@@ -663,11 +663,7 @@ function disabledOAuthConfig(sourcePath = null, 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 ?? {};
+function mergeOAuthEnvOverrides(rawOAuth, env) {
     const envOverrides = [];
     const merged = { ...rawOAuth };
     if (env.LLM_GATEWAY_OAUTH_ENABLED !== undefined) {
@@ -695,43 +691,43 @@ export function loadRemoteOAuthConfig(logger = noopLogger, env = process.env) {
         merged.require_consent = merged.require_consent ?? true;
         envOverrides.push("LLM_GATEWAY_OAUTH_CONSENT_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;
+    return { merged, envOverrides };
+}
+function validateParsedOAuthConfig(data, env, sourcePath, envOverrides, logger, issues) {
     if (data.issuer !== "auto" && !isHttpsOrLoopbackUrl(data.issuer)) {
         logWarn(logger, "Invalid [http.oauth].issuer; remote OAuth disabled");
-        return disabledOAuthConfig(sourcePath, envOverrides);
+        issues.push("OAuth issuer must be an https:// URL (or a loopback URL for local testing).");
+        return null;
     }
     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);
+            issues.push("An OAuth client is missing a client_secret_hash (required when public clients are disabled). Recreate it with `llm-cli-gateway oauth client add`.");
+            return null;
         }
         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);
+            issues.push("An OAuth client secret hash is not a valid scrypt hash. Rotate it with `llm-cli-gateway oauth client rotate`.");
+            return null;
         }
         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);
+            issues.push("An OAuth client has a missing or non-https/loopback redirect URI. Re-add the client with a valid --redirect-uri.");
+            return null;
         }
     }
     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);
+            issues.push("The OAuth shared-secret hash is missing or invalid. Reset it with `llm-cli-gateway oauth shared-secret set`.");
+            return null;
         }
     }
     if (data.registration_policy === "open_dev" && env.LLM_GATEWAY_OAUTH_OPEN_DEV !== "1") {
@@ -740,7 +736,8 @@ export function loadRemoteOAuthConfig(logger = noopLogger, env = process.env) {
     if (data.require_consent) {
         if (!data.consent_secret_hash || !isSecretHash(data.consent_secret_hash)) {
             logWarn(logger, "[http.oauth].require_consent is set but consent_secret_hash is missing/invalid; remote OAuth disabled");
-            return disabledOAuthConfig(sourcePath, envOverrides);
+            issues.push("require_consent is set but the consent secret hash is missing or invalid. Set it with `llm-cli-gateway oauth shared-secret set` or LLM_GATEWAY_OAUTH_CONSENT_SECRET.");
+            return null;
         }
     }
     return {
@@ -769,3 +766,45 @@ export function loadRemoteOAuthConfig(logger = noopLogger, env = process.env) {
         sources: { configFile: sourcePath, envOverrides },
     };
 }
+export function diagnoseRemoteOAuthConfig(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 { merged, envOverrides } = mergeOAuthEnvOverrides(rawOAuth, env);
+    const configured = Object.keys(rawOAuth).length > 0 || envOverrides.length > 0;
+    const parsed = OAuthConfigSchema.safeParse(merged);
+    if (!parsed.success) {
+        logWarn(logger, "Invalid [http.oauth] config; remote OAuth disabled", {
+            error: parsed.error.message,
+        });
+        return {
+            config: disabledOAuthConfig(sourcePath, envOverrides),
+            status: "malformed",
+            configured: true,
+            issues: [
+                "The [http.oauth] config is invalid (schema validation failed); remote OAuth is disabled.",
+            ],
+        };
+    }
+    const data = parsed.data;
+    const issues = [];
+    const built = validateParsedOAuthConfig(data, env, sourcePath, envOverrides, logger, issues);
+    if (!built) {
+        return {
+            config: disabledOAuthConfig(sourcePath, envOverrides),
+            status: data.enabled ? "malformed" : configured ? "disabled" : "absent",
+            configured,
+            issues: data.enabled ? issues : [],
+        };
+    }
+    const status = built.enabled
+        ? "enabled"
+        : configured
+            ? "disabled"
+            : "absent";
+    return { config: built, status, configured, issues: [] };
+}
+export function loadRemoteOAuthConfig(logger = noopLogger, env = process.env) {
+    return diagnoseRemoteOAuthConfig(logger, env).config;
+}

package/dist/connector-setup.d.ts

@@ -0,0 +1,39 @@
+import { type RemoteHttpOAuthReadiness } from "./doctor.js";
+import type { RemoteOAuthConfig } from "./auth.js";
+export declare const CONNECTOR_SETUP_SECRET_WARNING = "Never paste gateway bearer tokens, OAuth client secrets, OAuth access tokens, consent/shared secrets, tunnel tokens, or provider credentials into a remote chat transcript. Only the fields in this packet are safe to paste into a connector UI.";
+export interface ConnectorSetupOptions {
+    clientId?: string;
+    includeLegacyNoAuth?: boolean;
+}
+export interface ConnectorSetupPacket {
+    ok: boolean;
+    schema: "remote-connector-setup.v1";
+    ready: boolean;
+    stage: RemoteHttpOAuthReadiness["stage"];
+    auth_mode: RemoteHttpOAuthReadiness["auth_mode"];
+    connector: {
+        mcp_url: string | null;
+        authorization_url: string | null;
+        token_url: string | null;
+        client_id: string | null;
+        client_secret_required: boolean;
+        client_secret_source: string | null;
+    };
+    workspace: RemoteHttpOAuthReadiness["workspace"];
+    next_actions: string[];
+    warnings: string[];
+    legacy_no_auth?: {
+        deprecated: true;
+        connector_url: string | null;
+        note: string;
+    };
+}
+export declare function buildConnectorSetupPacket(input: {
+    readiness: RemoteHttpOAuthReadiness;
+    oauth: RemoteOAuthConfig;
+    options?: ConnectorSetupOptions;
+    legacyNoAuthUrl?: string | null;
+}): ConnectorSetupPacket;
+export declare function legacyNoAuthConnectorUrl(env?: NodeJS.ProcessEnv): string | null;
+export declare function gatherConnectorSetupPacket(options?: ConnectorSetupOptions, env?: NodeJS.ProcessEnv): ConnectorSetupPacket;
+export declare function renderConnectorSetupSummary(packet: ConnectorSetupPacket): string;

package/dist/connector-setup.js

@@ -0,0 +1,86 @@
+import { gatherRemoteHttpOAuthReadiness } from "./doctor.js";
+import { diagnoseRemoteOAuthConfig } from "./config.js";
+import { joinBaseAndPath, resolveConfiguredRemoteOrigin } from "./remote-url.js";
+export const CONNECTOR_SETUP_SECRET_WARNING = "Never paste gateway bearer tokens, OAuth client secrets, OAuth access tokens, consent/shared secrets, tunnel tokens, or provider credentials into a remote chat transcript. Only the fields in this packet are safe to paste into a connector UI.";
+export function buildConnectorSetupPacket(input) {
+    const { readiness, oauth } = input;
+    const options = input.options ?? {};
+    const configuredClientId = oauth.clients[0]?.clientId ?? null;
+    const clientId = options.clientId ?? configuredClientId;
+    const clientSecretRequired = oauth.enabled && !oauth.allowPublicClients;
+    const clientSecretSource = clientSecretRequired
+        ? "Run `llm-cli-gateway oauth client add <client-id> --redirect-uri <connector-callback> --print-once` (or `oauth client rotate <client-id> --print-once`) and paste the printed secret once into the connector UI."
+        : null;
+    const packet = {
+        ok: true,
+        schema: "remote-connector-setup.v1",
+        ready: readiness.ready,
+        stage: readiness.stage,
+        auth_mode: readiness.auth_mode,
+        connector: {
+            mcp_url: readiness.mcp_url,
+            authorization_url: readiness.oauth.authorization_url,
+            token_url: readiness.oauth.token_url,
+            client_id: clientId,
+            client_secret_required: clientSecretRequired,
+            client_secret_source: clientSecretSource,
+        },
+        workspace: readiness.workspace,
+        next_actions: readiness.next_actions,
+        warnings: [CONNECTOR_SETUP_SECRET_WARNING],
+    };
+    if (options.includeLegacyNoAuth) {
+        packet.legacy_no_auth = {
+            deprecated: true,
+            connector_url: input.legacyNoAuthUrl ?? null,
+            note: "Deprecated no-auth connector URL. It bypasses authentication; prefer OAuth. Do not share this URL.",
+        };
+    }
+    return packet;
+}
+export function legacyNoAuthConnectorUrl(env = process.env) {
+    const noAuthPath = (env.LLM_GATEWAY_NO_AUTH_PATHS || "")
+        .split(/[,;\s]+/)
+        .map(value => value.trim())
+        .find(value => value.startsWith("/") && !value.includes("?") && !value.includes("#"));
+    if (!noAuthPath)
+        return null;
+    const baseOrigin = resolveConfiguredRemoteOrigin({
+        publicUrl: env.LLM_GATEWAY_PUBLIC_URL ?? null,
+    });
+    if (!baseOrigin)
+        return null;
+    return joinBaseAndPath(baseOrigin, noAuthPath);
+}
+export function gatherConnectorSetupPacket(options = {}, env = process.env) {
+    const readiness = gatherRemoteHttpOAuthReadiness(env);
+    const oauth = diagnoseRemoteOAuthConfig(undefined, env).config;
+    const legacyNoAuthUrl = options.includeLegacyNoAuth ? legacyNoAuthConnectorUrl(env) : null;
+    return buildConnectorSetupPacket({ readiness, oauth, options, legacyNoAuthUrl });
+}
+export function renderConnectorSetupSummary(packet) {
+    const lines = [];
+    lines.push(`Remote connector readiness: ${packet.stage}${packet.ready ? " (ready)" : ""}`);
+    lines.push(`Authentication mode: ${packet.auth_mode}`);
+    if (packet.connector.mcp_url)
+        lines.push(`MCP URL:            ${packet.connector.mcp_url}`);
+    if (packet.connector.authorization_url)
+        lines.push(`Authorization URL:  ${packet.connector.authorization_url}`);
+    if (packet.connector.token_url)
+        lines.push(`Token URL:          ${packet.connector.token_url}`);
+    if (packet.connector.client_id)
+        lines.push(`Client ID:          ${packet.connector.client_id}`);
+    if (packet.connector.client_secret_required && packet.connector.client_secret_source) {
+        lines.push(`Client secret:      ${packet.connector.client_secret_source}`);
+    }
+    lines.push(`Workspace:          ${packet.workspace.ready
+        ? `ready (default: ${packet.workspace.default ?? "none, pass a registered alias"})`
+        : "not ready"}`);
+    if (packet.next_actions.length > 0) {
+        lines.push("Next actions:");
+        for (const action of packet.next_actions)
+            lines.push(`  - ${action}`);
+    }
+    lines.push(packet.warnings[0] ?? CONNECTOR_SETUP_SECRET_WARNING);
+    return lines.join("\n");
+}

package/dist/doctor.d.ts

@@ -2,7 +2,9 @@ import { type EndpointExposureReport } from "./endpoint-exposure.js";
 import { type ProviderLoginStatus } from "./provider-status.js";
 import { type ApiProviderLoginGuidance } from "./provider-login-guidance.js";
 import type { FlightRecorderQuery } from "./flight-recorder.js";
-import { type CacheAwarenessConfig, type ProvidersConfig } from "./config.js";
+import { type CacheAwarenessConfig, type ProvidersConfig, type RemoteOAuthConfigDiagnostics } from "./config.js";
+import type { AuthConfig } from "./auth.js";
+import { type RemoteSafeWorkspaceSummary } from "./workspace-registry.js";
 import { type ProviderCapabilityId, type ProviderKind } from "./provider-tool-capabilities.js";
 import { type CliType } from "./session-manager.js";
 export interface CacheAwarenessReport {
@@ -146,6 +148,7 @@ export interface DoctorReport {
         };
     }>;
     endpoint_exposure: EndpointExposureReport;
+    remote_http_oauth: RemoteHttpOAuthReadiness;
     client_config: {
         claude_desktop_config_present: boolean;
         codex_config_present: boolean;
@@ -167,6 +170,41 @@ export interface DoctorReport {
     };
     next_actions: string[];
 }
+export type RemoteHttpOAuthStage = "not_started" | "missing_public_url" | "endpoint_unreachable" | "oauth_disabled" | "unsafe_oauth_config" | "missing_oauth_client" | "missing_workspace" | "ready";
+export declare const REMOTE_HTTP_OAUTH_STAGES: readonly RemoteHttpOAuthStage[];
+export interface RemoteHttpOAuthReadiness {
+    ready: boolean;
+    stage: RemoteHttpOAuthStage;
+    public_url: string | null;
+    mcp_url: string | null;
+    auth_mode: "oauth" | "bearer_token" | "none";
+    oauth: {
+        enabled: boolean;
+        issuer: string | null;
+        authorization_url: string | null;
+        token_url: string | null;
+        registration_policy: string;
+        clients_configured: number;
+        consent_required: boolean;
+    };
+    workspace: {
+        ready: boolean;
+        default: string | null;
+        aliases: string[];
+    };
+    next_actions: string[];
+}
+export interface RemoteHttpOAuthReadinessInput {
+    oauthDiag: Pick<RemoteOAuthConfigDiagnostics, "status" | "config" | "issues">;
+    workspace: RemoteSafeWorkspaceSummary;
+    auth: AuthConfig;
+    transport: "stdio" | "http";
+    publicUrl: string | null;
+    endpoint: EndpointExposureReport;
+    mcpPath: string;
+}
+export declare function buildRemoteHttpOAuthReadiness(input: RemoteHttpOAuthReadinessInput): RemoteHttpOAuthReadiness;
+export declare function gatherRemoteHttpOAuthReadiness(env?: NodeJS.ProcessEnv): RemoteHttpOAuthReadiness;
 export interface CreateDoctorReportOptions {
     env?: NodeJS.ProcessEnv;
     flightRecorder?: FlightRecorderQuery;

package/dist/doctor.js

@@ -7,8 +7,9 @@ import { createEndpointExposureReport, redactDiagnosticUrl, } from "./endpoint-e
 import { getApiProviderStatus, listProviderRuntimeStatuses, } from "./provider-status.js";
 import { getApiProviderLoginGuidance, } from "./provider-login-guidance.js";
 import { CLAUDE_MCP_SERVER_NAMES } from "./claude-mcp-config.js";
-import { enabledApiProviders, loadCacheAwarenessConfig, loadProvidersConfig, loadRemoteOAuthConfig, } from "./config.js";
-import { loadWorkspaceRegistry } from "./workspace-registry.js";
+import { diagnoseRemoteOAuthConfig, enabledApiProviders, loadCacheAwarenessConfig, loadProvidersConfig, } from "./config.js";
+import { loadWorkspaceRegistry, remoteSafeWorkspaceSummary, } from "./workspace-registry.js";
+import { buildRemoteConnectorUrls, resolveConfiguredRemoteOrigin } from "./remote-url.js";
 import { computeGlobalCacheStats } from "./cache-stats.js";
 import { FlightRecorder, resolveFlightRecorderDbPath } from "./flight-recorder.js";
 import { buildUpstreamContractReport } from "./upstream-contracts.js";
@@ -136,6 +137,174 @@ export function checkGeminiConfig(cwd = process.cwd(), home = homedir(), whiteli
         next_actions: nextActions,
     };
 }
+export const REMOTE_HTTP_OAUTH_STAGES = [
+    "not_started",
+    "missing_public_url",
+    "endpoint_unreachable",
+    "oauth_disabled",
+    "unsafe_oauth_config",
+    "missing_oauth_client",
+    "missing_workspace",
+    "ready",
+];
+export function buildRemoteHttpOAuthReadiness(input) {
+    const { config: oauth, status, issues } = input.oauthDiag;
+    const e = input.endpoint;
+    const baseOrigin = resolveConfiguredRemoteOrigin({
+        issuer: oauth.issuer === "auto" ? null : redactDiagnosticUrl(oauth.issuer),
+        publicUrl: input.publicUrl,
+    });
+    const urls = buildRemoteConnectorUrls({
+        baseOrigin,
+        mcpPath: input.mcpPath,
+        oauthEnabled: oauth.enabled,
+    });
+    const hasValidPublicHttpsUrl = e.public_url_configured &&
+        e.https_configured &&
+        (e.mode === "tunnel" || e.mode === "byo_reverse_proxy");
+    const oauthNotEnabled = status === "absent" || status === "disabled";
+    const oauthUnsafeForRemote = status === "malformed" ||
+        (oauth.enabled && (oauth.allowPublicClients || oauth.registrationPolicy === "open_dev"));
+    let stage;
+    if (!e.public_url_configured && input.transport !== "http" && status === "absent") {
+        stage = "not_started";
+    }
+    else if (!hasValidPublicHttpsUrl) {
+        stage = "missing_public_url";
+    }
+    else if (e.reachable_from_web === "unreachable") {
+        stage = "endpoint_unreachable";
+    }
+    else if (oauthNotEnabled) {
+        stage = "oauth_disabled";
+    }
+    else if (oauthUnsafeForRemote) {
+        stage = "unsafe_oauth_config";
+    }
+    else if (oauth.registrationPolicy === "static_clients" && oauth.clients.length === 0) {
+        stage = "missing_oauth_client";
+    }
+    else if (!input.workspace.ready) {
+        stage = "missing_workspace";
+    }
+    else {
+        stage = "ready";
+    }
+    const authMode = oauth.enabled
+        ? "oauth"
+        : input.auth.required && input.auth.tokenConfigured
+            ? "bearer_token"
+            : "none";
+    return {
+        ready: stage === "ready",
+        stage,
+        public_url: input.publicUrl,
+        mcp_url: urls.mcpUrl,
+        auth_mode: authMode,
+        oauth: {
+            enabled: oauth.enabled,
+            issuer: urls.issuer,
+            authorization_url: urls.authorizationUrl,
+            token_url: urls.tokenUrl,
+            registration_policy: oauth.registrationPolicy,
+            clients_configured: oauth.clients.length,
+            consent_required: oauth.requireConsent,
+        },
+        workspace: {
+            ready: input.workspace.ready,
+            default: input.workspace.default,
+            aliases: input.workspace.aliases,
+        },
+        next_actions: remoteReadinessNextActions(stage, {
+            oauth,
+            status,
+            issues,
+            workspace: input.workspace,
+            endpointReachability: e.reachable_from_web,
+        }),
+    };
+}
+function remoteReadinessNextActions(stage, ctx) {
+    switch (stage) {
+        case "not_started":
+            return [
+                "Remote HTTP + OAuth setup has not started. Start an HTTPS tunnel or reverse proxy and set LLM_GATEWAY_PUBLIC_URL to the public https URL.",
+                "Then register an OAuth client: llm-cli-gateway oauth client add <client-id> --redirect-uri <connector-callback> --print-once",
+            ];
+        case "missing_public_url":
+            return [
+                "Set LLM_GATEWAY_PUBLIC_URL to a public https URL (tunnel or reverse proxy), not localhost or a LAN address.",
+                "Re-run: llm-cli-gateway doctor --json",
+            ];
+        case "endpoint_unreachable":
+            return [
+                "The public MCP URL is configured but not reachable from the web. Fix tunnel/reverse-proxy routing, then re-run: llm-cli-gateway doctor --json",
+            ];
+        case "oauth_disabled":
+            return [
+                "OAuth is the recommended remote connector authentication mode. Enable it by registering a client: llm-cli-gateway oauth client add <client-id> --redirect-uri <connector-callback> --print-once",
+            ];
+        case "unsafe_oauth_config": {
+            const reasons = [];
+            if (ctx.status === "malformed") {
+                reasons.push(...(ctx.issues.length
+                    ? ctx.issues
+                    : ["The [http.oauth] config is invalid; fix it and re-run doctor --json."]));
+            }
+            else {
+                if (ctx.oauth.allowPublicClients) {
+                    reasons.push("OAuth allow_public_clients is enabled on a public endpoint. Use confidential clients: registration_policy=static_clients with a client secret.");
+                }
+                if (ctx.oauth.registrationPolicy === "open_dev") {
+                    reasons.push("OAuth registration_policy=open_dev is unsafe on a public endpoint. Switch to static_clients with confidential client secrets.");
+                }
+            }
+            reasons.push("Re-run: llm-cli-gateway doctor --json");
+            return reasons;
+        }
+        case "missing_oauth_client":
+            return [
+                "OAuth is enabled but no client is registered. Add one: llm-cli-gateway oauth client add <client-id> --redirect-uri <connector-callback> --print-once",
+            ];
+        case "missing_workspace":
+            return [
+                "No workspace is available for remote provider execution. Register a repo and set it as the default: add a [[workspaces.repos]] entry with [workspaces].default in ~/.llm-cli-gateway/config.toml, or run `llm-cli-gateway workspace add <alias> <absolute-repo-path> --default` when an allowed root is configured.",
+                "Remote clients then select the workspace by alias; local absolute paths are never accepted from remote clients.",
+            ];
+        case "ready": {
+            const readyActions = [
+                ctx.workspace.default
+                    ? `Remote connector is ready. Remote provider calls use the default workspace "${ctx.workspace.default}" unless a registered alias is supplied.`
+                    : "Remote connector is ready. Remote provider calls must supply a registered workspace alias; set a default with `llm-cli-gateway workspace add <alias> <path> --default` to make one implicit.",
+                "Paste only copy-safe connector fields (MCP URL, authorization URL, token URL, client id) into the remote connector UI.",
+            ];
+            if (ctx.endpointReachability === "not_checked") {
+                readyActions.push("Config is complete but public reachability was not verified. Set LLM_GATEWAY_VERIFY_PUBLIC_URL=1 and re-run doctor --json to confirm the public URL is reachable from the web.");
+            }
+            return readyActions;
+        }
+        default:
+            return [];
+    }
+}
+export function gatherRemoteHttpOAuthReadiness(env = process.env) {
+    const oauthDiag = diagnoseRemoteOAuthConfig(undefined, env);
+    const workspace = remoteSafeWorkspaceSummary(loadWorkspaceRegistry());
+    const auth = loadAuthConfig(env);
+    const transport = defaultTransport(env);
+    const publicUrl = redactDiagnosticUrl(env.LLM_GATEWAY_PUBLIC_URL || null);
+    const endpoint = createEndpointExposureReport(env, publicUrl);
+    const mcpPath = env.LLM_GATEWAY_HTTP_PATH || "/mcp";
+    return buildRemoteHttpOAuthReadiness({
+        oauthDiag,
+        workspace,
+        auth,
+        transport,
+        publicUrl,
+        endpoint,
+        mcpPath,
+    });
+}
 function packageVersion() {
     const here = dirname(fileURLToPath(import.meta.url));
     const candidates = [join(here, "..", "package.json"), join(here, "..", "..", "package.json")];
@@ -306,7 +475,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 oauthDiag = diagnoseRemoteOAuthConfig(undefined, env);
+    const oauth = oauthDiag.config;
     const workspaceRegistry = loadWorkspaceRegistry();
     const transport = defaultTransport(env);
     const rawPublicUrl = env.LLM_GATEWAY_PUBLIC_URL || null;
@@ -382,6 +552,15 @@ export function createDoctorReport(envOrOptions = process.env) {
         },
         providers: Object.fromEntries(CLI_TYPES.map(provider => [provider, doctorProviderStatus(providerStatuses[provider])])),
         endpoint_exposure: endpointExposure,
+        remote_http_oauth: buildRemoteHttpOAuthReadiness({
+            oauthDiag,
+            workspace: remoteSafeWorkspaceSummary(workspaceRegistry),
+            auth,
+            transport,
+            publicUrl,
+            endpoint: endpointExposure,
+            mcpPath: env.LLM_GATEWAY_HTTP_PATH || "/mcp",
+        }),
         client_config: clientConfigStatus(),
         cache_awareness: buildCacheAwarenessReport(opts),
         provider_capabilities: buildProviderCapabilitySummary(providerStatuses),

package/dist/http-transport.js

@@ -57,6 +57,27 @@ function isLocalHost(host) {
     const hostname = host.split(":")[0]?.toLowerCase() ?? "";
     return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
 }
+function isLoopbackHostname(hostname) {
+    const h = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    return h === "localhost" || h === "::1" || /^127\./.test(h);
+}
+function isPubliclyExposed(env, host) {
+    if (!isLocalHost(host))
+        return true;
+    if (env.LLM_GATEWAY_TUNNEL_PROVIDER && env.LLM_GATEWAY_TUNNEL_PROVIDER.trim().length > 0) {
+        return true;
+    }
+    const publicUrl = env.LLM_GATEWAY_PUBLIC_URL;
+    if (publicUrl && publicUrl.trim().length > 0) {
+        try {
+            if (!isLoopbackHostname(new URL(publicUrl).hostname))
+                return true;
+        }
+        catch {
+        }
+    }
+    return false;
+}
 function requestBaseUrl(req) {
     const configured = process.env.LLM_GATEWAY_PUBLIC_URL;
     if (configured) {
@@ -85,9 +106,12 @@ export async function startHttpGateway(options) {
     const oauthConfig = loadRemoteOAuthConfig(logger);
     if (oauthConfig.enabled &&
         (oauthConfig.allowPublicClients || oauthConfig.registrationPolicy === "open_dev") &&
-        !isLocalHost(host)) {
-        throw new Error(`Refusing to start: remote OAuth with ${oauthConfig.allowPublicClients ? "public clients" : "open_dev registration"} is exposed on a non-loopback bind (host=${host}). Bind LLM_GATEWAY_HTTP_HOST to 127.0.0.1 ` +
-            `and front the gateway with an authenticating proxy, or switch to ` +
+        isPubliclyExposed(process.env, host)) {
+        const exposure = !isLocalHost(host)
+            ? `a non-loopback bind (host=${host})`
+            : "a public URL / tunnel (LLM_GATEWAY_PUBLIC_URL or LLM_GATEWAY_TUNNEL_PROVIDER)";
+        throw new Error(`Refusing to start: remote OAuth with ${oauthConfig.allowPublicClients ? "public clients" : "open_dev registration"} is exposed via ${exposure}. A loopback bind fronted by a public tunnel is still ` +
+            `publicly reachable. Front the gateway with an authenticating proxy, or switch to ` +
             `registration_policy=static_clients with confidential client secrets.`);
     }
     const oauthServer = oauthConfig.enabled

package/dist/index.d.ts

@@ -120,6 +120,7 @@ export declare function resolveWorktreeForRequest(worktreeOpt: boolean | {
     workspaceRoot?: string;
 }): Promise<ResolvedWorktree>;
 export declare function formatWorktreePrefix(worktreePath?: string): string;
+export declare function remoteSafeWorktreePath(worktreePath?: string, workspaceRoot?: string): string | undefined;
 export declare function createErrorResponse(cli: string, code: number, stderr: string, correlationId?: string, error?: Error, apiError?: {
     httpStatus?: number | null;
     responseBody?: string;