@salesforce/graphiti 11.35.1 → 11.35.3

package/src/commands/mcp-mirror/run-mirror.ts

@@ -7,6 +7,7 @@
 import { type z } from "zod";
 import { AuthError } from "../../lib/errors.js";
 import { SchemaRefreshError } from "../../lib/prime-schema.js";
+import { sanitizePaths } from "../../schemas/tool-adapter.js";
 
 /**
  * Shared adapter for the `sf-gql-*` CLI mirror commands. Each command reads a
@@ -138,24 +139,33 @@ export async function runMirror<T>(
 		const output = await build(result.data);
 		console.log(JSON.stringify(output));
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
+		const rawMessage = err instanceof Error ? err.message : String(err);
+		// Classify on the RAW message (the heuristic keys off auth/schema wording;
+		// sanitizePaths would relativize a "~/.sf" hint to a marker and defeat it).
 		// Typed signals win; otherwise fall back to the best-effort message regex.
 		// AuthError is checked first because its message (W-23335328) reads "Schema
 		// priming failed … expired or unauthorized. Re-authenticate …" — that
 		// "priming" makes classifyErrorMessage return SCHEMA_PRIME_FAILED, so an
 		// untyped fallthrough would misclassify a 401/403 introspection failure as a
-		// schema problem (the exact Schema-vs-Auth confusion this WI fixes).
+		// schema problem (the exact Schema-vs-Auth confusion W-23335328 fixes).
 		const code: MirrorErrorCode =
 			err instanceof AuthError
 				? "AUTH_FAILED"
 				: err instanceof SchemaRefreshError
 					? "SCHEMA_PRIME_FAILED"
-					: classifyErrorMessage(message);
+					: classifyErrorMessage(rawMessage);
+		// W-23336442 (N2): emit the SANITIZED message, never the raw one. sanitizePaths
+		// redacts absolute filesystem paths (home dir, repo checkout, schema cache —
+		// W-22697673) AND neutralizes Cc/Cf control chars (bidi/zero-width/tag chars
+		// that JSON.stringify leaves raw), so a caller- or filesystem-derived error
+		// string can neither disclose local layout nor smuggle control chars to the host.
+		const message = sanitizePaths(rawMessage);
 		// The stack is omitted by default so the envelope never leaks internals;
-		// GRAPHITI_DEBUG=1 opts into attaching it under `details` for debugging.
+		// GRAPHITI_DEBUG=1 opts into attaching it under `details` — and even then it is
+		// run through the same sanitizer so the opt-in debug stack cannot leak paths.
 		const details =
 			process.env.GRAPHITI_DEBUG === "1" && err instanceof Error && err.stack
-				? { stack: err.stack }
+				? { stack: sanitizePaths(err.stack) }
 				: undefined;
 		emitError(code, message, details);
 	}

package/src/intent/__tests__/build-discover.spec.ts

@@ -429,4 +429,166 @@ describe("intent/build-discover", () => {
 			).rejects.toThrow(/not found on "Account"/);
 		});
 	});
+
+	// W-23336442: free-text org metadata (field label, picklist value, schema
+	// description) is reflected verbatim through the SUCCESS envelope, whose
+	// JSON.stringify escapes only C0 (U+0000-U+001F). DEL (U+007F) and the entire
+	// Cf class (bidi overrides, zero-width, ...) survive raw, so buildDiscover must
+	// neutralize them at the projection sites. `neutralizeControlChars` escapes to
+	// a visible `\xNN` (cp<=0xff) or `\uNNNN` literal; ordinary Unicode is untouched.
+	describe("free-text metadata neutralization (W-23336442)", () => {
+		// Raw dangerous code points (escapes in SOURCE, raw at runtime): U+202E
+		// RIGHT-TO-LEFT OVERRIDE (Cf), U+200B ZERO WIDTH SPACE (Cf), U+007F DELETE (Cc).
+		const RLO = "\u{202e}";
+		const ZWSP = "\u{200b}";
+		const DEL = "\x7f";
+		// Their neutralized (visible, inert) forms.
+		const ESC_RLO = "\\u202e";
+		const ESC_ZWSP = "\\u200b";
+		const ESC_DEL = "\\x7f";
+
+		const TAINTED_INFO: ObjectInfoResult = {
+			...ACCOUNT_INFO,
+			fields: [
+				makeField({
+					apiName: "Industry",
+					label: `Ind${RLO}ustry${ZWSP} café 日本語${DEL}`,
+					dataType: "PICKLIST",
+					createable: true,
+					updateable: true,
+				}),
+			],
+			picklists: [
+				{
+					apiName: "Industry",
+					label: "Industry",
+					required: false,
+					values: [
+						{ value: `Tech${RLO}nology${DEL}`, label: "Technology" },
+						{ value: `Fin${ZWSP}ance café`, label: "Finance" },
+					],
+				},
+			],
+		};
+
+		function taintedDeps(): DiscoverDeps {
+			return {
+				primeDeps: makePrimeDeps(),
+				getOrgAuth: async () => ({
+					alias: ORG,
+					username: "u",
+					instanceUrl: ORG_URL,
+					accessToken: "t",
+					orgId: "00D",
+				}),
+				getObjectInfo: async () => TAINTED_INFO,
+			};
+		}
+
+		it("escapes Cc/Cf in a field label but preserves ordinary Unicode (describe_field)", async () => {
+			const out = await buildDiscover(
+				{ org: ORG, mode: "describe_field", object: "Account", field: "Industry" },
+				taintedDeps(),
+			);
+			if (out.mode !== "describe_field") return;
+
+			// Escaped: the raw code points are ABSENT and appear as visible escapes.
+			expect(out.field.label).toBe(`Ind${ESC_RLO}ustry${ESC_ZWSP} café 日本語${ESC_DEL}`);
+			expect(out.field.label).not.toContain(RLO);
+			expect(out.field.label).not.toContain(ZWSP);
+			expect(out.field.label).not.toContain(DEL);
+			// Ordinary Unicode survives verbatim.
+			expect(out.field.label).toContain("café");
+			expect(out.field.label).toContain("日本語");
+		});
+
+		it("escapes Cc/Cf in picklist values but preserves ordinary Unicode (describe_field)", async () => {
+			const out = await buildDiscover(
+				{ org: ORG, mode: "describe_field", object: "Account", field: "Industry" },
+				taintedDeps(),
+			);
+			if (out.mode !== "describe_field") return;
+
+			expect(out.field.picklistValues).toEqual([
+				`Tech${ESC_RLO}nology${ESC_DEL}`,
+				`Fin${ESC_ZWSP}ance café`,
+			]);
+			const joined = (out.field.picklistValues ?? []).join("");
+			expect(joined).not.toContain(RLO);
+			expect(joined).not.toContain(ZWSP);
+			expect(joined).not.toContain(DEL);
+			expect(joined).toContain("café");
+		});
+
+		it("escapes Cc/Cf in field labels reached via describe_object", async () => {
+			const out = await buildDiscover(
+				{ org: ORG, mode: "describe_object", object: "Account" },
+				taintedDeps(),
+			);
+			if (out.mode !== "describe_object") return;
+
+			const industry = out.object.fields.find((f) => f.name === "Industry");
+			expect(industry?.label).toBe(`Ind${ESC_RLO}ustry${ESC_ZWSP} café 日本語${ESC_DEL}`);
+			expect(industry?.label).not.toContain(RLO);
+			expect(industry?.label).not.toContain(DEL);
+			expect(industry?.picklistValues).toEqual([
+				`Tech${ESC_RLO}nology${ESC_DEL}`,
+				`Fin${ESC_ZWSP}ance café`,
+			]);
+		});
+
+		it("escapes Cc/Cf in the list_objects label (schema description)", async () => {
+			const ALIAS = "test-discover-taint";
+			const URL = "https://test-discover-taint.my.salesforce.com";
+			// Descriptions carry the raw code points at runtime (source uses escapes).
+			// U+202E/U+200B/U+007F are all valid GraphQL SourceCharacters (>= U+0020).
+			const taintSchema = buildSchema(`
+				type Query { uiapi: UIAPI! }
+				type UIAPI { query: RecordQuery! }
+				type RecordQuery {
+					"Cust${RLO}omer${ZWSP} café 日本語${DEL}"
+					Account(first: Int): AccountConnection!
+				}
+				type AccountConnection { edges: [AccountEdge!]! }
+				type AccountEdge { node: Account! }
+				type Account { Id: ID! }
+			`);
+			primeSchemaCache(ALIAS, taintSchema);
+			primeSchemaCache(URL, taintSchema);
+
+			const deps: DiscoverDeps = {
+				primeDeps: {
+					getOrgAuth: async () => ({
+						alias: ALIAS,
+						username: "u",
+						instanceUrl: URL,
+						accessToken: "t",
+						orgId: "00D",
+					}),
+					downloadSchema: async (auth) => {
+						const cacheKey = schemaCacheKeyForInstanceUrl(auth.instanceUrl);
+						const filePath = path.join(schemaDir(), `${cacheKey}.json`);
+						atomicWriteJson(filePath, { data: introspectionFromSchema(taintSchema) });
+						return {
+							cacheKey,
+							instanceUrl: auth.instanceUrl,
+							typeCount: 0,
+							downloadedAt: new Date().toISOString(),
+							filePath,
+						};
+					},
+				},
+			};
+
+			const out = await buildDiscover({ org: ALIAS, mode: "list_objects" }, deps);
+			if (out.mode !== "list_objects") return;
+			const account = out.objects.find((o) => o.name === "Account");
+			expect(account?.label).toBe(`Cust${ESC_RLO}omer${ESC_ZWSP} café 日本語${ESC_DEL}`);
+			expect(account?.label).not.toContain(RLO);
+			expect(account?.label).not.toContain(ZWSP);
+			expect(account?.label).not.toContain(DEL);
+			expect(account?.label).toContain("café");
+			expect(account?.label).toContain("日本語");
+		});
+	});
 });

package/src/intent/build-discover.ts

@@ -21,6 +21,7 @@ import {
 } from "../lib/object-info.js";
 import { type PrimeDeps } from "../lib/prime-schema.js";
 import { resolvePath } from "../lib/walker.js";
+import { neutralizeControlChars } from "../schemas/tool-adapter.js";
 
 export interface DiscoverDeps {
 	primeDeps?: PrimeDeps;
@@ -124,8 +125,12 @@ function listQueryableObjects(
 		result = walker.fields
 			.filter((f) => /Connection$/.test(f.typeName.replace(/[![\]]/g, "")))
 			.map((f) => ({
+				// `name` is a GraphQL field name (charset-guarded identifier) — left
+				// as-is. W-23336442: `label` is free-text org schema description
+				// reflected verbatim into the success envelope, so neutralize its
+				// Cc/Cf (bidi/zero-width/DEL) before it reaches the host.
 				name: f.name,
-				...(f.description ? { label: f.description } : {}),
+				...(f.description ? { label: neutralizeControlChars(f.description) } : {}),
 			}));
 	} catch {
 		return [];
@@ -143,12 +148,20 @@ function toFieldDescription(field: FieldMetadata, info: ObjectInfoResult): Field
 	const picklist = info.picklists.find((p) => p.apiName === field.apiName);
 	// `parseObjectInfoResponse` already drops null-valued entries, but the
 	// PicklistValue type still allows null — filter narrows to string[].
+	// W-23336442: picklist `value` is free-text org metadata reflected verbatim
+	// into the success envelope — neutralize Cc/Cf before it reaches the host.
 	const picklistValues =
-		picklist?.values.map((v) => v.value).filter((v): v is string => v !== null) ?? [];
+		picklist?.values
+			.map((v) => v.value)
+			.filter((v): v is string => v !== null)
+			.map(neutralizeControlChars) ?? [];
 
 	return {
+		// W-23336442: `name`/`type` are identifier/system-enum (already charset-
+		// safe) so pass through; `label` is free-text org metadata, so neutralize
+		// its Cc/Cf (bidi/zero-width/DEL) on this success-envelope reflection path.
 		name: field.apiName,
-		label: field.label ?? field.apiName,
+		label: neutralizeControlChars(field.label ?? field.apiName),
 		type: field.dataType ?? "UNKNOWN",
 		filterable: field.filterable,
 		sortable: field.sortable,

package/src/lib/__tests__/control-chars.spec.ts

@@ -4,9 +4,11 @@
  * For full license text, see the LICENSE.txt file
  */
 
