llm-cli-gateway 2.13.0 → 2.13.2

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

@@ -38,11 +38,11 @@ type ExtendedToolResponse = {
     reviewIntegrity?: ReviewIntegrityResult;
     warnings?: WarningEntry[];
 };
-declare const logger: {
-    info: (message: string, ...args: any[]) => void;
-    warn: (message: string, ...args: any[]) => void;
-    error: (message: string, ...args: any[]) => void;
-    debug: (message: string, ...args: any[]) => void;
+export declare const logger: {
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+    debug: (message: string, ...args: unknown[]) => void;
 };
 type GatewayLogger = typeof logger;
 export declare function buildServerInstructions(asyncJobsEnabled: boolean, grokApiToolsEnabled?: boolean): string;
@@ -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;