parse-stack-next 4.5.0

data/lib/parse/api/path_segment.rb

@@ -0,0 +1,75 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "uri"
+
+module Parse
+  module API
+    # Helpers for safely interpolating user-controlled segments into REST
+    # paths. Every site that builds a request URL via raw string
+    # interpolation (`"functions/#{name}"`, `"schemas/#{className}"`, etc.)
+    # should route the name through one of these helpers first so a caller
+    # passing `"../classes/_User?where=%7B%7D"` cannot traverse to a
+    # different endpoint and read it with whatever credentials the outer
+    # request was authorized to send.
+    module PathSegment
+      module_function
+
+      # Parse identifier pattern: starts with a letter or underscore (Parse
+      # uses leading underscore for system classes like `_User`,
+      # `_Session`, `_Role`), then alphanumerics and underscores. Matches
+      # the documented Parse class/field/function/job naming rules.
+      IDENTIFIER_PATTERN = /\A[A-Za-z_][A-Za-z0-9_]*\z/.freeze
+
+      # Validate a Parse identifier (class name, function name, job name,
+      # field name) and return it unchanged. Identifiers are already
+      # path-safe under the strict pattern, so no percent-encoding is
+      # needed; we just refuse anything that violates the shape.
+      #
+      # @param value the identifier to validate (anything responding to
+      #   `to_s`).
+      # @param kind [String] human-readable name for error messages.
+      # @return [String] the validated identifier.
+      # @raise [ArgumentError] if blank, contains a slash, contains a dot,
+      #   or otherwise fails the pattern.
+      def identifier!(value, kind: "name")
+        s = value.to_s
+        if s.empty?
+          raise ArgumentError, "#{kind} must not be empty"
+        end
+        unless IDENTIFIER_PATTERN.match?(s)
+          raise ArgumentError,
+            "#{kind} #{s.inspect} contains characters that are not allowed in " \
+            "a Parse identifier. Names must match /\\A[A-Za-z_][A-Za-z0-9_]*\\z/."
+        end
+        s
+      end
+
+      # Validate and percent-encode a less-restrictive path segment, used
+      # for file names which can contain hyphens, periods, and other
+      # filename-safe characters but must never contain a literal `/`,
+      # `..`, or NUL/control characters.
+      #
+      # @param value the segment to validate.
+      # @param kind [String] human-readable name for error messages.
+      # @return [String] percent-encoded segment safe for path interpolation.
+      # @raise [ArgumentError] if blank, contains a slash, is a path-
+      #   traversal token, or contains control characters.
+      def file!(value, kind: "filename")
+        s = value.to_s
+        if s.empty?
+          raise ArgumentError, "#{kind} must not be empty"
+        end
+        if s.include?("/") || s == ".." || s == "."
+          raise ArgumentError,
+            "#{kind} #{s.inspect} contains path-traversal characters " \
+            "(`/`, `.`, or `..`). Names must be a single path segment."
+        end
+        if s.match?(/[\x00-\x1F\x7F]/)
+          raise ArgumentError, "#{kind} #{s.inspect} contains control characters"
+        end
+        URI.encode_www_form_component(s)
+      end
+    end
+  end
+end

data/lib/parse/api/push.rb

@@ -0,0 +1,20 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module API
+    # Defines the Parse Push notification service interface for the Parse REST API
+    module Push
+      # @!visibility private
+      PUSH_PATH = "push"
+
+      # Update the schema for a collection.
+      # @param payload [Hash] the paylod for the Push notification.
+      # @return [Parse::Response]
+      # @see http://docs.parseplatform.org/rest/guide/#sending-pushes Sending Pushes
+      def push(payload = {})
+        request :post, PUSH_PATH, body: payload.as_json
+      end
+    end
+  end
+end

data/lib/parse/api/schema.rb

