Add default and pointer permissions to CLP DSL

Enhances the Parse::CLP class and Parse::Object DSL to support default permissions for all operations, pointer-based permissions (readUserFields, writeUserFields), and improved snake_case to camelCase field conversion. Updates integration and unit tests to cover new features, including default permission propagation, pointer permissions, and field name conversions.

Author: AdrianCurtin

CHANGELOG.md

@@ -2,6 +2,48 @@
 
 ### 3.2.1
 
+#### New Features
+
+- **NEW**: Added `set_default_clp` method to set a default permission for all CLP operations at once. This is important because Parse Server treats missing operations as `{}` (no access, master key only).
+
+```ruby
+class Document < Parse::Object
+  # Set all operations to public by default
+  set_default_clp public: true
+
+  # Or require authentication for all operations
+  set_default_clp requires_authentication: true
+
+  # Or restrict all operations to specific roles
+  set_default_clp roles: ["Admin", "Editor"]
+
+  # Then override specific operations as needed
+  set_clp :delete, public: false, roles: ["Admin"]
+end
+```
+
+- **NEW**: Added `set_read_user_fields` and `set_write_user_fields` for pointer-based permissions. These allow users referenced by pointer fields to have read/write access to objects.
+
+```ruby
+class Document < Parse::Object
+  belongs_to :owner, as: :user
+  belongs_to :editor, as: :user
+
+  # Owner can read, editor can write
+  set_read_user_fields [:owner]
+  set_write_user_fields [:editor]
+
+  # Snake_case field names are auto-converted to camelCase
+end
+```
+
+- **NEW**: Added `reset_clp!` method to reset CLPs to public defaults. Useful for clearing restrictive permissions that may have accumulated on the server.
+
+```ruby
+# Reset all CLPs to public access
+Song.reset_clp!
+```
+
 #### Improvements
 
 - **IMPROVED**: CLP methods now automatically convert snake_case Ruby property names to camelCase Parse Server field names. This provides consistency with the rest of the Parse Stack framework where you define properties in snake_case.
@@ -12,7 +54,7 @@
 class Document < Parse::Object
   property :internal_notes, :string
   property :secret_data, :string
-  property :owner_user, :pointer, as: :user
+  belongs_to :owner_user, as: :user
 
   # Field names are auto-converted
   protect_fields "*", [:internal_notes, :secret_data]
@@ -33,17 +75,35 @@ end
 
 ```ruby
 class Document < Parse::Object
-  property :owner_field, :pointer, as: :user
-  property :editor_field, :pointer, as: :user
+  belongs_to :owner_field, as: :user
+  belongs_to :editor_field, as: :user
 
   # pointer_fields are auto-converted
   set_clp :update, pointer_fields: [:owner_field, :editor_field]
   # Converts to: pointerFields: ["ownerField", "editorField"]
 end
 ```
 
+- **IMPROVED**: Added `include_defaults` parameter to `CLP#as_json`. When `true`, includes default permissions for all undefined operations (useful when pushing complete CLP to server).
+
+```ruby
+clp = Parse::CLP.new
+clp.set_default_permission(public: true)
+clp.set_permission(:delete, roles: ["Admin"])
+
+# Without defaults - only explicitly set operations
+clp.as_json
+# => {"delete" => {"role:Admin" => true}}
+
+# With defaults - all operations included
+clp.as_json(include_defaults: true)
+# => {"find" => {"*" => true}, "get" => {"*" => true}, ... "delete" => {"role:Admin" => true}}
+```
+
 #### Bug Fixes
 
+- **FIXED**: `auto_upgrade!` now resets CLPs before applying new ones. Parse Server merges CLP updates rather than replacing them, so old restrictive permissions could persist and cause "Permission denied" errors. Now `auto_upgrade!` first resets CLPs to public defaults, then applies the model's CLP configuration.
+
 - **FIXED**: Test setup for role membership now correctly uses `add_users()` method for adding users to roles (roles use Parse Relations, not Array properties).
 
 ### 3.2.0

