Add helpers to prevent SQL injection for trigger when clauses.

Author: stevensJourney

packages/common/src/client/triggers/TriggerManager.ts

@@ -140,11 +140,16 @@ interface BaseCreateDiffTriggerOptions {
    * For example, you can use it to only trigger on certain values in the NEW row.
    * Note that for PowerSync the row data is stored in a JSON column named `data`.
    * The row id is available in the `id` column.
+   *
+   * NB! The WHEN clauses here added added directly to the SQLite trigger creation SQL.
+   * Any user input strings here should be sanitized externally. The {@link when} string template function performs
+   * some basic sanitization, extra external sanitization is recommended.
+   *
    * @example
    * {
-   *  'INSERT': `json_extract(NEW.data, '$.list_id') = 'abcd'`
-   *  'UPDATE': `NEW.id = 'abcd' AND json_extract(NEW.data, '$.status') = 'active'`
-   *  'DELETE': `json_extract(OLD.data, '$.list_id') = 'abcd'`
+   *  'INSERT': whenClause`json_extract(NEW.data, '$.list_id') = ${sanitizeUUID(list.id)}`
+   *  'UPDATE': whenClause`NEW.id = 'abcd' AND json_extract(NEW.data, '$.status') = 'active'`
+   *  'DELETE': whenClause`json_extract(OLD.data, '$.list_id') = 'abcd'`
    * }
    */
   when?: Partial<Record<DiffTriggerOperation, string>>;
@@ -310,7 +315,7 @@ export interface TriggerManager {
    *        source: 'todos',
    *        columns: ['list_id'],
    *        when: {
-   *          [DiffTriggerOperation.INSERT]: "json_extract(NEW.data, '$.list_id') = '123'"
+   *          [DiffTriggerOperation.INSERT]: whenClause`json_extract(NEW.data, '$.list_id') = '123'`
    *        },
    *        operations: [DiffTriggerOperation.INSERT],
    *        onChange: async (context) => {

packages/common/src/client/triggers/whenClause.ts

@@ -0,0 +1,66 @@
+function sanitizeString(input: string): string {
+  return `'${input.replace(/'/g, "''")}'`;
+}
+/**
+ * Helper function for sanitizing UUID input strings.
+ * Typically used with {@link whenClause}.
+ */
+export function sanitizeUUID(uuid: string): string {
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  const isValid = uuidRegex.test(uuid);
+  if (!isValid) {
+    throw new Error(`${uuid} is not a valid UUID`);
+  }
+  return uuid;
+}
+
+/**
+ * SQL string template function for {@link TrackDiffOptions#when} and {@link CreateDiffTriggerOptions#when}.
+ *
+ * This function performs basic string interpolation for SQLite WHEN clauses.
+ *
+ * **String placeholders:**
+ * - All string values passed as placeholders are automatically wrapped in single quotes (`'`).
+ * - Any single quotes within the string value are escaped by doubling them (`''`), as required by SQL syntax.
+ * - Do not manually wrap placeholders in single quotes in your template string; the function will handle quoting and escaping for you.
+ *
+ * **Other types:**
+ * - `null` and `undefined` are converted to SQL `NULL`.
+ * - Objects are stringified using `JSON.stringify()` and wrapped in single quotes, with any single quotes inside the stringified value escaped.
+ * - Numbers and other primitive types are inserted directly.
+ *
+ * **Usage example:**
+ * ```typescript
+ * const myID = "O'Reilly";
+ * const clause = whenClause`New.id = ${myID}`;
+ * // Result: "New.id = 'O''Reilly'"
+ * ```
+ *
+ * Avoid manually quoting placeholders:
+ * ```typescript
+ * // Incorrect:
+ * whenClause`New.id = '${myID}'` // Produces double quotes: New.id = ''O''Reilly''
+ * ```
+ */
+export function whenClause(strings: TemplateStringsArray, ...values: any[]): string {
+  let result = '';
+  strings.forEach((str, i) => {
+    result += str;
+    if (i < values.length) {
+      // For SQL, escape single quotes in string values
+      const value = values[i];
+      if (typeof value === 'string') {
+        result += sanitizeString(value);
+      } else if (value === null || value === undefined) {
+        result += 'NULL';
+      } else if (typeof value == 'object') {
+        // Stringify the object and escape single quotes in the result
+        const stringified = JSON.stringify(value);
+        result += sanitizeString(stringified);
+      } else {
+        result += value;
+      }
+    }
+  });
+  return result;
+}

packages/common/src/index.ts

@@ -32,6 +32,7 @@ export * from './db/schema/Table.js';
 export * from './db/schema/TableV2.js';
 
 export * from './client/triggers/TriggerManager.js';
+export * from './client/triggers/whenClause.js';
 
 export * from './utils/AbortOperation.js';
 export * from './utils/BaseObserver.js';

packages/node/tests/trigger.test.ts

@@ -1,5 +1,10 @@
-import { DiffTriggerOperation, ExtractedTriggerDiffRecord, TriggerDiffRecord } from '@powersync/common';
-// import 'source-map-support/register';
+import {
+  DiffTriggerOperation,
+  ExtractedTriggerDiffRecord,
+  sanitizeUUID,
+  TriggerDiffRecord,
+  whenClause
+} from '@powersync/common';
 import { describe, expect, vi } from 'vitest';
 import { Database, databaseTest } from './utils';
 
@@ -111,7 +116,9 @@ describe('Triggers', () => {
     await database.triggers.trackTableDiff({
       source: 'todos',
       columns: ['list_id'],
-      when: { [DiffTriggerOperation.INSERT]: `json_extract(NEW.data, '$.list_id') = '${firstList.id}'` },
+      when: {
+        [DiffTriggerOperation.INSERT]: whenClause`json_extract(NEW.data, '$.list_id') = ${sanitizeUUID(firstList.id)}`
+      },
       operations: [DiffTriggerOperation.INSERT],
       onChange: async (context) => {
         // Fetches the current state of  todo records that were inserted during this diff window.
@@ -189,7 +196,7 @@ describe('Triggers', () => {
      */
     await database.triggers.trackTableDiff({
       source: 'lists',
-      when: { [DiffTriggerOperation.UPDATE]: `NEW.id = '${list.id}'` },
+      when: { [DiffTriggerOperation.UPDATE]: whenClause`NEW.id = ${sanitizeUUID(list.id)}` },
       operations: [DiffTriggerOperation.UPDATE, DiffTriggerOperation.DELETE],
       onChange: async (context) => {
         // Fetches the todo records that were inserted during this diff
@@ -298,7 +305,9 @@ describe('Triggers', () => {
     await database.triggers.trackTableDiff({
       source: 'todos',
       columns: ['list_id'],
-      when: { [DiffTriggerOperation.INSERT]: `json_extract(NEW.data, '$.list_id') = '${firstList.id}'` },
+      when: {
+        [DiffTriggerOperation.INSERT]: whenClause`json_extract(NEW.data, '$.list_id') = ${sanitizeUUID(firstList.id)}`
+      },
       operations: [DiffTriggerOperation.INSERT],
       onChange: async (context) => {
         // Fetches the todo records that were inserted during this diff
@@ -342,11 +351,11 @@ describe('Triggers', () => {
       async () => {
         expect(todos.length).toEqual(todoCreationCount);
       },
-      { timeout: 10000, interval: 1000 }
+      { timeout: 1000, interval: 100 }
     );
   });
 
-  databaseTest('Should extract diff values', { timeout: 10000 }, async ({ database }) => {
+  databaseTest('Should extract diff values', async ({ database }) => {
     await database.execute(
       /* sql */ `
         INSERT INTO
@@ -386,7 +395,9 @@ describe('Triggers', () => {
     // The onChange handler is guaranteed to see any change after the state above.
     await database.triggers.trackTableDiff({
       source: 'todos',
-      when: { [DiffTriggerOperation.INSERT]: `json_extract(NEW.data, '$.list_id') = '${firstList.id}'` },
+      when: {
+        [DiffTriggerOperation.INSERT]: whenClause`json_extract(NEW.data, '$.list_id') = ${sanitizeUUID(firstList.id)}`
+      },
       operations: [DiffTriggerOperation.INSERT],
       onChange: async (context) => {
         // Fetches the content of the records at the time of the operation
@@ -416,11 +427,11 @@ describe('Triggers', () => {
         expect(changes.map((c) => c.content)).toEqual(['todo 1', 'todo 2', 'todo 3']);
         expect(changes.every((c) => c.operation === DiffTriggerOperation.INSERT)).toBeTruthy();
       },
-      { timeout: 10000, interval: 1000 }
+      { timeout: 1000, interval: 100 }
     );
   });
 
-  databaseTest('Should allow tracking 0 columns', { timeout: 10000 }, async ({ database }) => {
+  databaseTest('Should allow tracking 0 columns', { timeout: 1000 }, async ({ database }) => {
     /**
      * Tracks the ids of todos reported via the trigger
      */
@@ -491,7 +502,7 @@ describe('Triggers', () => {
       async () => {
         expect(changes).toEqual(ids);
       },
-      { timeout: 10000, interval: 1000 }
+      { timeout: 1000, interval: 100 }
     );
   });
 });