@kysera/rls 0.8.5 → 0.8.7

package/dist/index.d.ts

@@ -719,27 +719,13 @@ interface RLSPluginOptions<DB = unknown> {
  * Note: 'schema' and 'onViolation' are not included as they are complex runtime objects.
  */
 declare const RLSPluginOptionsSchema: z.ZodObject<{
-    excludeTables: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    bypassRoles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    excludeTables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    bypassRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
     requireContext: z.ZodOptional<z.ZodBoolean>;
     allowUnfilteredQueries: z.ZodOptional<z.ZodBoolean>;
     auditDecisions: z.ZodOptional<z.ZodBoolean>;
     primaryKeyColumn: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    excludeTables?: string[] | undefined;
-    bypassRoles?: string[] | undefined;
-    requireContext?: boolean | undefined;
-    allowUnfilteredQueries?: boolean | undefined;
-    auditDecisions?: boolean | undefined;
-    primaryKeyColumn?: string | undefined;
-}, {
-    excludeTables?: string[] | undefined;
-    bypassRoles?: string[] | undefined;
-    requireContext?: boolean | undefined;
-    allowUnfilteredQueries?: boolean | undefined;
-    auditDecisions?: boolean | undefined;
-    primaryKeyColumn?: string | undefined;
-}>;
+}, z.core.$strip>;
 /**
  * Create RLS plugin for Kysera
  *

package/dist/index.js

@@ -997,35 +997,70 @@ var MutationGuard = class {
     await this.checkMutation(table, "create", void 0, data);
   }
   /**
-   * 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(table, existingRow, data) {
     await this.checkMutation(table, "update", existingRow, data);
   }
   /**
-   * 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, existingRow) {
@@ -1454,7 +1489,12 @@ function rlsPlugin(options) {
           return await originalCreate(data);
         },
         /**
-         * 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, data) {
           if (!originalUpdate) {
@@ -1507,7 +1547,12 @@ function rlsPlugin(options) {
           return await originalUpdate(id, data);
         },
         /**
-         * 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) {
           if (!originalDelete) {