Merge pull request #505 from neo4j/504-flag-to-disable-esaping-labels-and-types

504 flag to disable escaping labels and types

Author: angrykoala

.changeset/shiny-badgers-reply.md

@@ -0,0 +1,49 @@
+---
+"@neo4j/cypher-builder": patch
+---
+
+New options to disable automatic escaping of labels and relationship types have been added to the `.build` method on clauses, inside the new object `unsafeEscapeOptions`:
+
+- `disableLabelEscaping` (defaults to `false`): If set to true, node labels will not be escaped if unsafe.
+- `disableRelationshipTypeEscaping` (defaults to `false`): If set to true, relationship types will not be escaped if unsafe
+
+For example:
+
+```js
+const personNode = new Cypher.Node();
+const movieNode = new Cypher.Node();
+
+const matchQuery = new Cypher.Match(
+    new Cypher.Pattern(personNode, {
+        labels: ["Person"],
+        properties: {
+            ["person name"]: new Cypher.Literal(`Uneak "Seveer`),
+        },
+    })
+        .related({ type: "ACTED IN" })
+        .to(movieNode, { labels: ["A Movie"] })
+).return(personNode);
+
+const queryResult = matchQuery.build({
+    unsafeEscapeOptions: {
+        disableLabelEscaping: true,
+        disableRelationshipTypeEscaping: true,
+    },
+});
+```
+
+This query will generate the following (invalid) Cypher:
+
+```
+MATCH (this0:Person { `person name`: "Uneak \"Seveer" })-[:ACTED IN]->(this1:A Movie)
+RETURN this0
+```
+
+Instead of the default (safe) Cypher:
+
+```cypher
+MATCH (this0:Person { `person name`: "Uneak \"Seveer" })-[:`ACTED IN`]->(this1:`A Movie`)
+RETURN this0
+```
+
+**WARNING:**: Changing these options may lead to code injection and unsafe Cypher.

docs/modules/ROOT/pages/how-to/customize-cypher.adoc

@@ -346,3 +346,92 @@ And the following parameters:
 The callback passed into `Raw` is producing the string `this0.prop = $myParam`. 
 To achieve this, it uses the utility method `utils.compileCypher` and passes the variable `movie` and the `context` parameter, which then returns the string `this0`. 
 Finally, the custom parameter `$myParam` is returned in the tuple `[cypher, params]`, ensuring that it is available when executing `match.build()`.
+
+
+== Disable automatic escaping
+
+[WARNING]
+====
+Changing these options may lead to code injection and unsafe Cypher.
+====
+
+Cypher Builder automatically escapes unsafe strings that could lead to code injection. This behavior can be configured using the `unsafeEscapeOptions` parameter in the `.build` method of clauses:
+
+- `disableLabelEscaping` (defaults to `false`): If set to `true`, node labels will not be escaped, even if unsafe.
+- `disableRelationshipTypeEscaping` (defaults to `false`): If set to `true`, relationship types will not be escaped, even if unsafe.
+
+For example:
+
+[source, javascript]
+----
+const personNode = new Cypher.Node();
+const movieNode = new Cypher.Node();
+
+const matchQuery = new Cypher.Match(
+    new Cypher.Pattern(personNode, {
+        labels: ["Person"],
+        properties: {
+            ["person name"]: new Cypher.Literal(`Uneak "Seveer`),
+        },
+    })
+        .related({ type: "ACTED IN" })
+        .to(movieNode, { labels: ["A Movie"] })
+).return(personNode);
+
+const queryResult = matchQuery.build({
+    unsafeEscapeOptions: {
+        disableLabelEscaping: true,
+        disableRelationshipTypeEscaping: true,
+    },
+});
+----
+
+This query will generate the following (invalid) Cypher:
+
+
+[source]
+----
+MATCH (this0:Person { `person name`: "Uneak \"Seveer" })-[:ACTED IN]->(this1:A Movie)
+RETURN this0
+----
+
+Instead of the default (safe) Cypher:
+
+[source, cypher]
+----
+MATCH (this0:Person { `person name`: "Uneak \"Seveer" })-[:`ACTED IN`]->(this1:`A Movie`)
+RETURN this0
+----
+
+=== Manually escaping labels and types
+
+If automatic escaping is disabled, strings used for labels and relationship types must be escaped manually. This can be done using the following utility functions:
+
+* `Cypher.utils.escapeLabel(str)`
+* `Cypher.utils.escapeType(str)`
+
+In the previous example, labels and types can be escaped manually to produce valid Cypher:
+
+[source, javascript]
+----
+const personNode = new Cypher.Node();
+const movieNode = new Cypher.Node();
+
+const matchQuery = new Cypher.Match(
+    new Cypher.Pattern(personNode, {
+        labels: [Cypher.utils.escapeLabel("Person")],
+        properties: {
+            ["person name"]: new Cypher.Literal(`Uneak "Seveer`),
+        },
+    })
+        .related({ type: Cypher.utils.escapeType("ACTED IN") })
+        .to(movieNode, { labels: [Cypher.utils.escapeLabel("A Movie")] })
+).return(personNode);
+
+const queryResult = matchQuery.build({
+    unsafeEscapeOptions: {
+        disableLabelEscaping: true,
+        disableRelationshipTypeEscaping: true,
+    },
+});
+----