lib/parse/model/clp.rb

@@ -60,9 +60,15 @@ module Parse
   #
   # @see https://docs.parseplatform.org/rest/guide/#class-level-permissions
   class CLP
-    # Valid CLP operation keys
+    # Valid CLP operation keys for permission-based access
     OPERATIONS = %i[find get count create update delete addField].freeze
 
+    # Pointer-permission keys (users in these fields get read/write access)
+    POINTER_PERMISSIONS = %i[readUserFields writeUserFields].freeze
+
+    # All valid CLP keys
+    ALL_KEYS = (OPERATIONS + POINTER_PERMISSIONS + [:protectedFields]).freeze
+
     # @return [Hash] the raw CLP hash
     attr_reader :permissions
 
@@ -83,13 +89,50 @@ def parse_data(data)
           @protected_fields = value.transform_keys(&:to_s)
         elsif OPERATIONS.include?(key_sym)
           @permissions[key_sym] = value.transform_keys(&:to_s)
+        elsif POINTER_PERMISSIONS.include?(key_sym)
+          # readUserFields and writeUserFields are arrays of field names
+          @permissions[key_sym] = Array(value)
         else
-          # Store any other keys (like requiresAuthentication, etc.)
+          # Store any other keys
           @permissions[key_sym] = value
         end
       end
     end
 
+    # Set pointer-permission fields for read access.
+    # Users pointed to by these fields can read the object.
+    # @param fields [Array<String, Symbol>] pointer field names
+    # @return [self]
+    # @example
+    #   clp.set_read_user_fields(:owner, :collaborators)
+    def set_read_user_fields(*fields)
+      @permissions[:readUserFields] = fields.flatten.map(&:to_s)
+      self
+    end
+
+    # Set pointer-permission fields for write access.
+    # Users pointed to by these fields can write to the object.
+    # @param fields [Array<String, Symbol>] pointer field names
+    # @return [self]
+    # @example
+    #   clp.set_write_user_fields(:owner)
+    def set_write_user_fields(*fields)
+      @permissions[:writeUserFields] = fields.flatten.map(&:to_s)
+      self
+    end
+
+    # Get the read user fields.
+    # @return [Array<String>] pointer field names for read access
+    def read_user_fields
+      @permissions[:readUserFields] || []
+    end
+
+    # Get the write user fields.
+    # @return [Array<String>] pointer field names for write access
+    def write_user_fields
+      @permissions[:writeUserFields] || []
+    end
+
     # Set permissions for a specific operation.
     # @param operation [Symbol] one of :find, :get, :count, :create, :update, :delete, :addField
     # @param public_access [Boolean, nil] whether public access is allowed
@@ -255,14 +298,45 @@ def filter_fields(data, user: nil, roles: [], authenticated: nil)
       data.reject { |key, _| fields_to_hide.include?(key.to_s) }
     end
 
+    # The default permission to use for operations not explicitly set.
+    # When set, `as_json` will include this for all undefined operations.
+    # @return [Hash, nil] the default permission hash (e.g., { "*" => true })
+    attr_accessor :default_permission
+
     # Convert to Parse Server CLP format.
+    #
+    # IMPORTANT: Parse Server interprets missing operations as {} (no access).
+    # If you have protectedFields but no operations defined, the class becomes
+    # effectively master-key-only. Use `set_default_permission` or `include_defaults`
+    # to ensure all operations are included.
+    #
+    # @param include_defaults [Boolean] whether to include default permissions
+    #   for operations that haven't been explicitly set. Defaults to true if
+    #   any CLPs are defined (operations or protectedFields).
     # @return [Hash] the CLP hash suitable for schema updates
-    def as_json(*_args)
+    def as_json(include_defaults: nil)
       result = {}
 
