fix: handle UTF BOM in config files (v3 backport) (#10171)

* feat: add BOM handling implementation and tests for v3-maintenance backport

- Add removeBOMAndValidate function to detect and handle BOMs in config files
- Remove UTF-8 BOM automatically during file parsing
- Error on unsupported BOMs (UTF-16 BE/LE, UTF-32 BE/LE) with descriptive messages
- Add comprehensive test suite covering all BOM scenarios
- Backport from main branch BOM handling implementation

Co-Authored-By: [email protected] <[email protected]>

* add changeset for v3-maintenance backport

Co-Authored-By: [email protected] <[email protected]>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: [email protected] <[email protected]>

Author: devin-ai-integration[bot]

.changeset/violet-walls-tie.md

@@ -0,0 +1,5 @@
+---
+"wrangler": patch
+---
+
+Handle UTF BOM in config files - detect and remove UTF-8 BOMs, error on unsupported BOMs (UTF-16, UTF-32)

packages/wrangler/src/__tests__/config/configuration.test.ts

@@ -6616,6 +6616,93 @@ describe("experimental_readRawConfig()", () => {
 	);
 });
 
+describe("BOM (Byte Order Marker) handling", () => {
+	runInTempDir();
+
+	it("should remove UTF-8 BOM from TOML config files", () => {
+		const configContent = `name = "test-worker"
+compatibility_date = "2022-01-12"`;
+
+		fs.writeFileSync(
+			"wrangler.toml",
+			Buffer.concat([
+				Buffer.from([0xef, 0xbb, 0xbf]),
+				Buffer.from(configContent, "utf-8"),
+			])
+		);
+
+		const config = readConfig({ config: "wrangler.toml" });
+		expect(config.name).toBe("test-worker");
+		expect(config.compatibility_date).toBe("2022-01-12");
+	});
+
+	it("should remove UTF-8 BOM from JSON config files", () => {
+		const configContent = `{
+	"name": "test-worker",
+	"compatibility_date": "2022-01-12"
+}`;
+
+		fs.writeFileSync(
+			"wrangler.json",
+			Buffer.concat([
+				Buffer.from([0xef, 0xbb, 0xbf]),
+				Buffer.from(configContent, "utf-8"),
+			])
+		);
+
+		const config = readConfig({ config: "wrangler.json" });
+		expect(config.name).toBe("test-worker");
+		expect(config.compatibility_date).toBe("2022-01-12");
+	});
+
+	it("should error on UTF-16 BE BOM", () => {
+		const bomBytes = Buffer.from([0xfe, 0xff]);
+		const configContent = Buffer.from('{"name": "test"}', "utf-8");
+		fs.writeFileSync("wrangler.json", Buffer.concat([bomBytes, configContent]));
+
+		expect(() => readConfig({ config: "wrangler.json" })).toThrow(
+			"Configuration file contains UTF-16 BE byte order marker"
+		);
+	});
+
+	it("should error on UTF-16 LE BOM", () => {
+		const bomBytes = Buffer.from([0xff, 0xfe]);
+		const configContent = Buffer.from('{"name": "test"}', "utf-8");
+		fs.writeFileSync("wrangler.json", Buffer.concat([bomBytes, configContent]));
+
+		expect(() => readConfig({ config: "wrangler.json" })).toThrow(
+			"Configuration file contains UTF-16 LE byte order marker"
+		);
+	});
+
+	it("should error on UTF-32 BE BOM", () => {
+		const bomBytes = Buffer.from([0x00, 0x00, 0xfe, 0xff]);
+		const configContent = Buffer.from('{"name": "test"}', "utf-8");
+		fs.writeFileSync("wrangler.json", Buffer.concat([bomBytes, configContent]));
+
+		expect(() => readConfig({ config: "wrangler.json" })).toThrow(
+			"Configuration file contains UTF-32 BE byte order marker"
+		);
+	});
+
+	it("should error on UTF-32 LE BOM", () => {
+		const bomBytes = Buffer.from([0xff, 0xfe, 0x00, 0x00]);
+		const configContent = Buffer.from('{"name": "test"}', "utf-8");
+		fs.writeFileSync("wrangler.json", Buffer.concat([bomBytes, configContent]));
+
+		expect(() => readConfig({ config: "wrangler.json" })).toThrow(
+			"Configuration file contains UTF-32 LE byte order marker"
+		);
+	});
+
+	it("should handle files without BOM normally", () => {
+		writeWranglerConfig({ name: "no-bom-test" });
+
+		const config = readConfig({ config: "wrangler.toml" });
+		expect(config.name).toBe("no-bom-test");
+	});
+});
+
 function normalizePath(text: string): string {
 	return text
 		.replace("project\\wrangler.toml", "project/wrangler.toml")

packages/wrangler/src/parse.ts

@@ -215,8 +215,13 @@ export function readFileSyncToBuffer(file: string): Buffer {
  */
 export function readFileSync(file: string): string {
 	try {
-		return fs.readFileSync(file, { encoding: "utf-8" });
+		const buffer = fs.readFileSync(file);
+		return removeBOMAndValidate(buffer, file);
 	} catch (err) {
+		if (err instanceof ParseError) {
+			throw err;
+		}
+
 		const { message } = err as Error;
 		throw new ParseError({
 			text: `Could not read file: ${file}`,
@@ -359,3 +364,50 @@ export function parseNonHyphenedUuid(uuid: string | null): string | null {
 
 	return hyphenated.slice(0, 36);
 }
+
+const UNSUPPORTED_BOMS = [
+	{
+		buffer: Buffer.from([0x00, 0x00, 0xfe, 0xff]),
+		encoding: "UTF-32 BE",
+	},
+	{
+		buffer: Buffer.from([0xff, 0xfe, 0x00, 0x00]),
+		encoding: "UTF-32 LE",
+	},
+	{
+		buffer: Buffer.from([0xfe, 0xff]),
+		encoding: "UTF-16 BE",
+	},
+	{
+		buffer: Buffer.from([0xff, 0xfe]),
+		encoding: "UTF-16 LE",
+	},
+];
+
+function removeBOMAndValidate(buffer: Buffer, file: string): string {
+	for (const bom of UNSUPPORTED_BOMS) {
+		if (
+			buffer.length >= bom.buffer.length &&
+			buffer.subarray(0, bom.buffer.length).equals(bom.buffer)
+		) {
+			throw new ParseError({
+				text: `Configuration file contains ${bom.encoding} byte order marker`,
+				notes: [
+					{
+						text: `The file "${file}" appears to be encoded as ${bom.encoding}. Please save the file as UTF-8 without BOM.`,
+					},
+				],
+				location: { file, line: 1, column: 0 },
+				telemetryMessage: `${bom.encoding} BOM detected`,
+			});
+		}
+	}
+
+	const content = buffer.toString("utf-8");
+
+	if (content.charCodeAt(0) === 0xfeff) {
+		return content.slice(1);
+	}
+
+	return content;
+}