+import { parse } from "graphql";
 import { describe, expect, it } from "vitest";
 import {
 	CONTROL_CHAR_RE,
+	escapeControlCharsGraphQL,
 	LINE_SEPARATOR_RE,
 	stripControlChars,
 	stripLineSeparators,
@@ -117,6 +119,72 @@ describe("lib/control-chars", () => {
 		});
 	});
 
+	// escapeControlCharsGraphQL is the THIRD disposition of the shared Cc/Cf class
+	// (W-23336442): unlike stripControlChars (delete) or neutralizeControlChars
+	// (\xNN / \u{...} for a plain-JSON envelope), it emits ONLY GraphQL-valid
+	// \uXXXX escapes because its output lands inside a LIVE GraphQL string literal
+	// -- \xNN would make the query un-parseable and \u{...} isn't universally
+	// accepted, so astral chars become a surrogate PAIR.
+	describe("escapeControlCharsGraphQL", () => {
+		// Expected \uXXXX (or surrogate-pair) rendering for each representative.
+		const ESCAPED: [string, string, string][] = [
+			["C0 LF", "\n", "\\u000a"],
+			["C0 NUL", "\x00", "\\u0000"],
+			["C0 ESC", "\x1b", "\\u001b"],
+			["DEL (survives JSON.stringify)", "\x7f", "\\u007f"],
+			["C1 CSI", "\x9b", "\\u009b"],
+			["NEL", "\u{85}", "\\u0085"],
+			["ZWSP (BMP Cf)", "\u{200b}", "\\u200b"],
+			["bidi RLO (BMP Cf)", "\u{202e}", "\\u202e"],
+			["BOM/ZWNBSP", "\u{feff}", "\\ufeff"],
+			// Astral tag char -> UTF-16 surrogate pair (U+E0001 = D800+... / DC00+...).
+			["tag block U+E0001 (astral)", "\u{e0001}", "\\udb40\\udc01"],
+		];
+
+		it.each(ESCAPED)("escapes %s to a lower-case \\uXXXX escape", (_label, ch, esc) => {
+			expect(escapeControlCharsGraphQL(`a${ch}b`)).toBe(`a${esc}b`);
+		});
+
+		it("emits the astral tag char as a surrogate pair, never \\u{...}", () => {
+			const out = escapeControlCharsGraphQL("\u{e0001}");
+			expect(out).toBe("\\udb40\\udc01");
+			expect(out).not.toContain("\\u{");
+		});
+
+		it("leaves ordinary Unicode (accents, CJK, emoji) untouched", () => {
+			const ok = "plain ASCII café 日本語 naïve \u{1f600}";
+			expect(escapeControlCharsGraphQL(ok)).toBe(ok);
+		});
+
+		it("leaves U+2028/U+2029 untouched (Zl/Zp are out of the Cc/Cf class)", () => {
+			expect(escapeControlCharsGraphQL("a\u{2028}b\u{2029}c")).toBe("a\u{2028}b\u{2029}c");
+		});
+
+		it("escapes every occurrence, not just the first", () => {
+			expect(escapeControlCharsGraphQL("a\u{202e}b\u{200b}c\x7fd")).toBe(
+				"a\\u202eb\\u200bc\\u007fd",
+			);
+		});
+
+		it("output contains no raw Cc/Cf code point and no GraphQL-invalid \\xNN / \\u{...}", () => {
+			const poison = ESCAPED.map(([, ch]) => ch).join("x");
+			const out = escapeControlCharsGraphQL(poison);
+			expect(out).not.toMatch(/[\p{Cc}\p{Cf}]/u);
+			// GraphQL rejects \xNN entirely and not every parser accepts \u{...}.
+			expect(out).not.toContain("\\x");
+			expect(out).not.toContain("\\u{");
+		});
+
+		it("produces a GraphQL-parseable string literal for a poisoned value (round-trip)", () => {
+			// Wrap the escaped output in quotes: it must be a valid GraphQL document.
+			const escaped = escapeControlCharsGraphQL("before\u{202e}\u{200b}\x7f\u{e0001}after");
+			const query = `query { field(arg: "${escaped}") }`;
+			expect(() => parse(query)).not.toThrow();
+			// The specific dangerous code points are absent from the raw query source.
+			expect(query).not.toMatch(/[\u{202e}\u{200b}\u{7f}\u{e0001}]/u);
+		});
+	});
+
 	// U+2028/U+2029 are Zl/Zp -- NOT part of CONTROL_CHAR_RE (asserted above) --
 	// so they get their own primitive. Every host-visible sink strips them
 	// separately because raw, they trip a Claude.AI 408 (MCP TS SDK #2155): the

