fix(api): reject an invalid request body locally

.changeset/api-validate-json-body.md

@@ -0,0 +1,5 @@
+---
+"clerk": patch
+---
+
+Reject an invalid `clerk api` request body on your machine instead of sending it. The error echoes what arrived and, when a `-d` value reached the CLI with its double quotes stripped or wrapped in literal single quotes, names the shell quoting behind it — an unquoted body in a POSIX shell, or PowerShell before 7.3 and cmd.exe on Windows — and suggests the same request with `--file`, which no shell can mangle. Those shell-quoting rejections carry the error code `invalid_json_shell_quoting`; other parse failures keep `invalid_json`.

packages/cli-core/src/commands/api/README.md

@@ -65,6 +65,36 @@ clerk api /v1/platform/applications --platform
 clerk api --fapi /environment --app app_123 --instance dev
 ```
 
+## Request bodies and shell quoting
+
+`-d` takes the body exactly as your shell hands it over, and the CLI parses it
+before sending — an unparseable payload fails locally with the reason, instead of
+costing a round trip and a server-side byte offset. When the value reached the
+CLI with its double quotes stripped, or wrapped in literal single quotes, the
+error names the shell quoting behind it.
+
+The `-d '{"key":"value"}'` form in the examples above is POSIX shell syntax: the
+single quotes keep bash and zsh from consuming the double quotes inside. Leave
+them off and the shell strips those quotes, so the CLI receives `{key:value}`.
+
+Even with the single quotes, that form fails in PowerShell before 7.3 and in
+cmd.exe:
+
+- **PowerShell before 7.3** passes an argument's embedded double quotes to a
+  native program unescaped, so the program's command-line parser consumes them:
+  `-d '{"user_id":"x"}'` arrives as `{user_id:x}`. PowerShell 7.3 fixed this.
+- **cmd.exe** gives `'` no special meaning, so the wrapping single quotes are
+  passed through as part of the value, and the double quotes inside are consumed
+  the same way: `'{user_id:x}'`.
+
+`--file` and piped stdin sidestep the shell entirely and behave the same
+everywhere, so prefer them for anything non-trivial and in scripts:
+
+```sh
+clerk api /users --file body.json
+cat body.json | clerk api /users
+```
+
 ## Options
 
 | Flag                    | Description                                                                     |

packages/cli-core/src/commands/api/index.test.ts

@@ -726,4 +726,156 @@ describe("api command", () => {
     await runApi("/users", { data: '{"from":"inline"}', file: bodyFile });
     expect(JSON.parse(capturedBody)).toEqual({ from: "inline" });
   });
