fix(env): surface CLERK_PLATFORM_API_URL credential mismatch

CLERK_PLATFORM_API_URL redirects API traffic to an arbitrary host, but
credentials are keyed by environment name, not by URL, so the active env's
token is sent to the override host with no isolation. Warn about this in human
mode (agent/scripted output stays clean), and report the active environment and
API URL in clerk doctor so the mismatch is visible.

Refs #329

Author: rafa-thayto

.changeset/platform-api-url-credential-warning.md

@@ -0,0 +1,5 @@
+---
+"clerk": patch
+---
+
+Warn (in human mode) when `CLERK_PLATFORM_API_URL` routes requests to a host that differs from the active environment's URL, since credentials are keyed by environment name and not by URL. `clerk doctor` now also reports the active environment and its API URL so the mismatch is visible.

packages/cli-core/src/cli-program.ts

@@ -26,6 +26,7 @@ import {
   getCurrentEnvName,
   getAvailableEnvs,
   getPlapiBaseUrl,
+  warnIfPlatformApiUrlOverride,
 } from "./lib/environment.ts";
 import {
   CliError,
@@ -129,6 +130,8 @@ export function createProgram(): Program {
     if (activeEnv !== "production") {
       process.stderr.write(`[${activeEnv.toUpperCase()}]\n`);
     }
+
+    warnIfPlatformApiUrlOverride();
   });
 
   // Show update notification after each command, except for commands that

packages/cli-core/src/commands/doctor/checks.ts

@@ -16,6 +16,7 @@ import {
   formatChannelLabel,
 } from "../../lib/update-check.ts";
 import { formatHostStateProbeFailures, getAgentHostStateProbe } from "../../lib/host-execution.ts";
+import { getCurrentEnvName, getPlapiBaseUrl } from "../../lib/environment.ts";
 import { isAgent } from "../../mode.ts";
 import type { CheckResult, DoctorContext, FixAction } from "./types.ts";
 
@@ -74,7 +75,7 @@ export async function checkLoggedIn(ctx: DoctorContext): Promise<CheckResult> {
       remedy: "Run `clerk auth login` to authenticate.",
     });
   }
-  return check.pass("Logged in (token found in credential store)");
+  return check.pass(`Logged in — environment "${getCurrentEnvName()}", API ${getPlapiBaseUrl()}`);
 }
 
 export async function checkHostExecution(): Promise<CheckResult> {

packages/cli-core/src/lib/environment.test.ts

@@ -0,0 +1,46 @@
+import { test, expect, describe, beforeEach, afterEach } from "bun:test";
+import { getPlapiBaseUrl, warnIfPlatformApiUrlOverride } from "./environment.ts";
+import { setMode } from "../mode.ts";
+import { useCaptureLog } from "../test/lib/stubs.ts";
+
+describe("warnIfPlatformApiUrlOverride", () => {
+  const captured = useCaptureLog();
+  const original = process.env.CLERK_PLATFORM_API_URL;
+
+  beforeEach(() => {
+    setMode("human");
+    delete process.env.CLERK_PLATFORM_API_URL;
+  });
+
+  afterEach(() => {
+    setMode("human");
+    if (original === undefined) delete process.env.CLERK_PLATFORM_API_URL;
+    else process.env.CLERK_PLATFORM_API_URL = original;
+  });
+
+  test("warns in human mode when the override differs from the active env URL", () => {
+    process.env.CLERK_PLATFORM_API_URL = "https://api.staging.example.com";
+    warnIfPlatformApiUrlOverride();
+    expect(captured.err).toContain("CLERK_PLATFORM_API_URL");
+    expect(captured.err).toContain("production");
+  });
+
+  test("does not warn when no override is set", () => {
+    warnIfPlatformApiUrlOverride();
+    expect(captured.err).not.toContain("CLERK_PLATFORM_API_URL");
+  });
+
+  test("does not warn when the override equals the active env URL", () => {
+    const profileUrl = getPlapiBaseUrl(); // no override set → active env URL
+    process.env.CLERK_PLATFORM_API_URL = profileUrl;
+    warnIfPlatformApiUrlOverride();
+    expect(captured.err).not.toContain("CLERK_PLATFORM_API_URL");
+  });
+
+  test("stays silent in agent mode to avoid corrupting machine-readable output", () => {
+    setMode("agent");
+    process.env.CLERK_PLATFORM_API_URL = "https://api.staging.example.com";
+    warnIfPlatformApiUrlOverride();
+    expect(captured.err).not.toContain("CLERK_PLATFORM_API_URL");
+  });
+});

packages/cli-core/src/lib/environment.ts

@@ -11,6 +11,7 @@
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { isHuman } from "../mode.ts";
 import { log } from "./log.ts";
 
 export interface EnvProfileConfig {
@@ -136,6 +137,27 @@ export function getPlapiBaseUrl(): string {
   return process.env.CLERK_PLATFORM_API_URL ?? getCurrentEnv().platformApiUrl;
 }
 
+/**
+ * Warn when CLERK_PLATFORM_API_URL redirects requests to a host that differs
+ * from the active environment's platform URL. Credentials are keyed by
+ * environment name, not by URL, so the active env's token is what gets sent to
+ * the override host — surface that so it isn't a silent surprise.
+ *
+ * Human mode only: a per-command warning line would corrupt the machine-readable
+ * stderr that agent mode emits. Agent/scripted callers get the same information
+ * from the `clerk doctor` environment report instead.
+ */
+export function warnIfPlatformApiUrlOverride(): void {
+  if (!isHuman()) return;
+  const override = process.env.CLERK_PLATFORM_API_URL;
+  if (!override) return;
+  const envName = getCurrentEnvName();
+  if (override === getCurrentEnv().platformApiUrl) return;
+  log.warn(
+    `CLERK_PLATFORM_API_URL is routing requests to ${override}, but credentials stay keyed to the "${envName}" environment — the "${envName}" token will be sent to that host.`,
+  );
+}
+
 export function getBapiBaseUrl(): string {
   return process.env.CLERK_BACKEND_API_URL ?? getCurrentEnv().backendApiUrl;
 }