From 627fd6b65b4faf36ccc72ba4fd992d49376a88c4 Mon Sep 17 00:00:00 2001 From: Rafael Thayto Date: Tue, 16 Jun 2026 20:07:20 -0300 Subject: [PATCH 1/3] 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 --- .../platform-api-url-credential-warning.md | 5 ++ packages/cli-core/src/cli-program.ts | 3 ++ .../cli-core/src/commands/doctor/checks.ts | 3 +- packages/cli-core/src/lib/environment.test.ts | 46 +++++++++++++++++++ packages/cli-core/src/lib/environment.ts | 22 +++++++++ 5 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 .changeset/platform-api-url-credential-warning.md create mode 100644 packages/cli-core/src/lib/environment.test.ts diff --git a/.changeset/platform-api-url-credential-warning.md b/.changeset/platform-api-url-credential-warning.md new file mode 100644 index 00000000..a34a0185 --- /dev/null +++ b/.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. diff --git a/packages/cli-core/src/cli-program.ts b/packages/cli-core/src/cli-program.ts index a8e7f113..b81c1cc9 100644 --- a/packages/cli-core/src/cli-program.ts +++ b/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 diff --git a/packages/cli-core/src/commands/doctor/checks.ts b/packages/cli-core/src/commands/doctor/checks.ts index b8bf9afa..53929eec 100644 --- a/packages/cli-core/src/commands/doctor/checks.ts +++ b/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 { 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 { diff --git a/packages/cli-core/src/lib/environment.test.ts b/packages/cli-core/src/lib/environment.test.ts new file mode 100644 index 00000000..59531c8a --- /dev/null +++ b/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"); + }); +}); diff --git a/packages/cli-core/src/lib/environment.ts b/packages/cli-core/src/lib/environment.ts index 91643a28..a77c8fa8 100644 --- a/packages/cli-core/src/lib/environment.ts +++ b/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; } From e59876a847d0bcd9c08a0097975420a1bd194db0 Mon Sep 17 00:00:00 2001 From: Rafael Thayto Date: Thu, 18 Jun 2026 09:15:30 -0300 Subject: [PATCH 2/3] fix(env): normalize URLs before comparing to avoid spurious mismatch warnings Use new URL().href to normalize both the override and profile URL before comparing, so trailing slashes and host-case differences don't produce false positives. Falls back to raw string comparison when either URL is malformed. Also pin the test to a concrete literal ("https://api.clerk.com") instead of the self-referencing getPlapiBaseUrl() call, and strengthen the positive warning case by asserting the override host appears in the message. --- packages/cli-core/src/lib/environment.test.ts | 6 +++--- packages/cli-core/src/lib/environment.ts | 9 ++++++++- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/packages/cli-core/src/lib/environment.test.ts b/packages/cli-core/src/lib/environment.test.ts index 59531c8a..56ec3adb 100644 --- a/packages/cli-core/src/lib/environment.test.ts +++ b/packages/cli-core/src/lib/environment.test.ts @@ -1,5 +1,5 @@ import { test, expect, describe, beforeEach, afterEach } from "bun:test"; -import { getPlapiBaseUrl, warnIfPlatformApiUrlOverride } from "./environment.ts"; +import { warnIfPlatformApiUrlOverride } from "./environment.ts"; import { setMode } from "../mode.ts"; import { useCaptureLog } from "../test/lib/stubs.ts"; @@ -23,6 +23,7 @@ describe("warnIfPlatformApiUrlOverride", () => { warnIfPlatformApiUrlOverride(); expect(captured.err).toContain("CLERK_PLATFORM_API_URL"); expect(captured.err).toContain("production"); + expect(captured.err).toContain("api.staging.example.com"); }); test("does not warn when no override is set", () => { @@ -31,8 +32,7 @@ describe("warnIfPlatformApiUrlOverride", () => { }); 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; + process.env.CLERK_PLATFORM_API_URL = "https://api.clerk.com"; warnIfPlatformApiUrlOverride(); expect(captured.err).not.toContain("CLERK_PLATFORM_API_URL"); }); diff --git a/packages/cli-core/src/lib/environment.ts b/packages/cli-core/src/lib/environment.ts index a77c8fa8..8c7f6ccc 100644 --- a/packages/cli-core/src/lib/environment.ts +++ b/packages/cli-core/src/lib/environment.ts @@ -152,7 +152,14 @@ export function warnIfPlatformApiUrlOverride(): void { const override = process.env.CLERK_PLATFORM_API_URL; if (!override) return; const envName = getCurrentEnvName(); - if (override === getCurrentEnv().platformApiUrl) return; + const normalize = (u: string) => { + try { + return new URL(u).href; + } catch { + return u; + } + }; + if (normalize(override) === normalize(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.`, ); From 39bbf59d74658bb0a665a815f293dd79acd0cab1 Mon Sep 17 00:00:00 2001 From: Rafael Thayto Date: Mon, 22 Jun 2026 17:47:51 -0300 Subject: [PATCH 3/3] refactor(env): extract isPlatformApiUrlOverridden and move warn to call site Export `isPlatformApiUrlOverridden()` from environment.ts that returns the override/profile URLs and env name as data, rather than emitting the warning itself. Move the `log.warn` call to the preAction hook in cli-program.ts so the decision of whether/how to warn is at the call site, and so warnings go to stderr unconditionally (not just in human mode) since machine-readable stdout data is never polluted by stderr. Update integration tests to extract the JSON line from stderr before parsing so the warning line doesn't break `JSON.parse(result.stderr)`. --- packages/cli-core/src/cli-program.ts | 13 +++++- packages/cli-core/src/lib/environment.test.ts | 42 +++++++++---------- packages/cli-core/src/lib/environment.ts | 39 ++++++++++------- .../src/test/integration/error-codes.test.ts | 7 +++- .../src/test/integration/input-json.test.ts | 19 ++++++--- 5 files changed, 73 insertions(+), 47 deletions(-) diff --git a/packages/cli-core/src/cli-program.ts b/packages/cli-core/src/cli-program.ts index b81c1cc9..85300be2 100644 --- a/packages/cli-core/src/cli-program.ts +++ b/packages/cli-core/src/cli-program.ts @@ -26,7 +26,7 @@ import { getCurrentEnvName, getAvailableEnvs, getPlapiBaseUrl, - warnIfPlatformApiUrlOverride, + isPlatformApiUrlOverridden, } from "./lib/environment.ts"; import { CliError, @@ -131,7 +131,16 @@ export function createProgram(): Program { process.stderr.write(`[${activeEnv.toUpperCase()}]\n`); } - warnIfPlatformApiUrlOverride(); + // Warn when CLERK_PLATFORM_API_URL routes requests to a different host than + // the active environment's platform URL. Credentials are keyed by environment + // name, so the active env's token will be sent to the override host. Emitted + // to stderr so it never corrupts stdout data output. + const override = isPlatformApiUrlOverridden(); + if (override.overridden) { + log.warn( + `CLERK_PLATFORM_API_URL is routing requests to ${override.overrideUrl}, but credentials stay keyed to the "${override.envName}" environment — the "${override.envName}" token will be sent to that host.`, + ); + } }); // Show update notification after each command, except for commands that diff --git a/packages/cli-core/src/lib/environment.test.ts b/packages/cli-core/src/lib/environment.test.ts index 56ec3adb..827c51e1 100644 --- a/packages/cli-core/src/lib/environment.test.ts +++ b/packages/cli-core/src/lib/environment.test.ts @@ -1,46 +1,42 @@ import { test, expect, describe, beforeEach, afterEach } from "bun:test"; -import { warnIfPlatformApiUrlOverride } from "./environment.ts"; -import { setMode } from "../mode.ts"; -import { useCaptureLog } from "../test/lib/stubs.ts"; +import { isPlatformApiUrlOverridden } from "./environment.ts"; -describe("warnIfPlatformApiUrlOverride", () => { - const captured = useCaptureLog(); +describe("isPlatformApiUrlOverridden", () => { 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", () => { + test("returns overridden=true with URLs 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"); - expect(captured.err).toContain("api.staging.example.com"); + const result = isPlatformApiUrlOverridden(); + expect(result.overridden).toBe(true); + if (!result.overridden) return; + expect(result.overrideUrl).toBe("https://api.staging.example.com"); + expect(result.profileUrl).toBe("https://api.clerk.com"); + expect(result.envName).toBe("production"); }); - test("does not warn when no override is set", () => { - warnIfPlatformApiUrlOverride(); - expect(captured.err).not.toContain("CLERK_PLATFORM_API_URL"); + test("returns overridden=false when no override is set", () => { + const result = isPlatformApiUrlOverridden(); + expect(result.overridden).toBe(false); }); - test("does not warn when the override equals the active env URL", () => { + test("returns overridden=false when the override equals the active env URL", () => { process.env.CLERK_PLATFORM_API_URL = "https://api.clerk.com"; - warnIfPlatformApiUrlOverride(); - expect(captured.err).not.toContain("CLERK_PLATFORM_API_URL"); + const result = isPlatformApiUrlOverridden(); + expect(result.overridden).toBe(false); }); - 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"); + test("returns overridden=false when URLs differ only by trailing slash", () => { + process.env.CLERK_PLATFORM_API_URL = "https://api.clerk.com/"; + const result = isPlatformApiUrlOverridden(); + expect(result.overridden).toBe(false); }); }); diff --git a/packages/cli-core/src/lib/environment.ts b/packages/cli-core/src/lib/environment.ts index 8c7f6ccc..c7fb9972 100644 --- a/packages/cli-core/src/lib/environment.ts +++ b/packages/cli-core/src/lib/environment.ts @@ -11,7 +11,6 @@ import { readFileSync } from "node:fs"; import { join } from "node:path"; -import { isHuman } from "../mode.ts"; import { log } from "./log.ts"; export interface EnvProfileConfig { @@ -138,20 +137,28 @@ export function getPlapiBaseUrl(): string { } /** - * 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. + * Returns whether CLERK_PLATFORM_API_URL is set to a URL that differs from the + * active environment's configured platform URL, along with both URLs so the + * caller can surface a warning. * - * 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. + * Comparison normalises both URLs via `new URL().href` so trailing-slash and + * case differences are ignored; falls back to raw string comparison if either + * value is not a valid URL. */ -export function warnIfPlatformApiUrlOverride(): void { - if (!isHuman()) return; +export function isPlatformApiUrlOverridden(): + | { + overridden: false; + } + | { + overridden: true; + overrideUrl: string; + profileUrl: string; + envName: string; + } { const override = process.env.CLERK_PLATFORM_API_URL; - if (!override) return; - const envName = getCurrentEnvName(); + if (!override) return { overridden: false }; + + const profileUrl = getCurrentEnv().platformApiUrl; const normalize = (u: string) => { try { return new URL(u).href; @@ -159,10 +166,10 @@ export function warnIfPlatformApiUrlOverride(): void { return u; } }; - if (normalize(override) === normalize(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.`, - ); + + if (normalize(override) === normalize(profileUrl)) return { overridden: false }; + + return { overridden: true, overrideUrl: override, profileUrl, envName: getCurrentEnvName() }; } export function getBapiBaseUrl(): string { diff --git a/packages/cli-core/src/test/integration/error-codes.test.ts b/packages/cli-core/src/test/integration/error-codes.test.ts index 06c81e83..311675df 100644 --- a/packages/cli-core/src/test/integration/error-codes.test.ts +++ b/packages/cli-core/src/test/integration/error-codes.test.ts @@ -9,7 +9,12 @@ import { useIntegrationTestHarness, clerk, mockState } from "./lib/harness.ts"; useIntegrationTestHarness(); function parseJsonError(stderr: string): { code: string; message: string; docsUrl?: string } { - const parsed = JSON.parse(stderr); + const jsonLine = stderr + .split("\n") + .map((l) => l.trim()) + .find((l) => l.startsWith("{")); + if (!jsonLine) throw new SyntaxError(`No JSON line found in stderr:\n${stderr}`); + const parsed = JSON.parse(jsonLine); return parsed.error; } diff --git a/packages/cli-core/src/test/integration/input-json.test.ts b/packages/cli-core/src/test/integration/input-json.test.ts index 0c23560b..13ef9238 100644 --- a/packages/cli-core/src/test/integration/input-json.test.ts +++ b/packages/cli-core/src/test/integration/input-json.test.ts @@ -18,6 +18,15 @@ useIntegrationTestHarness(); const devInstance = getInstance(MOCK_APP, "development"); +function parseJsonFromStderr(stderr: string): { error: { code?: string } } { + const jsonLine = stderr + .split("\n") + .map((l) => l.trim()) + .find((l) => l.startsWith("{")); + if (!jsonLine) throw new SyntaxError(`No JSON line found in stderr:\n${stderr}`); + return JSON.parse(jsonLine) as { error: { code?: string } }; +} + beforeEach(async () => { await setProfile("github.com/test/project", { workspaceId: "", @@ -40,7 +49,7 @@ test("explicit CLI flags override --input-json values", async () => { const result = await clerk.raw("init", "--input-json", '{"mode":"human"}', "--mode", "agent"); expect(result.exitCode).not.toBe(0); // Agent mode emits structured JSON to stderr; human mode emits plain text. - const parsed = JSON.parse(result.stderr); + const parsed = parseJsonFromStderr(result.stderr); expect(parsed.error).toBeDefined(); }); @@ -234,14 +243,14 @@ test("--input-json is registered as a global option", async () => { // stderr is the agent-mode signature, which proves --mode agent was applied. const result = await clerk.raw("--input-json", '{"mode":"agent"}', "doctor", "--json"); expect(result.exitCode).not.toBe(0); - const parsed = JSON.parse(result.stderr); + const parsed = parseJsonFromStderr(result.stderr); expect(parsed.error).toBeDefined(); }); test("structured JSON error in agent mode for invalid JSON", async () => { const result = await clerk.raw("--mode", "agent", "init", "--input-json", "{bad}"); expect(result.exitCode).not.toBe(0); - const parsed = JSON.parse(result.stderr); + const parsed = parseJsonFromStderr(result.stderr); expect(parsed.error.code).toBe("invalid_json"); }); @@ -254,7 +263,7 @@ test("structured JSON error in agent mode for file not found", async () => { "@/tmp/does-not-exist-clerk.json", ); expect(result.exitCode).not.toBe(0); - const parsed = JSON.parse(result.stderr); + const parsed = parseJsonFromStderr(result.stderr); expect(parsed.error.code).toBe("file_not_found"); }); @@ -267,6 +276,6 @@ test("structured JSON error in agent mode for nested objects", async () => { '{"nested":{"key":"value"}}', ); expect(result.exitCode).not.toBe(0); - const parsed = JSON.parse(result.stderr); + const parsed = parseJsonFromStderr(result.stderr); expect(parsed.error.code).toBe("invalid_json"); });