@@ -0,0 +1,49 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module API
+    # Defines the Schema interface for the Parse REST API
+    module Schema
+      # @!visibility private
+      SCHEMAS_PATH = "schemas"
+
+      # Get all the schemas for the application.
+      # @param opts [Hash] additional options for the request.
+      # @return [Parse::Response]
+      def schemas(opts = {})
+        request_opts = { cache: false }.merge(opts)
+        request :get, SCHEMAS_PATH, opts: request_opts
+      end
+
+      # Get the schema for a collection.
+      # @param className [String] the name of the remote Parse collection.
+      # @return [Parse::Response]
+      def schema(className)
+        safe = Parse::API::PathSegment.identifier!(className, kind: "class name")
+        opts = { cache: false }
+        request :get, "#{SCHEMAS_PATH}/#{safe}", opts: opts
+      end
+
+      # Create a new collection with the specific schema.
+      # @param className [String] the name of the remote Parse collection.
+      # @param schema [Hash] the schema hash. This is a specific format specified by
+      #  Parse.
+      # @return [Parse::Response]
+      def create_schema(className, schema)
+        safe = Parse::API::PathSegment.identifier!(className, kind: "class name")
+        request :post, "#{SCHEMAS_PATH}/#{safe}", body: schema
+      end
+
+      # Update the schema for a collection.
+      # @param className [String] the name of the remote Parse collection.
+      # @param schema [Hash] the schema hash. This is a specific format specified by
+      #  Parse.
+      # @return [Parse::Response]
+      def update_schema(className, schema)
+        safe = Parse::API::PathSegment.identifier!(className, kind: "class name")
+        request :put, "#{SCHEMAS_PATH}/#{safe}", body: schema
+      end
+    end #Schema
+  end #API
+end

data/lib/parse/api/server.rb

@@ -0,0 +1,50 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module API
+    # APIs related to the open source Parse Server.
+    module Server
+
+      # @!attribute server_info
+      #  @return [Hash] the information about the server.
+      attr_writer :server_info
+
+      # @!visibility private
+      SERVER_INFO_PATH = "serverInfo"
+      # @!visibility private
+      SERVER_HEALTH_PATH = "health"
+      # Fetch and cache information about the Parse server configuration. This
+      # hash contains information specifically to the configuration of the running
+      # parse server.
+      # @return (see #server_info!)
+      def server_info
+        return @server_info if @server_info.present?
+        response = request :get, SERVER_INFO_PATH
+        @server_info = response.error? ? nil :
+          response.result.with_indifferent_access
+      end
+
+      # Fetches the status of the server based on the health check.
+      # @return [Boolean] whether the server is 'OK'.
+      def server_health
+        opts = { cache: false }
+        response = request :get, SERVER_HEALTH_PATH, opts: opts
+        response.success?
+      end
+
+      # Force fetches the server information.
+      # @return [Hash] a hash containing server configuration if available.
+      def server_info!
+        @server_info = nil
+        server_info
+      end
+
+      # Returns the version of the Parse server the client is connected to.
+      # @return [String] a version string (ex. '2.2.25') if available.
+      def server_version
+        server_info.present? ? @server_info[:parseServerVersion] : nil
+      end
+    end
+  end
+end

data/lib/parse/api/sessions.rb

@@ -0,0 +1,24 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module API
+    # Defines the Session class interface for the Parse REST API
+    module Sessions
+      # @!visibility private
+      SESSION_PATH_PREFIX = "sessions"
+
+      # Fetch a session record for a given session token.
+      # @param session_token [String] an active session token.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @return [Parse::Response]
+      def fetch_session(session_token, **opts)
+        opts.merge!({ use_master_key: false, cache: false })
+        headers = { Parse::Protocol::SESSION_TOKEN => session_token }
+        response = request :get, "#{SESSION_PATH_PREFIX}/me", headers: headers, opts: opts
+        response.parse_class = Parse::Model::CLASS_SESSION
+        response
+      end
+    end
+  end
+end

data/lib/parse/api/users.rb

