[workers-auth] Validate account IDs before using them in API requests (#13746)

edmundhung · petebacondarwin · web-flow · commit cec9d8875d3f · 2026-07-31T11:47:00.000+01:00
Co-authored-by: Pete Bacon Darwin &lt;pbacondarwin@cloudflare.com&gt;
diff --git a/.changeset/smart-news-punch.md b/.changeset/smart-news-punch.md
@@ -0,0 +1,8 @@
+---
+"@cloudflare/workers-auth": patch
+"wrangler": patch
+---
+
+Report a clear error for account IDs that can't be used in a Cloudflare API request
+
+Account IDs are substituted straight into Cloudflare API URL paths, so a value containing non-ASCII characters previously failed deep inside the request layer with an opaque `Cannot convert argument to a ByteString` error that gave no hint about which setting was at fault. Account IDs read from `CLOUDFLARE_ACCOUNT_ID` and from the `account_id` configuration field are now validated up front, and an invalid value fails with a message naming both the offending value and where it came from.
diff --git a/packages/workers-auth/AGENTS.md b/packages/workers-auth/AGENTS.md
@@ -11,6 +11,7 @@ CLIs. Internal-only — published as `prerelease: true`.
 - `src/generate-auth-url.ts` — authorize URL builder
 - `src/generate-random-state.ts` — CSRF state generator
 - `src/env-vars.ts` — `WRANGLER_*` and `CLOUDFLARE_AUTH_*` env-var getters
+- `src/account-id.ts` — `validateAccountId(id, source)`, applied to every user-supplied account ID (`CLOUDFLARE_ACCOUNT_ID`, the consumer's `account_id` config field) before it reaches an API URL path
 - `src/access.ts` — Cloudflare Access detection + service-token / `cloudflared` headers
 - `src/config-file/auth.ts` — the `AuthConfigStorage` / `UserAuthConfig` storage contract (interfaces only). The default plaintext credential implementation lives alongside the credential-store layer at `src/credential-store/file-store.ts` (see "Credential storage" below). The core `src/core/auth-config-file.ts` (`createAuthConfigFileHelpers({getConfigPath, format})`) and `src/core/file-storage.ts` (`createFileStorage(format, getPath)`) build the per-profile path helpers and non-credential file stores; each CLI descriptor (`src/wrangler/auth-config-file.ts`, `src/cf/auth-config-file.ts`) binds them to its config dir + `FileFormat` and re-exports `createTomlFileStorage` / `createJsonFileStorage`, `getAuthConfigFilePath`, etc. from its entrypoint. See "CORE LAYER" below.
 - `src/config-file/temporary.ts` — `TemporaryAccountStorage` / `TemporaryPreviewAccount` storage contract for the temporary-preview-account flow
diff --git a/packages/workers-auth/src/account-id.ts b/packages/workers-auth/src/account-id.ts
@@ -0,0 +1,32 @@
+import { UserError } from "@cloudflare/workers-utils";
+
+// Deliberately looser than the 32-character hex IDs the API hands out: the goal
+// is to reject values that cannot travel in a request at all, not to second-guess
+// what the API will accept.
+const ACCOUNT_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * Validate a user-supplied account ID before it reaches the API layer.
+ *
+ * Account IDs are substituted straight into Cloudflare API URL paths, and
+ * `fetch()` rejects URL/header values that aren't representable as a
+ * `ByteString`. Without this check, an account ID containing non-ASCII
+ * characters fails deep inside the request layer with an opaque
+ * `Cannot convert argument to a ByteString` error that gives no hint about
+ * which setting is at fault.
+ *
+ * @param accountId The account ID to check.
+ * @param source Where the value came from, phrased to read after the ID —
+ * e.g. `"set in the \`CLOUDFLARE_ACCOUNT_ID\` environment variable"`.
+ * @returns The account ID, so this can be used inline.
+ */
+export function validateAccountId(accountId: string, source: string): string {
+	if (!ACCOUNT_ID_PATTERN.test(accountId)) {
+		throw new UserError(
+			`Invalid account ID "${accountId}" ${source}. Account IDs may only contain alphanumeric characters, hyphens, and underscores.`,
+			{ telemetryMessage: "user account id invalid characters" }
+		);
+	}
+
+	return accountId;
+}
diff --git a/packages/workers-auth/src/core/factory.ts b/packages/workers-auth/src/core/factory.ts
@@ -27,6 +27,7 @@ import {
 } from "@cloudflare/workers-utils";
 import { formatDistanceToNowStrict } from "date-fns";
 import { dedent } from "ts-dedent";
+import { validateAccountId } from "../account-id";
 import { createCredentialStorageContext } from "../credential-store";
 import { getAuthFromEnv } from "../credentials";
 import { getCloudflareAccountIdFromEnv as getAccountIdFromEnv } from "../env-vars";
@@ -479,7 +480,10 @@ Alternatively, try running \`${descriptor.commands.login}\` to re-authenticate.`
 		}
 
 		if (config.account_id) {
-			return config.account_id;
+			return validateAccountId(
+				config.account_id,
+				`set as \`account_id\` in your ${descriptor.getConfigFileLabel()} file`
+			);
 		}
 		const envAccountId = getAccountIdFromEnv();
 		if (envAccountId) {
diff --git a/packages/workers-auth/src/env-vars.ts b/packages/workers-auth/src/env-vars.ts
@@ -3,6 +3,7 @@ import {
 	getCloudflareApiEnvironmentFromEnv,
 	getEnvironmentVariableFactory,
 } from "@cloudflare/workers-utils";
+import { validateAccountId } from "./account-id";
 
 /**
  * `WRANGLER_AUTH_DOMAIN` is the URL base domain that is used
@@ -59,17 +60,34 @@ export const getRevokeUrlFromEnv = getEnvironmentVariableFactory({
 	defaultValue: () => `https://${getAuthDomainFromEnv()}/oauth2/revoke`,
 });
 
+const readCloudflareAccountIdFromEnv = getEnvironmentVariableFactory({
+	variableName: "CLOUDFLARE_ACCOUNT_ID",
+	deprecatedName: "CF_ACCOUNT_ID",
+});
+
 /**
  * `CLOUDFLARE_ACCOUNT_ID` overrides the account inferred from the current user.
  *
  * This is a Cloudflare-wide variable (not wrangler-specific), so it lives in the
  * shared core rather than a consumer layer. `CF_ACCOUNT_ID` is the deprecated
  * spelling.
+ *
+ * Every caller feeds the result into a Cloudflare API URL path, so the value is
+ * validated here rather than at each call site. An empty string is treated as
+ * unset so callers keep falling back to the cached / interactively selected
+ * account.
  */
-export const getCloudflareAccountIdFromEnv = getEnvironmentVariableFactory({
-	variableName: "CLOUDFLARE_ACCOUNT_ID",
-	deprecatedName: "CF_ACCOUNT_ID",
-});
+export function getCloudflareAccountIdFromEnv(): string | undefined {
+	const accountId = readCloudflareAccountIdFromEnv();
+	if (!accountId) {
+		return undefined;
+	}
+
+	return validateAccountId(
+		accountId,
+		"set in the `CLOUDFLARE_ACCOUNT_ID` environment variable"
+	);
+}
 
 /**
  * `CLOUDFLARE_ACCESS_CLIENT_ID` is the Client ID of a Cloudflare Access Service Token.
diff --git a/packages/workers-auth/tests/account-id.test.ts b/packages/workers-auth/tests/account-id.test.ts
@@ -0,0 +1,67 @@
+import { afterEach, beforeEach, describe, it, vi } from "vitest";
+import { validateAccountId } from "../src/account-id";
+import { getCloudflareAccountIdFromEnv } from "../src/env-vars";
+
+describe("validateAccountId", () => {
+	it("accepts alphanumeric characters, hyphens, and underscores", ({
+		expect,
+	}) => {
+		for (const accountId of [
+			"a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9",
+			"ACCOUNT-ID",
+			"account_id",
+			"0",
+		]) {
+			expect(validateAccountId(accountId, "in the test")).toBe(accountId);
+		}
+	});
+
+	it("rejects values that cannot be used in an API URL", ({ expect }) => {
+		for (const accountId of [
+			"ваш-идентификатор-аккаунта",
+			"account id",
+			"\naccount-id",
+			"account/id",
+			"account:id",
+			"",
+		]) {
+			expect(() => validateAccountId(accountId, "in the test")).toThrow(
+				"Account IDs may only contain alphanumeric characters, hyphens, and underscores."
+			);
+		}
+	});
+
+	it("names the source of the invalid value", ({ expect }) => {
+		expect(() =>
+			validateAccountId("oh no", "set in the `SOME_VARIABLE` variable")
+		).toThrowErrorMatchingInlineSnapshot(
+			`[Error: Invalid account ID "oh no" set in the \`SOME_VARIABLE\` variable. Account IDs may only contain alphanumeric characters, hyphens, and underscores.]`
+		);
+	});
+});
+
+describe("getCloudflareAccountIdFromEnv", () => {
+	beforeEach(() => {
+		vi.unstubAllEnvs();
+	});
+	afterEach(() => {
+		vi.unstubAllEnvs();
+	});
+
+	it("returns the value of CLOUDFLARE_ACCOUNT_ID", ({ expect }) => {
+		vi.stubEnv("CLOUDFLARE_ACCOUNT_ID", "some-account-id");
+		expect(getCloudflareAccountIdFromEnv()).toBe("some-account-id");
+	});
+
+	it("treats an empty value as unset", ({ expect }) => {
+		vi.stubEnv("CLOUDFLARE_ACCOUNT_ID", "");
+		expect(getCloudflareAccountIdFromEnv()).toBeUndefined();
+	});
+
+	it("throws for a value that cannot be used in an API URL", ({ expect }) => {
+		vi.stubEnv("CLOUDFLARE_ACCOUNT_ID", "ваш-идентификатор-аккаунта");
+		expect(getCloudflareAccountIdFromEnv).toThrowErrorMatchingInlineSnapshot(
+			`[Error: Invalid account ID "ваш-идентификатор-аккаунта" set in the \`CLOUDFLARE_ACCOUNT_ID\` environment variable. Account IDs may only contain alphanumeric characters, hyphens, and underscores.]`
+		);
+	});
+});
diff --git a/packages/wrangler/src/__tests__/pages/project-list.test.ts b/packages/wrangler/src/__tests__/pages/project-list.test.ts
@@ -95,6 +95,20 @@ describe("pages project list", () => {
 		expect(requests.count).toBe(1);
 	});
 
+	it("should error before making a request when CLOUDFLARE_ACCOUNT_ID contains characters that are invalid in a URL", async ({
+		expect,
+	}) => {
+		vi.stubEnv("CLOUDFLARE_ACCOUNT_ID", "ваш-идентификатор-аккаунта");
+		const requests = mockProjectListRequest(expect, []);
+
+		await expect(runWrangler("pages project list")).rejects
+			.toThrowErrorMatchingInlineSnapshot(`
+			[Error: Invalid account ID "ваш-идентификатор-аккаунта" set in the \`CLOUDFLARE_ACCOUNT_ID\` environment variable. Account IDs may only contain alphanumeric characters, hyphens, and underscores.]
+		`);
+
+		expect(requests.count).toBe(0);
+	});
+
 	it("should return JSON output when --json flag is provided", async ({
 		expect,
 	}) => {
diff --git a/packages/wrangler/src/__tests__/user.test.ts b/packages/wrangler/src/__tests__/user.test.ts
@@ -1751,6 +1751,26 @@ describe("User", () => {
 			const result = getActiveAccountId({});
 			expect(result).toBeUndefined();
 		});
+
+		it("should reject a config.account_id that cannot be used in an API URL", ({
+			expect,
+		}) => {
+			expect(() =>
+				getActiveAccountId({ account_id: "ваш-идентификатор-аккаунта" })
+			).toThrowErrorMatchingInlineSnapshot(
+				`[Error: Invalid account ID "ваш-идентификатор-аккаунта" set as \`account_id\` in your Wrangler configuration file. Account IDs may only contain alphanumeric characters, hyphens, and underscores.]`
+			);
+		});
+
+		it("should reject a CLOUDFLARE_ACCOUNT_ID that cannot be used in an API URL", ({
+			expect,
+		}) => {
+			vi.stubEnv("CLOUDFLARE_ACCOUNT_ID", "ваш-идентификатор-аккаунта");
+
+			expect(() => getActiveAccountId({})).toThrowErrorMatchingInlineSnapshot(
+				`[Error: Invalid account ID "ваш-идентификатор-аккаунта" set in the \`CLOUDFLARE_ACCOUNT_ID\` environment variable. Account IDs may only contain alphanumeric characters, hyphens, and underscores.]`
+			);
+		});
 	});
 
 	describe("fetchAllAccounts", () => {
@@ -2148,5 +2168,19 @@ describe("User", () => {
 				name: "API Account",
 			});
 		});
+
+		it("should reject an invalid env var without making API calls", async ({
+			expect,
+		}) => {
+			vi.stubEnv("CLOUDFLARE_ACCOUNT_ID", "ваш-идентификатор-аккаунта");
+
+			// No getMswSuccessMembershipHandlers — if an API call is made, it will fail
+			// with an unhandled-request error rather than the validation error below.
+			await expect(
+				getOrSelectAccountId({})
+			).rejects.toThrowErrorMatchingInlineSnapshot(
+				`[Error: Invalid account ID "ваш-идентификатор-аккаунта" set in the \`CLOUDFLARE_ACCOUNT_ID\` environment variable. Account IDs may only contain alphanumeric characters, hyphens, and underscores.]`
+			);
+		});
 	});
 });