+      # Determine if we should include defaults
+      # Auto-enable if any CLP settings exist and no explicit choice made
+      should_include_defaults = if include_defaults.nil?
+        present? && @default_permission
+      else
+        include_defaults
+      end
+
       # Add operation permissions
       OPERATIONS.each do |op|
-        result[op.to_s] = @permissions[op] if @permissions[op]
+        if @permissions[op]
+          result[op.to_s] = @permissions[op]
+        elsif should_include_defaults && @default_permission
+          result[op.to_s] = @default_permission.dup
+        end
+      end
+
+      # Add pointer permissions (readUserFields, writeUserFields)
+      POINTER_PERMISSIONS.each do |perm|
+        result[perm.to_s] = @permissions[perm] if @permissions[perm]&.any?
       end
 
       # Add protected fields
@@ -271,6 +345,26 @@ def as_json(*_args)
       result
     end
 
+    # Set the default permission for operations not explicitly configured.
+    # This ensures that when CLPs are pushed to Parse Server, all operations
+    # have explicit permissions (avoiding the implicit {} = no access behavior).
+    #
+    # @param public_access [Boolean] whether public access is allowed
+    # @param requires_authentication [Boolean] whether authentication is required
+    # @param roles [Array<String>] role names that have access
+    # @return [self]
+    # @example
+    #   clp.set_default_permission(public_access: true)  # Default to public
+    #   clp.set_default_permission(requires_authentication: true)  # Default to auth required
+    def set_default_permission(public_access: nil, requires_authentication: false, roles: [])
+      perm = {}
+      perm["*"] = true if public_access == true
+      perm["requiresAuthentication"] = true if requires_authentication
+      Array(roles).each { |role| perm["role:#{role}"] = true }
+      @default_permission = perm.empty? ? nil : perm
+      self
+    end
+
     alias_method :to_h, :as_json
 
     # Check if there are any CLP settings.

lib/parse/model/core/schema.rb

@@ -73,6 +73,37 @@ def fetch_schema
         Parse::Model::CLASS_SCHEMA
       ].freeze
 
+      # Default CLP that grants public access to all operations.
+      # Used to reset CLPs before applying new ones.
+      DEFAULT_PUBLIC_CLP = {
+        "find" => { "*" => true },
+        "get" => { "*" => true },
+        "count" => { "*" => true },
+        "create" => { "*" => true },
+        "update" => { "*" => true },
+        "delete" => { "*" => true },
+        "addField" => { "*" => true }
+      }.freeze
+
+      # Reset the CLP on the server to public defaults.
+      # This clears any existing restrictive permissions.
+      #
+      # @param client [Parse::Client] optional client to use
+      # @return [Parse::Response] the response from the server
+      #
+      # @example Reset CLPs to public
+      #   Song.reset_clp!
+      def reset_clp!(client: nil)
+        client ||= self.client
+
+        unless client.master_key.present?
+          warn "[Parse] CLP reset for #{parse_class} requires the master key!"
+          return nil
+        end
+
+        client.update_schema(parse_class, { "classLevelPermissions" => DEFAULT_PUBLIC_CLP })
+      end
+
       # A class method for non-destructive auto upgrading a remote schema based
       # on the properties and relations you have defined in your local model. If
       # the collection doesn't exist, we create the schema. If the collection already
@@ -123,9 +154,15 @@ def auto_upgrade!(include_clp: true)
             h
           end
 
-          # Add CLP updates if configured and requested
+          # Handle CLP updates if configured and requested
           if include_clp && respond_to?(:class_permissions) && class_permissions.present?
-            current_schema[:classLevelPermissions] = class_permissions.as_json
+            # First, reset CLPs to public defaults to clear any old restrictive permissions.
+            # Parse Server merges CLPs rather than replacing them, so old keys can persist
+            # and cause "Permission denied" errors if not explicitly cleared.
+            reset_clp!
+
+            # Now apply the new CLP configuration
+            current_schema[:classLevelPermissions] = class_permissions.as_json(include_defaults: true)
           end
 
           return true if current_schema[:fields].empty? && !current_schema[:classLevelPermissions]