package/src/lib/__tests__/query-builder.spec.ts

@@ -548,4 +548,132 @@ describe("query-builder", () => {
 			}
 		});
 	});
+
+	// W-23336442: caller-supplied string VALUES (sf_gql_list scope/filter/orderBy)
+	// reach the emitted GraphQL literal via formatArgValue / valueToGraphQL, which
+	// use JSON.stringify. JSON.stringify escapes only the C0 range (U+0000-U+001F)
+	// and leaves DEL (U+007F) plus the entire Cf class (bidi overrides, zero-width,
+	// tag block) RAW inside the quotes. Since the query is a LIVE GraphQL document
+	// reflected to the host, those survivors are post-escaped to GraphQL-valid
+	// \uXXXX. CRITICAL invariants: (1) the specific poisoning code points are ABSENT
+	// from the emitted source (present only as \uXXXX), and (2) graphql.parse() of
+	// the emitted query still succeeds (\uXXXX is spec-valid; \xNN would not be).
+	describe("control-char value escaping (W-23336442)", () => {
+		// U+202E (bidi RLO), U+200B (ZWSP), U+007F (DEL): all survive JSON.stringify.
+		const POISON = "a\u{202e}b\u{200b}c\u{7f}d";
+		const RAW_CODE_POINTS = /[\u{202e}\u{200b}\u{7f}]/u;
+
+		it("escapes DEL/Cf in a top-level string arg value; the query still parses", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts"];
+			// A scalar arg value (like a scope token) carrying poisoned bytes.
+			setArg(session, ["accounts"], "first", POISON);
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+
+			const query = renderQuery(session);
+			// The dangerous code points appear ONLY as \uXXXX, never raw.
+			expect(query).not.toMatch(RAW_CODE_POINTS);
+			expect(query).toContain("\\u202e");
+			expect(query).toContain("\\u200b");
+			expect(query).toContain("\\u007f");
+			// Live-document round-trip: the escaped literal must still parse.
+			expect(() => parse(query)).not.toThrow();
+		});
+
+		it("escapes DEL/Cf in a well-formed quoted string-literal arg value (the passthrough branch); the query still parses", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts"];
+			// The value is ITSELF a well-formed quoted JSON string literal carrying the
+			// poisoned bytes, so formatArgValue takes its quoted-passthrough branch
+			// (query-builder.ts ~L291) — the third W-23336442 escape site, distinct from
+			// the default JSON.stringify branch and the valueToGraphQL path. JSON.parse
+			// accepts the raw DEL/Cf (legal unescaped inside a JSON string), so WITHOUT
+			// the post-escape the raw bytes would reflect verbatim into the live query.
+			setArg(session, ["accounts"], "first", JSON.stringify(POISON));
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+
+			const query = renderQuery(session);
+			expect(query).not.toMatch(RAW_CODE_POINTS);
+			expect(query).toContain("\\u202e");
+			expect(query).toContain("\\u200b");
+			expect(query).toContain("\\u007f");
+			expect(() => parse(query)).not.toThrow();
+		});
+
+		it("escapes DEL/Cf inside a nested filter-object string value (the valueToGraphQL path)", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts"];
+			// Mirrors buildList: JSON.stringify(spec.filter) stored as `where`, then
+			// rendered via jsonToGraphQL -> valueToGraphQL. The poisoned bytes live in
+			// a nested input-object string value.
+			const filter = { name: { like: POISON } };
+			deepSetArg(session, ["accounts"], "where", [], JSON.stringify(filter));
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+
+			const query = renderQuery(session);
+			expect(query).not.toMatch(RAW_CODE_POINTS);
+			expect(query).toContain("\\u202e");
+			expect(query).toContain("\\u200b");
+			expect(query).toContain("\\u007f");
+			expect(() => parse(query)).not.toThrow();
+		});
+
+		it("escapes an astral tag char (U+E0001) as a GraphQL-valid surrogate pair, never \\u{...}", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts"];
+			setArg(session, ["accounts"], "first", "x\u{e0001}y");
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+
+			const query = renderQuery(session);
+			expect(query).not.toMatch(/\u{e0001}/u); // no raw astral tag char
+			expect(query).not.toContain("\\u{"); // never the variable-width form
+			expect(query).toContain("\\udb40\\udc01"); // the surrogate pair
+			expect(() => parse(query)).not.toThrow();
+		});
+
+		it("does not disturb $var, numeric, enum, or boolean value paths", () => {
+			const session = makeSession();
+			addVariable(session, "$lim", "Int");
+			session.navigationPath = ["query", "accounts"];
+			// $var placeholder — emitted bare, not quoted or escaped.
+			setArg(session, ["accounts"], "first", "$lim");
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+
+			const query = renderQuery(session);
+			expect(query).toMatch(/first: \$lim\b/);
+			expect(query).not.toContain('"$lim"');
+			expect(() => parse(query)).not.toThrow();
+
+			// Numeric / boolean / enum defaults stay bare (unquoted, unescaped).
+			function withDefault(type: string, value: string): string {
+				const s = makeSession();
+				addVariable(s, "d", type, value);
+				s.navigationPath = ["query", "accounts", "edges", "node"];
+				selectLeaf(s, ["accounts", "edges", "node", "name"]);
+				return renderQuery(s);
+			}
+			expect(withDefault("Int", "42")).toContain("$d: Int = 42");
+			expect(withDefault("Boolean", "true")).toContain("$d: Boolean = true");
+			expect(withDefault("SortOrder", "DESC")).toContain("$d: SortOrder = DESC");
+		});
+
+		it("does not over-block ordinary Unicode string values (accents, CJK, emoji)", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts"];
+			const ok = "café 日本語 \u{1f600}";
+			setArg(session, ["accounts"], "first", ok);
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+
+			const query = renderQuery(session);
+			// Ordinary Unicode passes through verbatim inside the literal.
+			expect(query).toContain(`first: ${JSON.stringify(ok)}`);
+			expect(() => parse(query)).not.toThrow();
+		});
+	});
 });