+
+  // --- request body is parse-checked before it goes out ---
+
+  test("rejects invalid -d without making a request", async () => {
+    let requested = false;
+    stubFetch(async () => {
+      requested = true;
+      return new Response("{}", { status: 200 });
+    });
+
+    // What PowerShell before 7.3 leaves of -d '{"first_name":"Alice"}'.
+    await expect(runApi("/users", { data: "{first_name:Alice}" })).rejects.toThrow(
+      "Invalid JSON in --data",
+    );
+    expect(requested).toBe(false);
+  });
+
+  test('rejects an explicit -d "" instead of sending a bodyless request', async () => {
+    let requested = false;
+    stubFetch(async () => {
+      requested = true;
+      return new Response("{}", { status: 200 });
+    });
+
+    await expect(runApi("/users", { data: "" })).rejects.toThrow(
+      "Invalid JSON in --data: the body is empty.",
+    );
+    expect(requested).toBe(false);
+  });
+
+  test("rejects an invalid --file body", async () => {
+    const bodyFile = join(tempDir, "broken.json");
+    await Bun.write(bodyFile, '{"first_name":"Alice"');
+
+    await expect(runApi("/users", { file: bodyFile })).rejects.toThrow(
+      `Invalid JSON in --file ${bodyFile}`,
+    );
+  });
+
+  /**
+   * Make stdin look like a pipe carrying `text`: not a TTY, and its async
+   * iterator yields that one chunk. Returns the restore function; isTTY itself
+   * is put back by afterEach.
+   */
+  function pipeStdin(text: string): () => void {
+    Object.defineProperty(process.stdin, "isTTY", {
+      value: false,
+      writable: true,
+      configurable: true,
+    });
+    const original = process.stdin[Symbol.asyncIterator];
+    Object.defineProperty(process.stdin, Symbol.asyncIterator, {
+      value: async function* () {
+        if (text) yield Buffer.from(text);
+      },
+      writable: true,
+      configurable: true,
+    });
+    return () => {
+      Object.defineProperty(process.stdin, Symbol.asyncIterator, {
+        value: original,
+        writable: true,
+        configurable: true,
+      });
+    };
+  }
+
+  test("rejects an invalid piped body", async () => {
+    const restore = pipeStdin("not json at all");
+    try {
+      await expect(runApi("/users")).rejects.toThrow("Invalid JSON in the piped request body");
+    } finally {
+      restore();
+    }
+  });
+
+  // CI jobs and cron have a non-TTY stdin with nothing on it; a plain GET must
+  // still go out rather than be rejected as an empty body.
+  test("treats an empty non-TTY stdin as no body, not an empty one", async () => {
+    let capturedMethod = "";
+    let capturedBody: unknown = "unset";
+    stubFetch(async (_input, init) => {
+      capturedMethod = init?.method as string;
+      capturedBody = init?.body;
+      return new Response(JSON.stringify(mockUsers), { status: 200 });
+    });
+
+    const restore = pipeStdin("");
+    try {
+      await runApi("/users");
+    } finally {
+      restore();
+    }
+    expect(capturedMethod).toBe("GET");
+    expect(capturedBody).toBeUndefined();
+  });
+
+  test("forwards a piped body untrimmed", async () => {
+    let capturedBody = "";
+    stubFetch(async (_input, init) => {
+      capturedBody = init?.body as string;
+      return new Response("{}", { status: 200 });
+    });
+
+    const raw = '{"first_name": "Alice"}\n';
+    const restore = pipeStdin(raw);
+    try {
+      await runApi("/users");
+    } finally {
+      restore();
+    }
+    expect(capturedBody).toBe(raw);
+  });
+
+  test("--dry-run rejects an invalid body too", async () => {
+    await expect(runApi("/users", { dryRun: true, data: "{first_name:Alice}" })).rejects.toThrow(
+      "Invalid JSON in --data",
+    );
+  });
+
+  test("forwards a valid body byte-for-byte", async () => {
+    let capturedBody = "";
+    stubFetch(async (_input, init) => {
+      capturedBody = init?.body as string;
+      return new Response("{}", { status: 200 });
+    });
+
+    const raw = '{"first_name":  "Alice"}';
+    await runApi("/users", { data: raw });
+    expect(capturedBody).toBe(raw);
+  });
+
+  test("the suggested --file command repeats the caller's targeting flags", async () => {
+    const originalPlatform = process.platform;
+    Object.defineProperty(process, "platform", { value: "win32", writable: true });
+    try {
+      const error = (await runApi("/environment", {
+        fapi: true,
+        app: "app_1",
+        instance: "dev",
+        method: "post",
+        data: "{a:b}",
+      }).catch((e: unknown) => e)) as CliError;
+      expect(error.code).toBe(ERROR_CODE.INVALID_JSON_SHELL_QUOTING);
+      expect(error.examples?.[0]?.command).toBe(
+        "clerk api --fapi /environment -X POST --app app_1 --instance dev --file body.json",
+      );
+      expect(error.examples?.[0]?.command).not.toContain("sk_");
+    } finally {
+      Object.defineProperty(process, "platform", { value: originalPlatform, writable: true });
+    }
+  });
 });

packages/cli-core/src/commands/api/index.ts

@@ -7,6 +7,7 @@ import { bapiRequest } from "../../lib/bapi.ts";
 import { fapiRequest } from "../../lib/fapi.ts";
 import { resolveFapiHost } from "./fapi.ts";
 import { ApiError, ERROR_CODE, throwUsageError, throwUserAbort } from "../../lib/errors.ts";
+import { validateJsonBody } from "../../lib/json-body.ts";
 import { isHuman } from "../../mode.ts";
 import { confirm } from "../../lib/prompts.ts";
 import { withSpinner, intro, outro, pausedOutro } from "../../lib/spinner.ts";