@@ -0,0 +1,250 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "open-uri"
+
+module Parse
+  module API
+    # Defines the User class interface for the Parse REST API
+    module Users
+      # @!visibility private
+      USER_PATH_PREFIX = "users"
+      # @!visibility private
+      LOGOUT_PATH = "logout"
+      # @!visibility private
+      LOGIN_PATH = "login"
+      # @!visibility private
+      REQUEST_PASSWORD_RESET = "requestPasswordReset"
+
+      # Fetch a {Parse::User} for a given objectId.
+      # @param id [String] the user objectid
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
+      def fetch_user(id, headers: {}, **opts)
+        request :get, "#{USER_PATH_PREFIX}/#{id}", headers: headers, opts: opts
+      end
+
+      # Find users matching a set of constraints.
+      # @param query [Hash] query parameters.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
+      def find_users(query = {}, headers: {}, **opts)
+        response = request :get, USER_PATH_PREFIX, query: query, headers: headers, opts: opts
+        response.parse_class = Parse::Model::CLASS_USER
+        response
+      end
+
+      # Find user matching this active session token.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
+      def current_user(session_token, headers: {}, **opts)
+        headers.merge!({ Parse::Protocol::SESSION_TOKEN => session_token })
+        response = request :get, "#{USER_PATH_PREFIX}/me", headers: headers, opts: opts
+        response.parse_class = Parse::Model::CLASS_USER
+        response
+      end
+
+      # Create a new user.
+      # @param body [Hash] a hash of values related to your _User schema.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
+      def create_user(body, headers: {}, **opts)
+        headers.merge!({ Parse::Protocol::REVOCABLE_SESSION => "1" })
+        if opts[:session_token].present?
+          headers.merge!({ Parse::Protocol::SESSION_TOKEN => opts[:session_token] })
+        end
+        response = request :post, USER_PATH_PREFIX, body: body, headers: headers, opts: opts
+        response.parse_class = Parse::Model::CLASS_USER
+        response
+      end
+
+      # Update a {Parse::User} record given an objectId.
+      # @param id [String] the Parse user objectId.
+      # @param body [Hash] the body of the API request.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
+      def update_user(id, body = {}, headers: {}, **opts)
+        response = request :put, "#{USER_PATH_PREFIX}/#{id}", body: body, opts: opts
+        response.parse_class = Parse::Model::CLASS_USER
+        response
+      end
+
+      # Set the authentication service OAUth data for a user. Deleting or unlinking
+      # is done by setting the authData of the service name to nil.
+      # @param id [String] the Parse user objectId.
+      # @param service_name [Symbol] the name of the OAuth service.
+      # @param auth_data [Hash] the hash data related to the third-party service.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
+      def set_service_auth_data(id, service_name, auth_data, headers: {}, **opts)
+        body = { authData: { service_name => auth_data } }
+        update_user(id, body, headers: headers, **opts)
+      end
+
+      # Delete a {Parse::User} record given an objectId.
+      # @param id [String] the Parse user objectId.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
+      def delete_user(id, headers: {}, **opts)
+        request :delete, "#{USER_PATH_PREFIX}/#{id}", headers: headers, opts: opts
+      end
+
+      # Request a password reset for a registered email.
+      # @param email [String] the Parse user email.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
+      def request_password_reset(email, headers: {}, **opts)
+        body = { email: email }
+        request :post, REQUEST_PASSWORD_RESET, body: body, opts: opts, headers: headers
+      end
+
+      # Login a user. Implements client-side rate limiting with exponential
+      # backoff after repeated failures to mitigate brute force attacks.
+      # @param username [String] the Parse user username.
+      # @param password [String] the Parse user's associated password.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @return [Parse::Response]
+      def login(username, password, headers: {}, **opts)
+        check_login_rate_limit!(username)
+        body = { username: username, password: password }
+        headers.merge!({ Parse::Protocol::REVOCABLE_SESSION => "1" })
+        response = request :post, LOGIN_PATH, body: body, headers: headers, opts: opts
+        response.parse_class = Parse::Model::CLASS_USER
+        track_login_attempt(username, response.success?)
+        response
+      end
+
+      # Login a user with MFA (Multi-Factor Authentication).
+      #
+      # This method handles Parse Server's MFA adapter which requires both
+      # standard credentials AND an MFA token when MFA is enabled for the user.
+      #
+      # @param username [String] the Parse user username.
+      # @param password [String] the Parse user's associated password.
+      # @param mfa_token [String] the TOTP code from authenticator app or recovery code.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @return [Parse::Response]
+      #
+      # @example
+      #   response = client.login_with_mfa("john", "password123", "123456")
+      def login_with_mfa(username, password, mfa_token, headers: {}, **opts)
+        check_login_rate_limit!(username)
+        # Parse Server expects authData to be sent with POST for MFA login
+        body = {
+          username: username,
+          password: password,
+          authData: {
+            mfa: {
+              token: mfa_token,
+            },
+          },
+        }
+        headers.merge!({ Parse::Protocol::REVOCABLE_SESSION => "1" })
+        response = request :post, LOGIN_PATH, body: body, headers: headers, opts: opts
+        response.parse_class = Parse::Model::CLASS_USER
+        track_login_attempt(username, response.success?)
+        response
+      end
+
+      # Logout a user by deleting the associated session.
+      # @param session_token [String] the Parse user session token to delete.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @return [Parse::Response]
+      def logout(session_token, headers: {}, **opts)
+        headers.merge!({ Parse::Protocol::SESSION_TOKEN => session_token })
+        opts.merge!({ use_master_key: false, session_token: session_token })
+        request :post, LOGOUT_PATH, headers: headers, opts: opts
+      end
+
+      # Signup a user given a username, password and, optionally, their email.
+      # @param username [String] the Parse user username.
+      # @param password [String] the Parse user's associated password.
+      # @param email [String] the desired Parse user's email.
+      # @param body [Hash] additional property values to pass when creating the user record.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @return [Parse::Response]
+      def signup(username, password, email = nil, body: {}, **opts)
+        body = body.merge({ username: username, password: password })
+        body[:email] = email || body[:email]
+        create_user(body, **opts)
+      end
+      private
+
+      # @!visibility private
+      # Thread-safe tracker for login rate limiting. Keys are usernames, values are
+      # { failures: Integer, locked_until: Time }.
+      def login_rate_limits
+        @login_rate_limit_mutex ||= Mutex.new
+        @login_rate_limits ||= {}
+      end
+
+      # Maximum consecutive failures before lockout.
+      LOGIN_MAX_FAILURES = 5
+      # Base delay in seconds for exponential backoff.
+      LOGIN_BASE_DELAY = 2
+      # Maximum number of tracked usernames before cleanup.
+      LOGIN_RATE_LIMIT_MAX_ENTRIES = 10_000
+      # Entries older than this (seconds) are eligible for cleanup.
+      LOGIN_RATE_LIMIT_TTL = 600
+
+      # Checks if a login attempt is allowed for the given username.
+      # @raise [RuntimeError] if the account is temporarily locked out.
+      def check_login_rate_limit!(username)
+        @login_rate_limit_mutex ||= Mutex.new
+        @login_rate_limit_mutex.synchronize do
+          entry = login_rate_limits[username]
+          return unless entry
+          if entry[:locked_until] && Time.now < entry[:locked_until]
+            wait = (entry[:locked_until] - Time.now).ceil
+            raise "Login rate limited for '#{username}'. Try again in #{wait} seconds."
+          end
+        end
+      end
+
+      # Records a login attempt result and applies exponential backoff on failure.
+      def track_login_attempt(username, success)
+        @login_rate_limit_mutex ||= Mutex.new
+        @login_rate_limit_mutex.synchronize do
+          if success
+            login_rate_limits.delete(username)
+          else
+            entry = login_rate_limits[username] || { failures: 0, locked_until: nil }
+            entry[:failures] += 1
+            if entry[:failures] >= LOGIN_MAX_FAILURES
+              delay = LOGIN_BASE_DELAY**(entry[:failures] - LOGIN_MAX_FAILURES + 1)
+              delay = [delay, 300].min # cap at 5 minutes
+              entry[:locked_until] = Time.now + delay
+            end
+            login_rate_limits[username] = entry
+          end
+          # Periodic cleanup of expired entries to prevent memory leak
+          cleanup_login_rate_limits if login_rate_limits.size > LOGIN_RATE_LIMIT_MAX_ENTRIES
+        end
+      end
+
+      # Removes expired entries from the rate limit tracker.
+      # Only deletes entries whose lockout has actually expired past the TTL —
+      # never deletes pre-lockout failure counters (which would defeat rate limiting
+      # by letting an attacker flood random usernames to trigger cleanup and reset
+      # a target's in-progress counter).
+      def cleanup_login_rate_limits
+        now = Time.now
+        login_rate_limits.delete_if do |_username, entry|
+          entry[:locked_until] && (now - entry[:locked_until]) > LOGIN_RATE_LIMIT_TTL
+        end
+      end
+
+    end # Users
+  end #API
+end #Parse