@@ -136,7 +173,7 @@ def auto_upgrade!(include_clp: true)
         initial_schema = schema
         # Include CLPs in initial schema creation if configured
         if include_clp && respond_to?(:class_permissions) && class_permissions.present?
-          initial_schema[:classLevelPermissions] = class_permissions.as_json
+          initial_schema[:classLevelPermissions] = class_permissions.as_json(include_defaults: true)
         end
         client.create_schema parse_class, initial_schema
       end

lib/parse/model/object.rb

@@ -384,6 +384,90 @@ def class_permissions
 
       alias_method :clp, :class_permissions
 
+      # Set default permissions for all CLP operations at once.
+      # This is useful for establishing a baseline before customizing specific operations.
+      #
+      # @param public [Boolean] whether public access is allowed for all operations
+      # @param roles [Array<String>] role names that have access to all operations
+      # @param requires_authentication [Boolean] whether authentication is required for all operations
+      #
+      # @example Public read, authenticated write
+      #   class Document < Parse::Object
+      #     # Start with public read access for all operations
+      #     set_default_clp public: true
+      #
+      #     # Then restrict write operations
+      #     set_clp :create, requires_authentication: true
+      #     set_clp :update, requires_authentication: true
+      #     set_clp :delete, public: false, roles: ["Admin"]
+      #   end
+      #
+      # @example Role-based access for everything
+      #   class AdminReport < Parse::Object
+      #     # Only admins can do anything
+      #     set_default_clp public: false, roles: ["Admin"]
+      #   end
+      #
+      # @example Authenticated users only
+      #   class PrivateData < Parse::Object
+      #     # Require authentication for all operations
+      #     set_default_clp requires_authentication: true
+      #   end
+      def set_default_clp(public: nil, roles: [], requires_authentication: false)
+        # Set the default permission on the CLP instance
+        # This will be used by as_json to fill in missing operations
+        class_permissions.set_default_permission(
+          public_access: public,
+          roles: Array(roles),
+          requires_authentication: requires_authentication
+        )
+
+        # Also explicitly set all operations to ensure they're included
+        Parse::CLP::OPERATIONS.each do |operation|
+          set_clp(operation, public: public, roles: roles, requires_authentication: requires_authentication)
+        end
+      end
+
+      # Set pointer-permission fields for read access.
+      # Users pointed to by these fields can read objects of this class.
+      # This is an alternative to ACLs for owner-based access control.
+      #
+      # @param fields [Array<Symbol, String>] pointer field names (snake_case supported)
+      # @example
+      #   class Document < Parse::Object
+      #     belongs_to :owner, as: :user
+      #     belongs_to :editor, as: :user
+      #
+      #     # Only owner and editor can read
+      #     set_read_user_fields :owner, :editor
+      #   end
+      def set_read_user_fields(*fields)
+        converted = fields.flatten.map do |f|
+          field_sym = f.to_sym
+          field_map[field_sym] || f.to_s.camelize(:lower)
+        end
+        class_permissions.set_read_user_fields(*converted)
+      end
+
+      # Set pointer-permission fields for write access.
+      # Users pointed to by these fields can write to objects of this class.
+      #
+      # @param fields [Array<Symbol, String>] pointer field names (snake_case supported)
+      # @example
+      #   class Document < Parse::Object
+      #     belongs_to :owner, as: :user
+      #
+      #     # Only owner can write
+      #     set_write_user_fields :owner
+      #   end
+      def set_write_user_fields(*fields)
+        converted = fields.flatten.map do |f|
+          field_sym = f.to_sym
+          field_map[field_sym] || f.to_s.camelize(:lower)
+        end
+        class_permissions.set_write_user_fields(*converted)
+      end
+
       # Set a class-level permission for a specific operation.
       # This is the main DSL method for configuring CLPs in your model.
       #