package/src/lib/control-chars.ts

@@ -47,6 +47,44 @@ export function stripControlChars(s: string): string {
 	return s.replace(CONTROL_CHAR_RE, "");
 }
 
+/**
+ * Escape every {@link CONTROL_CHAR_RE} code point to a GraphQL-valid `\uXXXX`
+ * escape, for reflection into a LIVE GraphQL DOCUMENT — the value-emission sites
+ * in `lib/query-builder.ts` (`sf_gql_list` scope/filter/orderBy values, and any
+ * nested input-object string, W-23336442). `JSON.stringify` already escapes the
+ * C0 range (U+0000-U+001F) when it builds the quoted literal, but leaves DEL
+ * (U+007F) and the ENTIRE Cf class (bidi overrides, zero-width, BOM, tag block)
+ * raw inside the quotes; this post-pass converts those survivors so the emitted
+ * query still `graphql.parse()`s and carries no smuggled/reordering code points.
+ *
+ * WHY `\uXXXX`-ONLY (and NOT the `\xNN` / `\u{...}` forms that
+ * `neutralizeControlChars` in `schemas/tool-adapter.ts` emits): the output here
+ * is a GraphQL string literal, whose grammar accepts ONLY `\uXXXX` (four fixed
+ * hex digits) as a Unicode escape. `\xNN` is not a GraphQL escape at all — it
+ * would make the document un-parseable — and the variable-width `\u{...}` form
+ * is not accepted by every GraphQL parser. So this escaper deliberately DIVERGES
+ * from the plain-JSON `neutralizeControlChars` (whose `\xNN`/`\u{...}` output is
+ * fine for a JSON envelope but fatal in a query):
+ *  - BMP code points  -> a single lower-case `\uXXXX` (4 hex).
+ *  - Astral code points (e.g. the U+E0000-E007F tag block) -> a UTF-16 surrogate
+ *    PAIR `\uXXXX\uXXXX`, which is universally GraphQL-valid, rather than `\u{...}`.
+ * Ordinary Unicode (accented names, CJK labels, emoji) and the Zl/Zp separators
+ * are untouched — they are outside the Cc/Cf class (see {@link CONTROL_CHAR_RE}).
+ */
+export function escapeControlCharsGraphQL(s: string): string {
+	return s.replace(CONTROL_CHAR_RE, (c) => {
+		// CONTROL_CHAR_RE carries the `u` flag, so an astral char matches as one
+		// code point; codePointAt(0) recovers its full scalar value.
+		const cp = c.codePointAt(0) ?? 0;
+		if (cp <= 0xffff) return `\\u${cp.toString(16).padStart(4, "0")}`;
+		// Astral: split into a high/low UTF-16 surrogate pair (never `\u{...}`).
+		const v = cp - 0x10000;
+		const hi = 0xd800 + (v >> 10);
+		const lo = 0xdc00 + (v & 0x3ff);
+		return `\\u${hi.toString(16).padStart(4, "0")}\\u${lo.toString(16).padStart(4, "0")}`;
+	});
+}
+
 /**
  * Unicode line/paragraph separators (U+2028 Zl / U+2029 Zp). These are legal in
  * JSON strings and are NOT escaped by `JSON.stringify`, and left raw in

package/src/lib/query-builder.ts

@@ -4,6 +4,7 @@
  * For full license text, see the LICENSE.txt file
  */
 
