@salesforce/graphiti 11.34.0 → 11.34.2

package/src/schemas/__tests__/fields.spec.ts

@@ -0,0 +1,182 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { enumStripControlChars } from "../fields.js";
+
+/**
+ * Unit-level contract for enumStripControlChars (W-23336443): the z.preprocess
+ * wrapper that STRIPS Unicode control/format chars from a string before enum
+ * validation, so a poisoned value can never be reflected verbatim by the MCP
+ * SDK's upstream validation. End-to-end proof that it closes the actual SDK
+ * reflection channel lives in the sf-gql-* tool specs; here we pin the wrapper's
+ * behavior in isolation (accept-after-strip, clean rejection, pass-throughs) and
+ * document the discriminatedUnion caveat with an executable proof.
+ *
+ * Injected chars are `\u` escapes, not literals, so the source has no invisible
+ * bytes. Representative one-per-class: U+202E (bidi RLO), U+200B (ZWSP), U+007F
+ * (DEL) -- the exact trio the SDK's JSON.stringify leaves raw (it escapes only
+ * C0, U+0000-U+001F).
+ */
+describe("schemas/fields — enumStripControlChars (W-23336443)", () => {
+	const MODE = enumStripControlChars(z.enum(["list_objects", "describe_object", "describe_field"]));
+
+	describe("accept-after-strip", () => {
+		it.each([
+			["trailing bidi RLO", "describe_object\u{202e}", "describe_object"],
+			["leading ZWSP", "\u{200b}list_objects", "list_objects"],
+			["embedded DEL", "describe\x7f_field", "describe_field"],
+			["interior ZWJ", "describe_ob\u{200d}ject", "describe_object"],
+		])("%s strips to the valid member and PARSES to it", (_label, input, expected) => {
+			const result = MODE.safeParse(input);
+			expect(result.success).toBe(true);
+			if (result.success) expect(result.data).toBe(expected);
+		});
+
+		it("a clean value is unchanged", () => {
+			const result = MODE.safeParse("list_objects");
+			expect(result.success).toBe(true);
+			if (result.success) expect(result.data).toBe("list_objects");
+		});
+
+		it.each([
+			["trailing line separator U+2028", "list_objects\u{2028}", "list_objects"],
+			["leading paragraph separator U+2029", "\u{2029}describe_object", "describe_object"],
+		])(
+			"%s is ALSO stripped (Zl/Zp, out of the Cc/Cf class but stripped on this path)",
+			(_label, input, expected) => {
+				// W-23336443 / F2: this rejection path reaches the host UPSTREAM of the
+				// envelope's own line-separator strip, so enumStripControlChars must
+				// strip U+2028/U+2029 itself (raw, they trip a Claude.AI 408). They are
+				// NOT Cc/Cf, so stripControlChars alone would miss them.
+				const result = MODE.safeParse(input);
+				expect(result.success).toBe(true);
+				if (result.success) expect(result.data).toBe(expected);
+			},
+		);
+
+		it("a genuinely-invalid value poisoned with U+2028/U+2029 rejects with neither separator raw", () => {
+			const result = MODE.safeParse("bo\u{2028}gus\u{2029}");
+			expect(result.success).toBe(false);
+			if (!result.success) {
+				const serialized = JSON.stringify(result.error.issues);
+				expect(serialized).not.toContain("\u{2028}");
+				expect(serialized).not.toContain("\u{2029}");
+				const received = (result.error.issues[0] as { received?: string }).received;
+				expect(received).toBe("bogus");
+			}
+		});
+	});
+
+	describe("clean rejection", () => {
+		it("a poisoned genuinely-invalid value rejects with NO raw control char in the message", () => {
+			// "bogus" + bidi + ZWSP + DEL. Strips to "bogus", which is not a member,
+			// so it rejects -- but zod reflects the STRIPPED value, so the specific
+			// injected code points must be absent from the issue.
+			const result = MODE.safeParse("bo\u{202e}gus\u{200b}\x7f");
+			expect(result.success).toBe(false);
+			if (!result.success) {
+				const serialized = JSON.stringify(result.error.issues);
+				// Assert the SPECIFIC injected code points are gone (a whole-class
+				// /[\p{Cc}\p{Cf}]/ check would false-positive on any structural
+				// whitespace zod/JSON introduce -- see control-chars.spec.ts note).
+				expect(serialized).not.toContain("\u{202e}");
+				expect(serialized).not.toContain("\u{200b}");
+				expect(serialized).not.toContain("\x7f");
+				// The reflected received value is the stripped token.
+				const received = (result.error.issues[0] as { received?: string }).received;
+				expect(received).toBe("bogus");
+			}
+		});
+
+		it("preserves the enum options in the issue (LLM still learns the allowed set)", () => {
+			const result = MODE.safeParse("bogus");
+			expect(result.success).toBe(false);
+			if (!result.success) {
+				const issue = result.error.issues[0] as { options?: string[] };
+				expect(issue.options).toEqual(["list_objects", "describe_object", "describe_field"]);
+			}
+		});
+	});
+
+	describe("pass-through of non-strings and optional/undefined", () => {
+		it("undefined passes through an optional wrapped enum (stays optional)", () => {
+			const OP = enumStripControlChars(z.enum(["query", "mutation", "aggregate"]).optional());
+			const result = OP.safeParse(undefined);
+			expect(result.success).toBe(true);
+			if (result.success) expect(result.data).toBeUndefined();
+		});
+
+		it("a non-string value is handed to the inner schema untouched (rejects as a type error)", () => {
+			const result = MODE.safeParse(42);
+			expect(result.success).toBe(false);
+			// The preprocess only strips strings; a number falls straight through
+			// to z.enum, which rejects it as an invalid_type / invalid_enum_value.
+		});
+	});
+
+	describe("published JSON-Schema shape is preserved (zod .describe passes through)", () => {
+		it("keeps the .describe() description on the wrapped enum", () => {
+			const described = enumStripControlChars(z.enum(["query", "mutation", "aggregate"])).describe(
+				"Operation root.",
+			);
+			expect(described.description).toBe("Operation root.");
+		});
+	});
+
+	describe("discriminatedUnion caveat (why the aggregate `function` enum is NOT wrapped)", () => {
+		// Executable proof that leaving discriminators un-wrapped is SAFE, and of
+		// the true reason (the WI's "breaks construction / narrow residual is
+		// reflected" rationale was imprecise for zod 3.25.76): a bad discriminator
+		// raises `invalid_union_discriminator`, whose issue lists only the EXPECTED
+		// options and does NOT echo the received value — so, unlike a plain
+		// `invalid_enum_value`, there is no verbatim-reflection channel to close.
+		it("a bad discriminator does NOT echo the received value (no reflection channel)", () => {
+			const du = z.discriminatedUnion("function", [
+				z.object({ function: z.enum(["count", "countDistinct"]), field: z.string().optional() }),
+				z.object({ function: z.enum(["sum", "avg", "min", "max"]), field: z.string() }),
+			]);
+			// A control-char-poisoned discriminator: it never matches a branch, so
+			// discrimination fails BEFORE any per-branch enum check would run.
+			const result = du.safeParse({ function: "count\u{202e}\u{200b}\x7f", field: "Amount" });
+			expect(result.success).toBe(false);
+			if (!result.success) {
+				const issue = result.error.issues[0] as {
+					code: string;
+					options?: string[];
+					received?: unknown;
+				};
+				expect(issue.code).toBe("invalid_union_discriminator");
+				// Lists the expected set...
+				expect(issue.options).toEqual(["count", "countDistinct", "sum", "avg", "min", "max"]);
+				// ...and crucially carries NO `received` echo of the poisoned input.
+				const serialized = JSON.stringify(result.error.issues);
+				expect(serialized).not.toContain("\u{202e}");
+				expect(serialized).not.toContain("\u{200b}");
+				expect(serialized).not.toContain("\x7f");
+			}
+		});
+
+		it("a plain z.union member CAN be wrapped safely (the groupBy `function` case)", () => {
+			const grouped = z.union([
+				z.string(),
+				z.object({
+					field: z.string(),
+					function: enumStripControlChars(z.enum(["CALENDAR_MONTH", "CALENDAR_YEAR"])),
+				}),
+			]);
+			const result = grouped.safeParse({
+				field: "CreatedDate",
+				function: "CALENDAR_MONTH\u{202e}",
+			});
+			expect(result.success).toBe(true);
+			if (result.success && typeof result.data === "object") {
+				expect((result.data as { function: string }).function).toBe("CALENDAR_MONTH");
+			}
+		});
+	});
+});