@@ -87,7 +88,7 @@ export async function api(
     }
 
     // 1. Resolve the request body
-    const body = await resolveBody(options);
+    const body = await resolveBody(options, endpoint);
 
     // 2. Determine HTTP method
     const method = (options.method ?? (body ? "POST" : "GET")).toUpperCase();
@@ -175,25 +176,47 @@ export async function api(
   }
 }
 
-async function resolveBody(options: { data?: string; file?: string }): Promise<string | null> {
-  if (options.data) return options.data;
+/**
+ * Resolve the request body from `-d`, `--file`, or piped stdin, and parse-check
+ * it before it can reach the API. The request's targeting flags ride along only
+ * so the error's suggested command hits the same endpoint; the secret key is
+ * deliberately not among them, since the suggestion is printed.
+ */
+async function resolveBody(options: ApiOptions, endpoint: string): Promise<string | null> {
+  const request = {
+    endpoint,
+    method: options.method,
+    fapi: options.fapi,
+    platform: options.platform,
+    app: options.app,
+    instance: options.instance,
+  };
+
+  // Presence, not truthiness: an explicit `-d ""` is an empty body to reject,
+  // not a request with no body.
+  if (options.data !== undefined) {
+    return validateJsonBody(options.data, { kind: "data" }, request);
+  }
 
   if (options.file) {
     const file = Bun.file(options.file);
     if (!(await file.exists())) {
       throwUsageError(`File not found: ${options.file}`, undefined, ERROR_CODE.FILE_NOT_FOUND);
     }
-    return file.text();
+    return validateJsonBody(await file.text(), { kind: "file", path: options.file }, request);
   }
 
-  // Read from stdin if piped
+  // Read from stdin if piped. A non-TTY stdin is not proof of a pipe — CI
+  // jobs, cron, and `< /dev/null` look the same and yield nothing — so nothing
+  // (or only whitespace) on stdin means no body rather than an empty one. What
+  // does arrive is forwarded untrimmed, like a --file body.
   if (!process.stdin.isTTY) {
     const chunks: Buffer[] = [];
     for await (const chunk of process.stdin) {
       chunks.push(Buffer.from(chunk));
     }
-    const text = Buffer.concat(chunks).toString("utf-8").trim();
-    if (text) return text;
+    const text = Buffer.concat(chunks).toString("utf-8");
+    if (text.trim()) return validateJsonBody(text, { kind: "stdin" }, request);
   }
 
   return null;
@@ -277,6 +300,11 @@ export function registerApi(program: Program): void {
         command: 'clerk api /users -d \'{"first_name":"Alice"}\'',
         description: "POST with a JSON body",
       },
+      {
+        command: "clerk api /users --file body.json",
+        description:
+          "POST a body from a file — no shell quoting, so it works the same in PowerShell and cmd.exe",
+      },
       {
         command: "clerk api --fapi /environment --app <id> --instance dev",
         description: "GET the public FAPI environment payload",

packages/cli-core/src/commands/users/README.md

@@ -94,6 +94,11 @@ clerk users create --app app_123 --instance prod -d '{"email_address":["alice@ex
 clerk users create --file user.json --dry-run
 ```
 
+The `-d '{"…"}'` form is POSIX shell syntax. It fails in cmd.exe, which passes
+the wrapping single quotes through as part of the value, and in PowerShell
+before 7.3, which strips an argument's embedded double quotes. Prefer the
+curated flags, or `--file`, on Windows and in scripts.
+
 Supported curated flags:
 
 - `--email <email>`

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

@@ -42,6 +42,8 @@ export const ERROR_CODE = {
   INVALID_WEBHOOK_SIGNATURE: "invalid_webhook_signature",
   /** Input is not valid JSON or not an object. */
   INVALID_JSON: "invalid_json",
+  /** A `clerk api -d` body arrived visibly mangled by shell quoting — stripped or wrapped. */
+  INVALID_JSON_SHELL_QUOTING: "invalid_json_shell_quoting",
   /** Failed to fetch or parse the OpenAPI catalog. */
   CATALOG_ERROR: "catalog_error",
   /** Doctor checks found issues. */