@kysera/rls 0.8.4 → 0.8.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kysera/rls",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "Row-Level Security plugin for Kysely - declarative policies, query transformation, native RLS support",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,9 +21,9 @@
   ],
   "peerDependencies": {
     "kysely": ">=0.28.8",
-    "zod": ">=3.0.0",
-    "@kysera/repository": "0.8.4",
-    "@kysera/executor": "0.8.4"
+    "zod": "^4.3.6",
+    "@kysera/executor": "0.8.6",
+    "@kysera/repository": "0.8.6"
   },
   "peerDependenciesMeta": {
     "@kysera/executor": {
@@ -33,11 +33,11 @@
       "optional": true
     },
     "zod": {
-      "optional": false
+      "optional": true
     }
   },
   "dependencies": {
-    "@kysera/core": "0.8.4"
+    "@kysera/core": "0.8.6"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
@@ -51,9 +51,9 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16",
-    "zod": "^3.24.2",
-    "@kysera/repository": "0.8.4",
-    "@kysera/executor": "0.8.4"
+    "zod": "^4.3.6",
+    "@kysera/executor": "0.8.6",
+    "@kysera/repository": "0.8.6"
   },
   "keywords": [
     "kysely",

package/src/plugin.ts

@@ -429,7 +429,12 @@ export function rlsPlugin<DB>(options: RLSPluginOptions<DB>): Plugin {
         },
 
         /**
-         * Wrapped update with RLS check
+         * Wrapped update with RLS check.
+         *
+         * WARNING (TOCTOU): The existing row is fetched before the policy check.
+         * In concurrent environments, the row could be modified between fetch and
+         * check. For safety, call this method within a transaction. The underlying
+         * MutationGuard.checkUpdate documents this in detail.
          */
         async update(id: unknown, data: unknown): Promise<unknown> {
           if (!originalUpdate) {
@@ -499,7 +504,12 @@ export function rlsPlugin<DB>(options: RLSPluginOptions<DB>): Plugin {
         },
 
         /**
-         * Wrapped delete with RLS check
+         * Wrapped delete with RLS check.
+         *
+         * WARNING (TOCTOU): The existing row is fetched before the policy check.
+         * In concurrent environments, the row could be modified between fetch and
+         * check. For safety, call this method within a transaction. The underlying
+         * MutationGuard.checkDelete documents this in detail.
          */
         async delete(id: unknown): Promise<unknown> {
           if (!originalDelete) {

package/src/transformer/mutation.ts

@@ -39,18 +39,35 @@ export class MutationGuard<DB = unknown> {
   }
 
   /**
-   * Check if UPDATE operation is allowed
+   * Check if an UPDATE operation is allowed by RLS policies.
    *
-   * @param table - Table name
-   * @param existingRow - Current row data
-   * @param data - Data being updated
-   * @throws RLSPolicyViolation if access is denied
+   * IMPORTANT: To prevent TOCTOU race conditions, always call this method
+   * within the same transaction as the actual update operation. The existingRow
+   * should be fetched with SELECT FOR UPDATE within the transaction.
+   *
+   * Without proper transaction isolation, the existingRow could be modified by
+   * a concurrent operation between the time it was fetched and the time this
+   * check runs, leading to policy decisions based on stale data.
+   *
+   * @param table - Target table name
+   * @param existingRow - Current row data (should be fetched within same transaction)
+   * @param data - New data being applied
+   * @throws RLSPolicyViolation if the operation is not allowed
    *
    * @example
    * ```typescript
-   * const guard = new MutationGuard(registry);
-   * const existingPost = await db.selectFrom('posts').where('id', '=', 1).selectAll().executeTakeFirst();
-   * await guard.checkUpdate('posts', existingPost, { title: 'Updated' });
+   * // RECOMMENDED: Use within a transaction with row locking
+   * await db.transaction().execute(async (trx) => {
+   *   const existingPost = await trx
+   *     .selectFrom('posts')
+   *     .where('id', '=', 1)
+   *     .forUpdate()
+   *     .selectAll()
+   *     .executeTakeFirst();
+   *
+   *   await guard.checkUpdate('posts', existingPost, { title: 'Updated' });
+   *   await trx.updateTable('posts').set({ title: 'Updated' }).where('id', '=', 1).execute();
+   * });
    * ```
    */
   async checkUpdate(
@@ -62,17 +79,35 @@ export class MutationGuard<DB = unknown> {
   }
 
   /**
-   * Check if DELETE operation is allowed
+   * Check if a DELETE operation is allowed by RLS policies.
    *
-   * @param table - Table name
-   * @param existingRow - Row to be deleted
-   * @throws RLSPolicyViolation if access is denied
+   * IMPORTANT: To prevent TOCTOU race conditions, always call this method
+   * within the same transaction as the actual delete operation. The existingRow
+   * should be fetched with SELECT FOR UPDATE within the transaction.
+   *
+   * Without proper transaction isolation, the existingRow could be modified by
+   * a concurrent operation between the time it was fetched and the time this
+   * check runs, leading to policy decisions based on stale data (e.g., a row's
+   * ownership could change, allowing an unauthorized delete).
+   *
+   * @param table - Target table name
+   * @param existingRow - Current row data (should be fetched within same transaction)
+   * @throws RLSPolicyViolation if the operation is not allowed
    *
    * @example
    * ```typescript
-   * const guard = new MutationGuard(registry);
-   * const existingPost = await db.selectFrom('posts').where('id', '=', 1).selectAll().executeTakeFirst();
-   * await guard.checkDelete('posts', existingPost);
+   * // RECOMMENDED: Use within a transaction with row locking
+   * await db.transaction().execute(async (trx) => {
+   *   const existingPost = await trx
+   *     .selectFrom('posts')
+   *     .where('id', '=', 1)
+   *     .forUpdate()
+   *     .selectAll()
+   *     .executeTakeFirst();
+   *
+   *   await guard.checkDelete('posts', existingPost);
+   *   await trx.deleteFrom('posts').where('id', '=', 1).execute();
+   * });
    * ```
    */
   async checkDelete(table: string, existingRow: Record<string, unknown>): Promise<void> {