+import { escapeControlCharsGraphQL } from "./control-chars.js";
 import { UserInputError } from "./errors.js";
 import { assertGraphqlName, GRAPHQL_NAME_RE } from "./graphql-name.js";
 import type { QuerySession, ProjectionNode, DirectiveNode } from "./session.js";
@@ -284,7 +285,10 @@ function formatArgValue(value: string): string {
 	// single literal.
 	if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
 		try {
-			if (typeof JSON.parse(trimmed) === "string") return trimmed;
+			// W-23336442: even a well-formed single literal can carry raw DEL/Cf
+			// inside the quotes (JSON permits them raw), so escape before passthrough
+			// (see the default branch below for the full rationale).
+			if (typeof JSON.parse(trimmed) === "string") return escapeControlCharsGraphQL(trimmed);
 		} catch {
 			// Not a single well-formed literal — re-encode below.
 		}
@@ -295,7 +299,15 @@ function formatArgValue(value: string): string {
 	// quotes/backslashes — so values like "a\nb" don't render a raw newline that
 	// graphql.parse() would reject as an unterminated string. (U+2028/U+2029 pass
 	// through raw and are handled at the MCP text boundary, not here.)
-	return JSON.stringify(trimmed);
+	//
+	// W-23336442: JSON.stringify escapes ONLY the C0 range (U+0000-U+001F); it
+	// leaves DEL (U+007F) and the entire Cf class (bidi overrides, zero-width, BOM,
+	// tag block) RAW inside the quoted literal. This query is a LIVE GraphQL
+	// document reflected to the host, so those survivors would smuggle/reorder text
+	// (sf_gql_list scope/filter/orderBy values reach here verbatim). Post-pass with
+	// escapeControlCharsGraphQL, which emits GraphQL-valid `\uXXXX` (never `\xNN`,
+	// which GraphQL rejects) so the query still graphql.parse()s.
+	return escapeControlCharsGraphQL(JSON.stringify(trimmed));
 }
 
 /**
@@ -348,7 +360,13 @@ function valueToGraphQL(value: unknown): string {
 		// terminators and control chars (\n \r \t \b \f), unlike a manual \ / " escape
 		// which would leave a raw newline that graphql.parse() rejects. (U+2028/U+2029
 		// pass through raw and are handled at the MCP text boundary, not here.)
-		return JSON.stringify(value);
+		//
+		// W-23336442: JSON.stringify escapes only C0, leaving DEL (U+007F) + the Cf
+		// class raw inside the literal. This is a nested input-object string value in
+		// a LIVE GraphQL document (filter/orderBy values JSON.stringify'd into a
+		// `where` arg reach here), so post-pass with escapeControlCharsGraphQL to emit
+		// GraphQL-valid `\uXXXX` (never `\xNN`) — same rationale as formatArgValue.
+		return escapeControlCharsGraphQL(JSON.stringify(value));
 	}
 	if (Array.isArray(value)) {
 		return `[${value.map(valueToGraphQL).join(", ")}]`;

package/src/schemas/__tests__/input-schemas.spec.ts

@@ -9,6 +9,7 @@ import {
 	AGGREGATE_INPUT,
 	CREATE_INPUT,
 	DETAIL_INPUT,
+	DISCOVER_INPUT,
 	LIST_INPUT,
 	UPDATE_INPUT,
 } from "../input-schemas.js";
@@ -151,3 +152,69 @@ describe("schemas/input-schemas — field-path charset validation (W-22735537)",
 		).toBe(true);
 	});
 });
+
+/**
+ * Contract for the `sf_gql_discover` `search` guard (W-23336442). `search` is a
+ * free-text substring filter reflected VERBATIM through the SUCCESS envelope
+ * (schemas/tool-adapter.ts runTool), which neutralizes neither Cc nor Cf —
+ * JSON.stringify escapes only C0 (U+0000-U+001F), leaving DEL (U+007F) and the
+ * ENTIRE Cf class (bidi overrides, zero-width, BOM, U+E0000-E007F tag block)
+ * raw. DISCOVER_SEARCH_RE must therefore REJECT the full Cc/Cf class, matching
+ * lib/control-chars.ts CONTROL_CHAR_RE — not just the C0/DEL subset the earlier
+ * /^[^\x00-\x1f\x7f]*$/ range caught.
+ *
+ * Injected chars are `\u` escapes, not literals, so the source carries no
+ * invisible bytes. Ordinary Unicode (café, 日本語) may appear as literals.
+ */
+describe("schemas/input-schemas — DISCOVER_INPUT.search Cc/Cf guard (W-23336442)", () => {
+	const base = { org: "myorg", mode: "list_objects" as const };
+
+	const parseSearch = (search: string) => DISCOVER_INPUT.safeParse({ ...base, search });
+
+	describe("REJECTS control/format (Cc/Cf) chars", () => {
+		it.each([
+			// Cf class — the gap the old C0/DEL-only range let through.
+			["ZWSP U+200B (Cf, zero-width)", "Acc\u{200b}ount"],
+			["RLO U+202E (Cf, bidi override)", "Acc\u{202e}ount"],
+			["tag char U+E0001 (Cf, tag block)", "Acc\u{e0001}ount"],
+			["BOM/ZWNBSP U+FEFF (Cf)", "\u{feff}Account"],
+			["soft hyphen U+00AD (Cf)", "Acc\u{00ad}ount"],
+			// Cc class — still rejected, as before.
+			["NUL U+0000 (Cc, C0)", "Acc\u{0000}ount"],
+			["ESC U+001B (Cc, C0)", "Acc\u{001b}ount"],
+			["DEL U+007F (Cc)", "Acc\u{007f}ount"],
+			["NEL U+0085 (Cc, C1)", "Acc\u{0085}ount"],
+		])("%s is rejected", (_label, search) => {
+			const result = parseSearch(search);
+			expect(result.success).toBe(false);
+			if (!result.success) {
+				const searchIssue = result.error.issues.find((i) => i.path[0] === "search");
+				expect(searchIssue?.message).toBe("search must not contain control characters");
+			}
+		});
+	});
+
+	describe("ACCEPTS ordinary printable Unicode", () => {
+		it.each([
+			["plain ASCII", "Account"],
+			["accented Latin (café)", "café"],
+			["CJK (日本語)", "日本語"],
+			["spaces", "My Custom Object"],
+			["punctuation and digits", "Order__c v2 (2026)"],
+			["empty string", ""],
+		])("%s is accepted", (_label, search) => {
+			const result = parseSearch(search);
+			expect(result.success).toBe(true);
+			if (result.success) expect(result.data.search).toBe(search);
+		});
+	});
+
+	it("still enforces the 100-char length cap alongside the Cc/Cf guard", () => {
+		const result = parseSearch("a".repeat(101));
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const searchIssue = result.error.issues.find((i) => i.path[0] === "search");
+			expect(searchIssue?.message).toBe("search must be 100 characters or fewer");
+		}
+	});
+});