@salesforce/graphiti 11.31.15 → 11.32.0

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

@@ -0,0 +1,153 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+	AGGREGATE_INPUT,
+	CREATE_INPUT,
+	DETAIL_INPUT,
+	LIST_INPUT,
+	UPDATE_INPUT,
+} from "../input-schemas.js";
+
+/**
+ * W-22735537 — zod-boundary charset validation for caller-supplied field-path /
+ * scope inputs. These guard the layered defense: a silent revert of a
+ * `dottedGraphqlName()` / `scopeArg()` field back to `z.string()` would reopen
+ * the selection-set injection at the MCP boundary and these tests would fail.
+ * (filter/orderBy object-KEY validation is enforced in the builder layer, not
+ * zod, so it is covered by the build-* specs, not here.)
+ */
+const BREAKOUT = "Id } injectedAlias: Name { value";
+
+describe("schemas/input-schemas — field-path charset validation (W-22735537)", () => {
+	it("CREATE_INPUT rejects a returnFields breakout; accepts a dotted path", () => {
+		expect(
+			CREATE_INPUT.safeParse({ org: "o", object: "Account", returnFields: [BREAKOUT] }).success,
+		).toBe(false);
+		expect(
+			CREATE_INPUT.safeParse({ org: "o", object: "Account", returnFields: ["Id", "Owner.Name"] })
+				.success,
+		).toBe(true);
+	});
+
+	it("UPDATE_INPUT rejects a returnFields breakout", () => {
+		expect(
+			UPDATE_INPUT.safeParse({ org: "o", object: "Account", returnFields: [BREAKOUT] }).success,
+		).toBe(false);
+	});
+
+	it("LIST_INPUT rejects fields/parentFields/scope breakouts; accepts legit", () => {
+		expect(LIST_INPUT.safeParse({ org: "o", object: "Account", fields: [BREAKOUT] }).success).toBe(
+			false,
+		);
+		expect(
+			LIST_INPUT.safeParse({
+				org: "o",
+				object: "Account",
+				fields: ["Id"],
+				parentFields: [BREAKOUT],
+			}).success,
+		).toBe(false);
+		expect(
+			LIST_INPUT.safeParse({
+				org: "o",
+				object: "Account",
+				fields: ["Id"],
+				scope: "{}) { Id } x: Account(scope: MINE",
+			}).success,
+		).toBe(false);
+		expect(
+			LIST_INPUT.safeParse({
+				org: "o",
+				object: "Account",
+				fields: ["Id", "Owner.Name"],
+				scope: "MINE",
+			}).success,
+		).toBe(true);
+		expect(
+			LIST_INPUT.safeParse({ org: "o", object: "Account", fields: ["Id"], scope: "$myScope" })
+				.success,
+		).toBe(true);
+	});
+
+	it("LIST_INPUT rejects a childRelationships[].fields breakout at the boundary", () => {
+		expect(
+			LIST_INPUT.safeParse({
+				org: "o",
+				object: "Account",
+				fields: ["Id"],
+				childRelationships: [{ relationshipName: "Contacts", fields: [BREAKOUT] }],
+			}).success,
+		).toBe(false);
+	});
+
+	it("DETAIL_INPUT rejects a fields breakout; accepts a dotted path", () => {
+		expect(
+			DETAIL_INPUT.safeParse({ org: "myorg", object: "Account", fields: [BREAKOUT] }).success,
+		).toBe(false);
+		expect(
+			DETAIL_INPUT.safeParse({ org: "myorg", object: "Account", fields: ["Id", "Owner.Name"] })
+				.success,
+		).toBe(true);
+	});
+
+	it("AGGREGATE_INPUT rejects an aggregations[].field breakout; accepts a single field", () => {
+		expect(
+			AGGREGATE_INPUT.safeParse({
+				org: "o",
+				object: "Account",
+				aggregations: [{ function: "sum", field: "Amount } evil { value" }],
+			}).success,
+		).toBe(false);
+		expect(
+			AGGREGATE_INPUT.safeParse({
+				org: "o",
+				object: "Account",
+				aggregations: [{ function: "sum", field: "Amount" }],
+			}).success,
+		).toBe(true);
+	});
+
+	// PR #678 review (Ciaran Hannigan): Salesforce custom-field __c syntax must be
+	// accepted. The dotted-path / Name regexes permit it today; this pins it so a
+	// future "no consecutive underscores" tweak can't silently start rejecting real
+	// fields across any caller-supplied field-path input.
+	it("accepts Salesforce custom/namespaced __c field syntax across every dotted-path input", () => {
+		const returnFields = ["Amount__c", "Owner.Custom__c", "MyNS__Field__c"];
+		expect(CREATE_INPUT.safeParse({ org: "o", object: "Account", returnFields }).success).toBe(
+			true,
+		);
+		expect(UPDATE_INPUT.safeParse({ org: "o", object: "Account", returnFields }).success).toBe(
+			true,
+		);
+		expect(
+			LIST_INPUT.safeParse({
+				org: "o",
+				object: "Account",
+				fields: ["Amount__c"],
+				parentFields: ["Owner.Custom__c"],
+				childRelationships: [{ relationshipName: "Contacts", fields: ["MyNS__Field__c"] }],
+			}).success,
+		).toBe(true);
+		expect(
+			DETAIL_INPUT.safeParse({
+				org: "o",
+				object: "Account",
+				fields: ["Amount__c"],
+				parentFields: ["Owner.Custom__c"],
+			}).success,
+		).toBe(true);
+		expect(
+			AGGREGATE_INPUT.safeParse({
+				org: "o",
+				object: "Account",
+				aggregations: [{ function: "sum", field: "Amount__c" }],
+				groupBy: ["MyNS__Field__c"],
+			}).success,
+		).toBe(true);
+	});
+});

