fix(webhooks): relay token carries the c_ prefix on the wire and in the inbox URL

Live-relay verified: play.svix.com returns 400 'Invalid token' for
unprefixed tokens, and the relay only registers an inbox when the start
frame carries the same c_ token. With c_ in both, a POST to the inbox
round-trips through the WebSocket and the reply frame is accepted —
proven end-to-end against the real relay with no PLAPI involvement.
Reverses spec change #12 (recorded as spec change #27).

Author: rafa-thayto

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

@@ -246,7 +246,7 @@ clerk webhooks listen [--forward-to <url>] [--events <list>] [--skip-verify] [--
 
 Behavior notes:
 
-- **Relay token**: 10 random base62 chars, raw on the wire (no `c_` prefix), persisted per instance in the CLI config (`relay.<instanceId>.token`). Close code 1008 = token collision → new token generated, persisted, redialed, and the endpoint URL re-pointed.
+- **Relay token**: `c_` + 10 random base62 chars — the same token goes in the start frame, the inbox URL, and the per-instance CLI config (`relay.<instanceId>.token`). Live-relay verified: `play.svix.com` rejects unprefixed tokens, and the relay only registers an inbox when the start frame carries the `c_` token. Close code 1008 = token collision → new token generated, persisted, redialed, and the endpoint URL re-pointed.
 - **Keepalive**: the relay server pings ~every 21s, but Bun's client WebSocket auto-pongs below the JS API (no ping events). After 30s of silence the client sends an active `ws.ping()` probe — writes to a dead link surface as close/error, which redials with the same token. Reconnects never change the relay URL.
 - **Per-delivery output**: human mode prints `time --> event_type msg_…` then `<-- status method path ms` via `log.ui` (bypasses the stderr throttle). Diagnostics: 401 → `clerkMiddleware` public-route hint; 400 → raw-body/`verifyWebhook()` order hint; 5xx → response body inline plus the exact `clerk webhooks replay <msg_id>` line; unreachable handler → synthetic **502** framed back to the relay.
 - **Verification**: deliveries failing HMAC are warned about and still forwarded (the mismatch means the relay secret diverged, not that the local handler should silently miss events).

packages/cli-core/src/commands/webhooks/listen.test.ts

@@ -161,7 +161,7 @@ describe("webhooks listen", () => {
     expect(mockResolveAppContext).not.toHaveBeenCalled();
   });
 
-  test("first run generates and persists a 10-char base62 token, then creates the endpoint", async () => {
+  test("first run generates and persists a c_-prefixed base62 token, then creates the endpoint", async () => {
     mockGetRelayEntry.mockResolvedValue(undefined);
 
     await startListen({}, captured);
@@ -172,7 +172,7 @@ describe("webhooks listen", () => {
     ];
     const persistedToken = firstEntry.token;
     expect(firstInstanceId).toBe("ins_1");
-    expect(persistedToken).toMatch(/^[0-9A-Za-z]{10}$/);
+    expect(persistedToken).toMatch(/^c_[0-9A-Za-z]{10}$/);
 
     expect(mockCreateWebhookEndpoint).toHaveBeenCalledWith("app_1", "ins_1", {
       url: `https://play.svix.com/in/${persistedToken}/`,

packages/cli-core/src/commands/webhooks/relay-protocol.test.ts

@@ -9,10 +9,9 @@ import {
 } from "./relay-protocol.ts";
 
 describe("generateRelayToken", () => {
-  test("produces 10 base62 chars with no prefix", () => {
+  test("produces c_ + 10 base62 chars (live-relay wire format)", () => {
     const token = generateRelayToken();
-    expect(token).toMatch(/^[0-9A-Za-z]{10}$/);
-    expect(token.startsWith("c_")).toBe(false);
+    expect(token).toMatch(/^c_[0-9A-Za-z]{10}$/);
   });
 
   test("produces distinct tokens across calls", () => {
@@ -22,7 +21,7 @@ describe("generateRelayToken", () => {
 });
 
 describe("relayReceiveUrl", () => {
-  test("builds the play.svix.com URL with the raw token", () => {
+  test("builds the play.svix.com URL with the token verbatim", () => {
     expect(relayReceiveUrl("Ab12Cd34Ef")).toBe("https://play.svix.com/in/Ab12Cd34Ef/");
   });
 });

packages/cli-core/src/commands/webhooks/relay-protocol.ts

@@ -23,8 +23,12 @@ const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
 const TOKEN_LENGTH = 10;
 // Largest multiple of 62 below 256; bytes at or above it would bias the modulo.
 const UNBIASED_BYTE_LIMIT = 248;
+// Live-relay verified (2026-06-10): play.svix.com rejects unprefixed tokens
+// ("Invalid token"), and the relay only registers an inbox when the start
+// frame carries the same c_ token. The prefix is wire format, not cosmetics.
+const TOKEN_PREFIX = "c_";
 
-/** 10 random base62 chars, raw — no `c_` prefix on the wire or in the URL. */
+/** `c_` + 10 random base62 chars — the same token goes in the start frame, the inbox URL, and config. */
 export function generateRelayToken(): string {
   let token = "";
   while (token.length < TOKEN_LENGTH) {
@@ -36,7 +40,7 @@ export function generateRelayToken(): string {
       if (token.length === TOKEN_LENGTH) break;
     }
   }
-  return token;
+  return TOKEN_PREFIX + token;
 }
 
 export function relayReceiveUrl(token: string): string {