src/Environment.ts

@@ -17,6 +17,7 @@
  * limitations under the License.
  */
 
+import type { BuildConfig } from "./Cypher";
 import { Param } from "./references/Param";
 import type { NamedReference, Variable } from "./references/Variable";
 
@@ -26,12 +27,15 @@ export type EnvPrefix = {
 };
 
 export type EnvConfig = {
-    labelOperator: ":" | "&";
-    cypherVersion?: "5";
+    labelOperator: NonNullable<BuildConfig["labelOperator"]>;
+    unsafeEscapeOptions: NonNullable<BuildConfig["unsafeEscapeOptions"]>;
+    cypherVersion: BuildConfig["cypherVersion"];
 };
 
 const defaultConfig: EnvConfig = {
     labelOperator: ":",
+    unsafeEscapeOptions: {},
+    cypherVersion: undefined,
 };
 
 /** Hold the internal references of Cypher parameters and variables

src/clauses/Clause.ts

@@ -28,10 +28,48 @@ const customInspectSymbol = Symbol.for("nodejs.util.inspect.custom");
 
 /** Config fields for the .build method */
 export type BuildConfig = Partial<{
+    /** Defines the default operator for adding multiple labels in a Pattern. Defaults to `":"`
+     *
+     * If the target Cypher is version 5 or above, `"&"` is recommended
+     *
+     * @example
+     * `MATCH (this:Movie:Film)`
+     * `MATCH (this:Movie&Film)`
+     *
+     */
     labelOperator: ":" | "&";
+    /** Will prefix generated queries with the Cypher version
+     * @example `CYPHER 5` */
     cypherVersion: "5";
+    /** Prefix variables with given string.
+     *
+     * This is useful to avoid name collisions if separate Cypher queries are generated and merged after generating the strings.
+     * @example `myPrefix_this0`
+     *
+     */
     prefix: string;
+    /** Extra parameters to be added to the result of `.build`. */
     extraParams: Record<string, unknown>;
+    /** Options for disabling automatic escaping of potentially unsafe strings.
+     *
+     * **WARNING**: Changing these options may lead to code injection and unsafe Cypher.
+     */
+    unsafeEscapeOptions: Partial<{
+        /** Disables automatic escaping of node labels.
+         *
+         * If disabled, any labels passed should be properly escaped with `utils.escapeLabel`.
+         *
+         * **WARNING**: Disabling label escaping may lead to code injection and unsafe Cypher.
+         */
+        disableLabelEscaping: boolean;
+        /** Disables automatic escaping of relationship types.
+         *
+         * If disabled, any types passed should be properly escaped with `utils.escapeType`.
+         *
+         * **WARNING**: Disabling type escaping may lead to code injection and unsafe Cypher.
+         */
+        disableRelationshipTypeEscaping: boolean;
+    }>;
 }>;
 
 /** Represents a clause AST node
@@ -41,11 +79,18 @@ export abstract class Clause extends CypherASTNode {
     protected nextClause: Clause | undefined;
 
     /** Compiles a clause into Cypher and params */