package/src/schemas/fields.ts

@@ -5,7 +5,7 @@
  */
 
 import { z } from "zod";
-import { GRAPHQL_NAME_RE } from "../lib/graphql-name.js";
+import { DOTTED_GRAPHQL_NAME_RE, GRAPHQL_NAME_RE } from "../lib/graphql-name.js";
 
 /**
  * Some MCP clients/models JSON-stringify complex tool arguments (e.g. send
@@ -59,6 +59,29 @@ export const quotedString = () => z.string().regex(/^".*"$/s);
 export const graphqlName = (description: string): z.ZodString =>
 	z.string().regex(GRAPHQL_NAME_RE, "must be a valid GraphQL Name").describe(description);
 
+/**
+ * Zod validator for a dotted field path (`Id`, `Owner.Name`, …). Each
+ * `.`-separated segment must be a valid GraphQL Name. Applied to every
+ * caller-supplied field-selection input (`returnFields`, `fields`,
+ * `parentFields`, child-relationship `fields`) so a selection-set breakout is
+ * rejected at the MCP boundary (W-22735537); the builders carry the matching
+ * `assertDottedGraphqlName` guard for direct (CLI / eval) callers.
+ */
+export const dottedGraphqlName = (description: string): z.ZodString =>
+	z
+		.string()
+		.regex(DOTTED_GRAPHQL_NAME_RE, "must be a valid field path (dot-separated GraphQL Names)")
+		.describe(description);
+
+/**
+ * `scope` argument validator: a bare enum token (e.g. `MINE`, `EVERYTHING`) or a
+ * `$varName` placeholder. `scope` renders into an argument position, so an
+ * unconstrained string is a selection-set / argument breakout (W-22735537).
+ */
+const SCOPE_RE = /^\$?[A-Za-z_][A-Za-z0-9_]*$/;
+export const scopeArg = (description: string): z.ZodString =>
+	z.string().regex(SCOPE_RE, "must be a Scope enum token or $varName").describe(description);
+
 /**
  * Org alias / username charset + length, matching `auth.ts`'s
  * `assertValidOrgAlias`. Defense-in-depth at the MCP boundary so the
@@ -101,7 +124,11 @@ export const childRelationshipSchema = (orderBy: z.ZodTypeAny) =>
 		relationshipName: graphqlName(
 			'Child relationship API name, e.g. "Contacts", "Opportunities". Must be a valid GraphQL Name.',
 		),
-		fields: z.array(z.string()),
+		fields: z.array(
+			dottedGraphqlName(
+				'Scalar field API names on the child record; dot-paths like "Owner.Name" allowed.',
+			),
+		),
 		first: jsonCoercible(
 			z.union([z.number().int().positive(), varPlaceholder(), intLiteralString(), quotedString()]),
 		).optional(),

package/src/schemas/input-schemas.ts

@@ -19,6 +19,7 @@
 import { z } from "zod";
 import {
 	childRelationshipSchema,
+	dottedGraphqlName,
 	graphqlName,
 	intLiteralString,
 	jsonCoercible,
@@ -26,6 +27,7 @@ import {
 	orderByObject,
 	orgAlias,
 	quotedString,
+	scopeArg,
 	varPlaceholder,
 } from "./fields.js";
 import { GROUP_BY_FUNCTIONS } from "../intent/types.js";
@@ -48,12 +50,12 @@ export const LIST_INPUT = z.object({
 	org: z.string().describe("Org alias resolved via local Salesforce CLI auth (~/.sf, ~/.sfdx)."),
 	object: graphqlName('SObject API name, e.g. "Account", "Case". Must be a valid GraphQL Name.'),
 	fields: z
-		.array(z.string())
+		.array(dottedGraphqlName('Scalar field API name; dot-paths like "Owner.Name" allowed.'))
 		.describe(
 			'Scalar field API names to select on the node. Dot-paths like "Owner.Name" are allowed.',
 		),
 	parentFields: z
-		.array(z.string())
+		.array(dottedGraphqlName('Dotted parent-relationship path, e.g. "Account.Name".'))
 		.optional()
 		.describe('Dotted parent-relationship paths, e.g. "Account.Name".'),
 	childRelationships: z.array(childRelationshipSchema(listOrderBySchema())).optional(),
@@ -76,7 +78,7 @@ export const LIST_INPUT = z.object({
 		.describe(
 			'Top-level connection page size as a NUMBER (e.g. 25, not "25"); defaults to 10. Pass a single "$varName" string to promote it to an optional Int variable.',
 		),
-	scope: z.string().optional().describe('Scope enum (e.g. "MINE", "EVERYTHING") or $varName.'),
+	scope: scopeArg('Scope enum (e.g. "MINE", "EVERYTHING") or $varName.').optional(),
 	operationName: graphqlName(
 		"Override the GraphQL operation name. Defaults to <Object>List.",
 	).optional(),
@@ -104,12 +106,12 @@ export const DETAIL_INPUT = z
 		org: orgAlias("Org alias resolved via local Salesforce CLI auth (~/.sf, ~/.sfdx)."),
 		object: graphqlName('SObject API name, e.g. "Account", "Case". Must be a valid GraphQL Name.'),
 		fields: z
-			.array(z.string())
+			.array(dottedGraphqlName('Scalar field API name; dot-paths like "Owner.Name" allowed.'))
 			.describe(
 				'Scalar field API names to select on the node. Dot-paths like "Owner.Name" are allowed.',
 			),
 		parentFields: z
-			.array(z.string())
+			.array(dottedGraphqlName('Dotted parent-relationship path, e.g. "Account.Name".'))
 			.optional()
 			.describe('Dotted parent-relationship paths, e.g. "Account.Name".'),
 		childRelationships: z.array(childRelationshipSchema(detailOrderBySchema())).optional(),
@@ -170,20 +172,20 @@ const aliasField = z
 const aggregationSchema = z.discriminatedUnion("function", [
 	z.object({
 		function: z.enum(["count", "countDistinct"]),
-		field: z.string().optional().describe('SObject field API name. Defaults to "Id" when omitted.'),
+		field: graphqlName('SObject field API name. Defaults to "Id" when omitted.').optional(),
 		alias: aliasField,
 	}),
 	z.object({
 		function: z.enum(["sum", "avg", "min", "max"]),
-		field: z.string().describe("SObject field API name. Required for sum/avg/min/max."),
+		field: graphqlName("SObject field API name. Required for sum/avg/min/max."),
 		alias: aliasField,
 	}),
 ]);
 
 const groupByElementSchema = z.union([
-	z.string(),
+	graphqlName("SObject field API name to group by (flat, non-dotted)."),
 	z.object({
-		field: z.string().describe("SObject field API name (DateTime/Date field)."),
+		field: graphqlName("SObject field API name (DateTime/Date field)."),
 		function: z
 			.enum(GROUP_BY_FUNCTIONS)
 			.describe("Date bucketing function from UIAPI GroupByFunction enum."),
@@ -269,10 +271,10 @@ export const CREATE_INPUT = z.object({
 	org: z.string().describe("Org alias resolved via local Salesforce CLI auth (~/.sf, ~/.sfdx)."),
 	object: graphqlName('SObject API name, e.g. "Account", "Order". Must be a valid GraphQL Name.'),
 	returnFields: z
-		.array(z.string())
+		.array(dottedGraphqlName("Scalar field API name to read back on the created Record."))
 		.optional()
 		.describe(
-			'Scalar field API names to read back on the created Record. Defaults to ["Id"]. Dot-paths like Owner.Name are not supported in mutation results; passing them produces a warning and the field is skipped.',
+			'Scalar field API names to read back on the created Record. Defaults to ["Id"]. Each entry must be a valid field name (dot-paths allowed); invalid entries are rejected. Dot-paths like Owner.Name are unsupported in mutation results and are skipped with a warning.',
 		),
 	inputVariable: z
 		.string()
@@ -291,10 +293,10 @@ export const UPDATE_INPUT = z.object({
 	org: z.string().describe("Org alias resolved via local Salesforce CLI auth (~/.sf, ~/.sfdx)."),
 	object: graphqlName('SObject API name, e.g. "Account", "Order". Must be a valid GraphQL Name.'),
 	returnFields: z
-		.array(z.string())
+		.array(dottedGraphqlName("Scalar field API name to read back on the updated Record."))
 		.optional()
 		.describe(
-			'Scalar field API names to read back on the updated Record. Defaults to ["Id"]. Dot-paths like Owner.Name are not supported in mutation results; passing them produces a warning and the field is skipped.',
+			'Scalar field API names to read back on the updated Record. Defaults to ["Id"]. Each entry must be a valid field name (dot-paths allowed); invalid entries are rejected. Dot-paths like Owner.Name are unsupported in mutation results and are skipped with a warning.',
 		),
 	inputVariable: z
 		.string()