fix(query): reject reserved encoded-query characters in condition values

Condition values were written into the encoded query verbatim, so a value
containing ^, ,, or @ could break out of its term and append arbitrary
clauses to sysparm_query (encoded-query injection).

ServiceNow encoded queries provide no escape sequence for these structural
characters, so values are now validated at construction time: a rejected
value yields an error Condition that surfaces through the existing
Error() channel and propagates via And()/Or(). Internally composed date
literals (OnSpecialty, JS, NewDateTimeValue) keep their intentional @ /
javascript: separators and bypass validation.

Fixes #645

Author: -g

query/base_field.go

@@ -20,15 +20,32 @@ func (f BaseField) buildBinary(op ast.Operator, right ast.Node) Condition {
 }
 
 func (f BaseField) binary(op ast.Operator, val interface{}) Condition {
+	if err := validateQueryValue(f.name, op, val); err != nil {
+		return NewErrorCondition(err)
+	}
 	return f.buildBinary(op, ast.NewLiteralNode(val))
 }
 
 func (f BaseField) pair(op ast.Operator, left, right interface{}) Condition {
+	if err := validateQueryValue(f.name, op, left); err != nil {
+		return NewErrorCondition(err)
+	}
+	if err := validateQueryValue(f.name, op, right); err != nil {
+		return NewErrorCondition(err)
+	}
 	return f.buildBinary(op, ast.NewPairNode(ast.NewLiteralNode(left), ast.NewLiteralNode(right)))
 }
 
-func (f BaseField) multi(op ast.Operator, nodes *ast.ArrayNode) Condition {
-	return f.buildBinary(op, nodes)
+// multi builds a condition over multiple primitive values (e.g., IN / NOT IN),
+// validating each value before building the array node. It is a package-level
+// function because Go methods cannot declare type parameters.
+func multi[T ast.Primitive](f BaseField, op ast.Operator, values ...T) Condition {
+	for _, value := range values {
+		if err := validateQueryValue(f.name, op, value); err != nil {
+			return NewErrorCondition(err)
+		}
+	}
+	return f.buildBinary(op, convertSliceToArrayNode(values...))
 }
 
 // IsAnything query that field is anything.

query/date_time_field.go

@@ -13,18 +13,26 @@ type DateTimeField struct {
 }
 
 func (f DateTimeField) dateTimeBinary(op ast.Operator, val any) Condition {
-	var literal string
 	switch v := val.(type) {
 	case DateTimeValue:
-		literal = v.String()
+		// Trusted composite built by this package (NewDateTimeValue, Time, JS,
+		// OnSpecialty): its "@" and "javascript:" separators are intentional
+		// encoded-query syntax, so it bypasses value validation.
+		return f.buildBinary(op, ast.NewLiteralNode(v.String()))
 	case time.Time:
-		literal = v.Format("2006-01-02 15:04:05")
+		return f.buildBinary(op, ast.NewLiteralNode(v.Format("2006-01-02 15:04:05")))
 	case string:
-		literal = v
+		if err := validateQueryValue(f.name, op, v); err != nil {
+			return NewErrorCondition(err)
+		}
+		return f.buildBinary(op, ast.NewLiteralNode(v))
 	default:
-		literal = fmt.Sprintf("%v", v)
+		literal := fmt.Sprintf("%v", v)
+		if err := validateQueryValue(f.name, op, literal); err != nil {
+			return NewErrorCondition(err)
+		}
+		return f.buildBinary(op, ast.NewLiteralNode(literal))
 	}
-	return f.binary(op, literal)
 }
 
 // On query the date-time field is on a specific date-time.

query/number_field.go

@@ -51,12 +51,12 @@ func (f NumberField) Between(lower, upper float64) Condition {
 
 // IsOneOf query that field is one of the provided values.
 func (f NumberField) IsOneOf(values ...float64) Condition {
-	return f.multi(ast.OperatorIsOneOf, convertSliceToArrayNode(values...))
+	return multi(f.BaseField, ast.OperatorIsOneOf, values...)
 }
 
 // IsNotOneOf query that field is not one of the provided values.
 func (f NumberField) IsNotOneOf(values ...float64) Condition {
-	return f.multi(ast.OperatorIsNotOneOf, convertSliceToArrayNode(values...))
+	return multi(f.BaseField, ast.OperatorIsNotOneOf, values...)
 }
 
 // GreaterThanField query that field is greater than the provided field.

query/query.go

@@ -1,5 +1,10 @@
 // Package query provides a type-safe and fluent API for building ServiceNow encoded queries.
 // It is a redesign of the query package, focusing on usability and immutability.
+//
+// Condition values are validated at construction time: a value containing one
+// of the reserved encoded-query characters ("^", ",", "@") yields an error
+// Condition whose Error() is non-nil, because ServiceNow encoded queries offer
+// no way to escape those characters inside a value.
 package query
 
 // Where starts a new query on the specified field as a string field.

query/string_field.go

@@ -41,12 +41,12 @@ func (f StringField) DoesNotContain(val string) Condition {
 
 // IsOneOf query that field is one of the provided values.
 func (f StringField) IsOneOf(values ...string) Condition {
-	return f.multi(ast.OperatorIsOneOf, convertSliceToArrayNode(values...))
+	return multi(f.BaseField, ast.OperatorIsOneOf, values...)
 }
 
 // IsNotOneOf query that field is not one of the provided values.
 func (f StringField) IsNotOneOf(values ...string) Condition {
-	return f.multi(ast.OperatorIsNotOneOf, convertSliceToArrayNode(values...))
+	return multi(f.BaseField, ast.OperatorIsNotOneOf, values...)
 }
 
 // IsEmptyString query that string field is empty.

query/validation.go

@@ -0,0 +1,37 @@
+package query
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/michaeldcanady/servicenow-sdk-go/v2/internal/ast"
+)
+
+// reservedQueryCharacters lists the ServiceNow encoded-query metacharacters that
+// cannot appear inside a condition value: "^" separates clauses ("^" / "^OR"),
+// "," separates values in a list, and "@" separates the halves of a pair.
+// Encoded queries provide no escape sequence for them, so a value containing
+// any of these characters would break out of its term and append arbitrary
+// clauses to the query.
+const reservedQueryCharacters = "^,@" //nolint:gochecknoglobals
+
+// validateQueryValue checks that a consumer-supplied value contains no reserved
+// encoded-query characters. It returns nil for safe values and a descriptive
+// error otherwise; callers turn that error into an error Condition via
+// NewErrorCondition so it surfaces through Condition.Error().
+//
+// Literals composed internally by this package (for example the
+// "label@javascript:expr@javascript:expr" strings built by OnSpecialty) are
+// trusted and must bypass this check.
+func validateQueryValue(field string, op ast.Operator, val any) error {
+	rendered := fmt.Sprintf("%v", val)
+	index := strings.IndexAny(rendered, reservedQueryCharacters)
+	if index < 0 {
+		return nil
+	}
+
+	return fmt.Errorf(
+		"value %q for field %q (operator %q) contains reserved encoded-query character %q; ^, ,, and @ structure the query itself and cannot be escaped",
+		rendered, field, op.String(), rendered[index],
+	)
+}