-    public build({ prefix, extraParams = {}, labelOperator = ":", cypherVersion }: BuildConfig = {}): CypherResult {
+    public build({
+        prefix,
+        extraParams = {},
+        labelOperator = ":",
+        cypherVersion,
+        unsafeEscapeOptions = {},
+    }: BuildConfig = {}): CypherResult {
         if (this.isRoot) {
             const env = this.getEnv(prefix, {
                 labelOperator,
                 cypherVersion,
+                unsafeEscapeOptions,
             });
             const cypher = this.getCypher(env);
 
@@ -58,7 +103,7 @@ export abstract class Clause extends CypherASTNode {
         }
         const root = this.getRoot();
         if (root instanceof Clause) {
-            return root.build({ prefix, extraParams, labelOperator, cypherVersion });
+            return root.build({ prefix, extraParams, labelOperator, cypherVersion, unsafeEscapeOptions });
         }
         throw new Error(`Cannot build root: ${root.constructor.name}`);
     }

src/pattern/PartialPattern.ts

@@ -26,7 +26,7 @@ import type { Expr } from "../types";
 import { compileCypherIfExists } from "../utils/compile-cypher-if-exists";
 import { NestedPattern, type NodePattern, type Pattern, type RelationshipPattern } from "./Pattern";
 import { PatternElement } from "./PatternElement";
-import { labelsToString } from "./labels-to-string";
+import { typeToString } from "./labels-to-string";
 
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface PartialPattern extends WithWhere {}
@@ -99,7 +99,7 @@ export class PartialPattern extends PatternElement {
 
     private getTypeStr(env: CypherEnvironment): string {
         if (this.type) {
-            return labelsToString(this.type, env);
+            return typeToString(this.type, env);
         }
         return "";
     }

src/pattern/Pattern.test.ts

@@ -517,4 +517,16 @@ describe("Patterns", () => {
 
         expect(queryResult.params).toMatchInlineSnapshot(`{}`);
     });
+
+    test("Pattern with empty strings as labels and types", () => {
+        const a = new Cypher.Node();
+        const b = new Cypher.Node();
+        const rel = new Cypher.Relationship();
+
+        const query = new TestClause(new Cypher.Pattern(a, { labels: [""] }).related(rel, { type: "" }).to(b));
+        const queryResult = query.build();
+        expect(queryResult.cypher).toMatchInlineSnapshot(`"(this0)-[this1]->(this2)"`);
+
+        expect(queryResult.params).toMatchInlineSnapshot(`{}`);
+    });
 });

src/pattern/labels-to-string.ts

@@ -21,20 +21,26 @@ import type { CypherEnvironment } from "../Environment";
 import { LabelExpr } from "../expressions/labels/label-expressions";
 import { addLabelToken } from "../utils/add-label-token";
 import { asArray } from "../utils/as-array";
-import { escapeLabel } from "../utils/escape";
+import { escapeLabel, escapeType } from "../utils/escape";
 
 export function labelsToString(labels: string | string[] | LabelExpr, env: CypherEnvironment): string {
     if (labels instanceof LabelExpr) {
-        const labelsStr = labels.getCypher(env);
-        if (!labelsStr) {
-            return "";
-        }
         return addLabelToken(env.config.labelOperator, labels.getCypher(env));
     } else {
-        const escapedLabels = asArray(labels).map(escapeLabel);
-        if (escapedLabels.length === 0) {
-            return "";
-        }
+        const shouldEscape = !env.config.unsafeEscapeOptions.disableLabelEscaping;
+        const escapedLabels = shouldEscape ? asArray(labels).map(escapeLabel) : asArray(labels);
+
         return addLabelToken(env.config.labelOperator, ...escapedLabels);
     }
 }
+
+export function typeToString(type: string | LabelExpr, env: CypherEnvironment): string {
+    if (type instanceof LabelExpr) {
+        return addLabelToken(env.config.labelOperator, type.getCypher(env));
+    } else {
+        const shouldEscape = !env.config.unsafeEscapeOptions.disableRelationshipTypeEscaping;
+        const escapedType = shouldEscape ? escapeType(type) : type;
+
+        return addLabelToken(env.config.labelOperator, escapedType);
+    }
+}

src/references/Variable.ts

@@ -17,11 +17,11 @@
  * limitations under the License.
  */
 
-import { PropertyRef } from "./PropertyRef";
+import type { CypherEnvironment } from "../Environment";
 import { ListIndex } from "../expressions/list/ListIndex";
 import type { Expr } from "../types";
-import type { CypherEnvironment } from "../Environment";
 import { escapeVariable } from "../utils/escape";
+import { PropertyRef } from "./PropertyRef";
 
 /** Represents a variable
  * @group Variables

src/utils/stringify-object.test.ts

@@ -39,4 +39,13 @@ describe("stringifyObject", () => {
 
         expect(result).toBe(`{ nobody: expects }`);
     });
+
+    test("escape keys", () => {
+        const result = stringifyObject({
+            ["this name"]: "this",
+            that: `"that"`,
+        });
+
+        expect(result).toBe(`{ \`this name\`: this, that: "that" }`);
+    });
 });