package/src/schemas/fields.ts

@@ -5,6 +5,7 @@
  */
 
 import { z } from "zod";
+import { stripControlChars, stripLineSeparators } from "../lib/control-chars.js";
 import { DOTTED_GRAPHQL_NAME_RE, GRAPHQL_NAME_RE } from "../lib/graphql-name.js";
 
 /**
@@ -40,6 +41,52 @@ const coerceJsonOnce = (v: unknown): unknown => {
 /** Wrap a schema so a JSON-stringified value is coerced before validation. */
 export const jsonCoercible = (schema: z.ZodTypeAny) => z.preprocess(coerceJsonArg, schema);
 
+/**
+ * Wrap an enum (or any string schema) so Unicode control/format chars are
+ * STRIPPED from a string value before validation (W-23336443). Motivation: a
+ * `z.enum` rejection is reflected VERBATIM by the MCP SDK's input validation,
+ * which runs UPSTREAM of `runTool` — so the adapter's `neutralizeControlChars`
+ * never executes, and a poisoned value like `"describe_object‮"` reaches
+ * the host raw inside `received '…'`. `JSON.stringify` (which the SDK uses)
+ * escapes only C0, so DEL and the entire Cf class (bidi overrides, zero-width)
+ * survive. Stripping here closes that channel two ways: a control-char-poisoned
+ * but otherwise-valid value strips to the valid enum member (accepted, no
+ * message), and a genuinely-invalid value rejects with a message free of raw
+ * control chars.
+ *
+ * This upstream path also strips U+2028/U+2029 (via {@link stripLineSeparators}),
+ * matching what every envelope sink does in `tool-adapter.ts`: those separators
+ * are NOT Cc/Cf so `stripControlChars` correctly ignores them, but left raw in
+ * host-visible text they trip a Claude.AI 408 (MCP TS SDK #2155) — and this
+ * rejection message reaches the host BEFORE the envelope's own line-separator
+ * strip can run, so it must strip them itself.
+ *
+ * Why `z.preprocess` and not `.refine`: preprocess can TRANSFORM (strip) the
+ * value, and — verified against the SDK's zod-to-json-schema converter — the
+ * wrapper PRESERVES the published JSON-Schema `enum` and `description`, so the
+ * advertised allowed-value list the LLM sees is unchanged. `.refine` can only
+ * reject, not strip.
+ *
+ * CAVEAT: applying this to a `z.discriminatedUnion` discriminator member is
+ * pointless, though not harmful. It is NOT harmful because zod's discriminator-
+ * map builder recurses through a `z.preprocess` wrapper (`getDiscriminator`
+ * reads `ZodEffects.innerType()`), so construction does NOT throw and clean
+ * values still route correctly (verified against zod 3.25.76 on AGGREGATE_INPUT).
+ * It is POINTLESS because discrimination reads the RAW `ctx.data[discriminator]`
+ * to pick a branch BEFORE that branch's preprocess ever runs — so the strip
+ * cannot influence branch selection. A discriminator that matches no branch
+ * raises `invalid_union_discriminator`, whose issue lists only the EXPECTED
+ * options and does NOT echo the received value — so, unlike a plain
+ * `invalid_enum_value`, there is no verbatim-reflection channel there to close.
+ * The aggregate `function` discriminators are therefore left un-wrapped per
+ * W-23336443; only plain enums (invalid_enum_value DOES echo `received`) need it.
+ */
+export const enumStripControlChars = <T extends z.ZodTypeAny>(schema: T) =>
+	z.preprocess(
+		(v) => (typeof v === "string" ? stripLineSeparators(stripControlChars(v)) : v),
+		schema,
+	);
+
 /** A string that looks like a JSON object/array literal — used so the advertised
  *  schema accepts a stringified object/array; coerceJsonArg then parses it. A
  *  `{`/`[`-prefixed but invalid-JSON string is accepted as a literal (rare; the

package/src/schemas/input-schemas.ts

@@ -20,6 +20,7 @@ import { z } from "zod";
 import {
 	childRelationshipSchema,
 	dottedGraphqlName,
+	enumStripControlChars,
 	graphqlName,
 	intLiteralString,
 	jsonCoercible,
@@ -139,11 +140,13 @@ export const DISCOVER_INPUT = z.object({
 		.string()
 		.regex(DISCOVER_ORG_ALIAS_RE, "org must match /^[A-Za-z0-9_-]{1,80}$/")
 		.describe("Org alias resolved via local Salesforce CLI auth (~/.sf, ~/.sfdx)."),
-	mode: z
-		.enum(["list_objects", "describe_object", "describe_field"])
-		.describe(
-			'Discovery mode. "list_objects" enumerates queryable SObjects; "describe_object" and "describe_field" return ObjectInfo metadata.',
-		),
+	// enumStripControlChars: a bad `mode` is reflected verbatim by the SDK's
+	// upstream validation (W-23336443) — strip Cc/Cf before it can reach the host.
+	mode: enumStripControlChars(
+		z.enum(["list_objects", "describe_object", "describe_field"]),
+	).describe(
+		'Discovery mode. "list_objects" enumerates queryable SObjects; "describe_object" and "describe_field" return ObjectInfo metadata.',
+	),
 	object: z
 		.string()
 		.regex(DISCOVER_SOBJECT_NAME_RE, "object must match /^[A-Za-z][A-Za-z0-9_]{0,79}$/")
@@ -169,6 +172,17 @@ const aliasField = z
 	.optional()
 	.describe("GraphQL alias for this aggregation's result key.");
 
+// NOTE (W-23336443): the `function` enums below are z.discriminatedUnion
+// DISCRIMINATORS — they are intentionally NOT wrapped in enumStripControlChars.
+// Wrapping would be pointless (not harmful): discrimination reads the RAW
+// `ctx.data.function` to pick a branch BEFORE that branch's preprocess runs, so
+// a strip could never change branch selection. And there is nothing to close: a
+// discriminator that matches no branch raises `invalid_union_discriminator`,
+// whose issue lists only the EXPECTED options and does NOT echo the received
+// value (verified, zod 3.25.76) — unlike a plain enum's `invalid_enum_value`,
+// which reflects `received` verbatim. The three plain enums that DO echo their
+// input (mode/operation/groupBy function) are the ones wrapped. See
+// enumStripControlChars in ./fields for the full mechanism.
 const aggregationSchema = z.discriminatedUnion("function", [
 	z.object({
 		function: z.enum(["count", "countDistinct"]),
@@ -186,9 +200,11 @@ const groupByElementSchema = z.union([
 	graphqlName("SObject field API name to group by (flat, non-dotted)."),
 	z.object({
 		field: graphqlName("SObject field API name (DateTime/Date field)."),
-		function: z
-			.enum(GROUP_BY_FUNCTIONS)
-			.describe("Date bucketing function from UIAPI GroupByFunction enum."),
+		// Plain z.union member (NOT a discriminatedUnion discriminator), so the
+		// enumStripControlChars wrapper is safe here (W-23336443).
+		function: enumStripControlChars(z.enum(GROUP_BY_FUNCTIONS)).describe(
+			"Date bucketing function from UIAPI GroupByFunction enum.",
+		),
 	}),
 ]);
 
@@ -254,12 +270,12 @@ export const RAW_INPUT = z.object({
 				'Each command is tokenized on spaces and a value MUST NOT contain a space — quoting does not help once a token has started (key=\'a b\' still splits). A filter value that contains a space (e.g. "New York", "In Progress") cannot be expressed via set in v1; use sf_gql_list with a JSON filter, or pass the value through a variable bound with var.\n' +
 				"Fails fast: a bad command aborts the whole call. Other CLI verbs (cd, drop, alias, optional, unset) are NOT supported in v1 — and the `optional` verb is unnecessary here: like every declarative tool, sf_gql_raw emits all selected record fields with the @optional directive automatically, so a field the running user lacks FLS for is omitted gracefully instead of failing the whole query.",
 		),
-	operation: z
-		.enum(["query", "mutation", "aggregate"])
-		.optional()
-		.describe(
-			'Operation root. "query" (default) → uiapi.query; "mutation" → mutation root; "aggregate" → uiapi.aggregate.',
-		),
+	// enumStripControlChars strips Cc/Cf from a bad `operation` before the SDK
+	// reflects it verbatim in a rejection message (W-23336443); the wrapper
+	// preserves the published enum + optional flag (undefined passes through).
+	operation: enumStripControlChars(z.enum(["query", "mutation", "aggregate"]).optional()).describe(
+		'Operation root. "query" (default) → uiapi.query; "mutation" → mutation root; "aggregate" → uiapi.aggregate.',
+	),
 	typeName: graphqlName(
 		"Override the GraphQL operation name. Defaults to Raw<Operation>.",
 	).optional(),

package/src/schemas/tool-adapter.ts

@@ -5,6 +5,7 @@
  */
 
 import os from "node:os";
+import { CONTROL_CHAR_RE, stripLineSeparators } from "../lib/control-chars.js";
 import {
 	AuthError,
 	classifyCause,
@@ -82,26 +83,15 @@ export const PATH_MARKERS = {
 	redacted: "<path>",
 } as const;
 
-// Unicode line separators (U+2028/U+2029) are legal in JSON strings but are NOT
-// escaped by JSON.stringify; left raw in `content.text` they trip a Claude.AI 408
-// timeout (MCP TS SDK #2155). Strip them from every host-visible envelope.
-const LINE_SEPARATOR_RE = /[\u2028\u2029]/g;
-function stripLineSeparators(s: string): string {
-	return s.replace(LINE_SEPARATOR_RE, "");
-}
-
-// Control (Cc: C0/C1/DEL) and format (Cf) characters that, left raw in reflected
-// error text, let caller-supplied input forge structure in the host-visible MCP
-// envelope (W-23148363, OWASP LLM01): newlines/CR fabricate "SYSTEM:"-style lines,
-// ESC (\x1b) opens ANSI/SGR sequences, NEL (U+0085) and the C1 8-bit CSI (\x9b) are
-// alternate line/escape introducers, and the Cf set (bidi overrides/marks/isolates
-// incl U+061C, zero-width joiners/spaces, word joiner, BOM, invisible-math operators,
-// soft hyphen, and the U+E0000-E007F "tag" smuggling block) reorders or hides text.
-// Matched by Unicode property class so the set tracks future Cc/Cf additions instead
-// of a hand-enumerated range that drifts (an earlier explicit range silently missed
-// U+061C / ZWNJ / ZWJ / tag chars -- all Cf). The ERROR envelope interpolates the
-// message raw (`${category}: ${text}`), so every one of these reaches the host
-// unescaped -- which is the vector this neutralizer closes.
+// `stripLineSeparators` (imported) removes U+2028/U+2029 from every host-visible
+// envelope below (they trip a Claude.AI 408 \u2014 see `lib/control-chars.ts`). Shared
+// with the enum-rejection path (W-23336443) so the two sinks cannot drift.
+//
+// The Cc/Cf class this escaper acts on is the shared CONTROL_CHAR_RE (see
+// `lib/control-chars.ts` for the full rationale — why bidi/zero-width/tag chars
+// are dangerous and why a Unicode property class is used over a hand-enumerated
+// range). Imported, not re-declared, so this ERROR-envelope escaper and the
+// enum-rejection stripper (W-23336443) cannot drift apart.
 //   SUCCESS-ENVELOPE SCOPE (W-23148363): the success path (runTool below) emits
 //   JSON.stringify(output), which escapes ONLY the C0 range (U+0000-U+001F). DEL
 //   (U+007F) and the ENTIRE Cf class (bidi overrides, zero-width, BOM, tag block)
@@ -115,9 +105,7 @@ function stripLineSeparators(s: string): string {
 //   Value-level neutralization is tracked as a follow-up WI -- note it must emit
 //   GraphQL-valid `\uXXXX` (never `\xNN`) since the success `query` is a live
 //   GraphQL document, so the whole-envelope neutralizer here cannot be reused as-is.
-// U+2028/U+2029 are deliberately absent (they are Zl/Zp, not Cc/Cf): stripLineSeparators
-// removes them entirely, and runs first.
-const NEUTRALIZE_RE = /[\p{Cc}\p{Cf}]/gu;
+// CONTROL_CHAR_RE carries the `g` + `u` flags, required by the `.replace` below.
 
 /**
  * Escape (not strip) control / format characters in host-visible error text so
@@ -125,11 +113,11 @@ const NEUTRALIZE_RE = /[\p{Cc}\p{Cf}]/gu;
  * (W-23148363). Escaping mirrors the SUCCESS envelope's JSON.stringify semantics
  * (`\n` -> `\\x0a`, U+202E -> `\\u202e`) -- the byte stays visible for debugging but
  * inert. Ordinary Unicode (accented names, CJK labels) is untouched. Astral code
- * points (e.g. the U+E0000-E007F tag block) render as `\\u{...}`; `NEUTRALIZE_RE`
+ * points (e.g. the U+E0000-E007F tag block) render as `\\u{...}`; `CONTROL_CHAR_RE`
  * carries the `u` flag so they match (and escape) as a single code point.
  */
 export function neutralizeControlChars(s: string): string {
-	return s.replace(NEUTRALIZE_RE, (c) => {
+	return s.replace(CONTROL_CHAR_RE, (c) => {
 		const cp = c.codePointAt(0) ?? 0;
 		if (cp <= 0xff) return `\\x${cp.toString(16).padStart(2, "0")}`;
 		if (cp <= 0xffff) return `\\u${cp.toString(16).padStart(4, "0")}`;