parse-stack-next 4.5.0

data/lib/parse/two_factor_auth.rb

@@ -0,0 +1,310 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  # Multi-Factor Authentication (MFA) support for Parse Server.
+  #
+  # This module interfaces with Parse Server's built-in MFA adapter which supports
+  # TOTP (Time-based One-Time Password) and SMS-based authentication.
+  #
+  # == Parse Server Configuration
+  #
+  # MFA must be enabled in your Parse Server configuration:
+  #
+  #   {
+  #     auth: {
+  #       mfa: {
+  #         enabled: true,
+  #         options: ["TOTP"],  // or ["SMS", "TOTP"]
+  #         digits: 6,
+  #         period: 30,
+  #         algorithm: "SHA1"
+  #       }
+  #     }
+  #   }
+  #
+  # == TOTP Setup Flow
+  #
+  # 1. Generate a secret client-side using {MFA.generate_secret}
+  # 2. Display QR code to user using {MFA.provisioning_uri} or {MFA.qr_code}
+  # 3. User scans QR with authenticator app (Google Authenticator, Authy, etc.)
+  # 4. User enters the 6-digit code from their app
+  # 5. Call {User#setup_mfa!} with secret and token to enable MFA
+  # 6. Store the recovery codes returned - user needs these for account recovery!
+  #
+  # @example Enable TOTP MFA for a user
+  #   # Step 1: Generate secret
+  #   secret = Parse::MFA.generate_secret
+  #
+  #   # Step 2: Show QR code to user
+  #   qr_svg = Parse::MFA.qr_code(secret, user.email, issuer: "MyApp")
+  #   # render qr_svg in your UI
+  #
+  #   # Step 3-4: User scans and enters code
+  #   token = params[:totp_code]  # "123456" from authenticator app
+  #
+  #   # Step 5: Enable MFA
+  #   recovery_codes = user.setup_mfa!(secret: secret, token: token)
+  #   # => "ABC123DEF456..., XYZ789..."
+  #
+  #   # Step 6: Show recovery codes to user (one time only!)
+  #
+  # @example Login with MFA
+  #   user = Parse::User.login_with_mfa("username", "password", "123456")
+  #
+  # @see https://github.com/parse-community/parse-server/blob/master/src/Adapters/Auth/mfa.js
+  #
+  module MFA
+    # Error raised when MFA verification fails
+    class VerificationError < Parse::Error
+      def initialize(message = "Invalid MFA token")
+        super(message)
+      end
+    end
+
+    # Error raised when MFA is required but not provided
+    class RequiredError < Parse::Error
+      def initialize(message = "MFA token is required for this account")
+        super(message)
+      end
+    end
+
+    # Error raised when MFA is already set up
+    class AlreadyEnabledError < Parse::Error
+      def initialize(message = "MFA is already set up on this account")
+        super(message)
+      end
+    end
+
+    # Error raised when required gem is not available
+    class DependencyError < Parse::Error
+      def initialize(gem_name)
+        super("The '#{gem_name}' gem is required for this feature. Add to Gemfile: gem '#{gem_name}'")
+      end
+    end
+
+    # Error raised when an operator is not authorized to perform a
+    # privileged MFA operation (e.g. master-key disable). See
+    # {Parse::MFA::UserExtension#disable_mfa_master_key!}.
+    class ForbiddenError < Parse::Error
+      def initialize(message = "Not authorized to perform this MFA operation")
+        super(message)
+      end
+    end
+
+    # Default configuration
+    DEFAULT_CONFIG = {
+      issuer: "Parse App",
+      digits: 6,
+      period: 30,
+      algorithm: "SHA1",
+      secret_length: 20,  # Minimum required by Parse Server
+    }.freeze
+
+    class << self
+      # Global MFA configuration
+      # @return [Hash]
+      def config
+        @config ||= DEFAULT_CONFIG.dup
+      end
+
+      # Configure MFA settings
+      # @yield [config] Configuration hash
+      # @example
+      #   Parse::MFA.configure do |config|
+      #     config[:issuer] = "My App"
+      #   end
+      def configure
+        yield config if block_given?
+        config
+      end
+
+      # Check if rotp gem is available
+      # @return [Boolean]
+      def rotp_available?
+        require "rotp"
+        true
+      rescue LoadError
+        false
+      end
+
+      # Check if rqrcode gem is available
+      # @return [Boolean]
+      def rqrcode_available?
+        require "rqrcode"
+        true
+      rescue LoadError
+        false
+      end
+
+      # Generate a new TOTP secret for MFA setup.
+      # The secret must be at least 20 characters (Parse Server requirement).
+      #
+      # @param length [Integer] Secret length (minimum 20)
+      # @return [String] Base32-encoded secret
+      #
+      # @example
+      #   secret = Parse::MFA.generate_secret
+      #   # => "JBSWY3DPEHPK3PXP4QFAZJ7K"
+      def generate_secret(length: nil)
+        ensure_rotp!
+        length ||= config[:secret_length]
+        length = [length, 20].max  # Parse Server requires minimum 20
+        ROTP::Base32.random(length)
+      end
+
+      # Create a TOTP instance for verification.
+      #
+      # @param secret [String] Base32-encoded secret
+      # @param issuer [String] Optional issuer name
+      # @return [ROTP::TOTP]
+      def totp(secret, issuer: nil)
+        ensure_rotp!
+        ROTP::TOTP.new(
+          secret,
+          issuer: issuer || config[:issuer],
+          interval: config[:period],
+          digits: config[:digits],
+        )
+      end
+
+      # Verify a TOTP code locally (for testing/validation before sending to server).
+      #
+      # @param secret [String] Base32-encoded secret
+      # @param code [String] The 6-digit code to verify
+      # @return [Boolean] True if valid
+      #
+      # @example
+      #   if Parse::MFA.verify(secret, "123456")
+      #     puts "Code is valid!"
+      #   end
+      def verify(secret, code)
+        return false if secret.blank? || code.blank?
+
+        ensure_rotp!
+        drift_seconds = config[:period]
+        totp_instance = totp(secret)
+        totp_instance.verify(code.to_s, drift_behind: drift_seconds, drift_ahead: drift_seconds).present?
+      end
+
+      # Get the current TOTP code (for testing/debugging).
+      #
+      # @param secret [String] Base32-encoded secret
+      # @return [String] Current 6-digit code
+      def current_code(secret)
+        ensure_rotp!
+        totp(secret).now
+      end
+
+      # Generate provisioning URI for authenticator apps.
+      #
+      # @param secret [String] Base32-encoded secret
+      # @param account_name [String] User identifier (email or username)
+      # @param issuer [String] Optional issuer override
+      # @return [String] otpauth:// URI
+      #
+      # @example
+      #   uri = Parse::MFA.provisioning_uri(secret, "user@example.com", issuer: "MyApp")
+      #   # => "otpauth://totp/MyApp:user@example.com?secret=ABC123&issuer=MyApp"
+      def provisioning_uri(secret, account_name, issuer: nil)
+        ensure_rotp!
+        totp(secret, issuer: issuer).provisioning_uri(account_name)
+      end
+
+      # Generate a QR code for the authenticator app.
+      #
+      # @param secret [String] Base32-encoded secret
+      # @param account_name [String] User identifier
+      # @param issuer [String] Optional issuer name
+      # @param format [Symbol] Output format (:svg, :png, :ascii)
+      # @return [String] QR code in specified format
+      #
+      # @example
+      #   svg = Parse::MFA.qr_code(secret, user.email, issuer: "MyApp")
+      #   # Render in HTML: <%= raw svg %>
+      def qr_code(secret, account_name, issuer: nil, format: :svg)
+        ensure_rqrcode!
+        uri = provisioning_uri(secret, account_name, issuer: issuer)
+        qr = RQRCode::QRCode.new(uri)
+
+        case format
+        when :svg
+          qr.as_svg(
+            color: "000",
+            shape_rendering: "crispEdges",
+            module_size: 4,
+            standalone: true,
+          )
+        when :png
+          qr.as_png(size: 300)
+        when :ascii
+          qr.as_ansi
+        else
+          qr.as_svg
+        end
+      end
+
+      # Build authData hash for MFA setup.
+      #
+      # @param secret [String] Base32-encoded TOTP secret
+      # @param token [String] Current TOTP code for verification
+      # @return [Hash] authData for Parse Server
+      def build_setup_auth_data(secret:, token:)
+        {
+          mfa: {
+            secret: secret,
+            token: token,
+          },
+        }
+      end
+
+      # Build authData hash for MFA login.
+      #
+      # @param token [String] TOTP code or recovery code
+      # @return [Hash] authData for Parse Server
+      def build_login_auth_data(token:)
+        {
+          mfa: {
+            token: token,
+          },
+        }
+      end
+
+      # Build authData hash for SMS MFA setup.
+      #
+      # @param mobile [String] Phone number in E.164 format
+      # @return [Hash] authData for Parse Server
+      def build_sms_setup_auth_data(mobile:)
+        {
+          mfa: {
+            mobile: mobile,
+          },
+        }
+      end
+
+      # Build authData hash for SMS MFA confirmation.
+      #
+      # @param mobile [String] Phone number
+      # @param token [String] SMS code received
+      # @return [Hash] authData for Parse Server
+      def build_sms_confirm_auth_data(mobile:, token:)
+        {
+          mfa: {
+            mobile: mobile,
+            token: token,
+          },
+        }
+      end
+
+      private
+
+      def ensure_rotp!
+        raise DependencyError.new("rotp") unless rotp_available?
+      end
+
+      def ensure_rqrcode!
+        raise DependencyError.new("rqrcode") unless rqrcode_available?
+      end
+    end
+  end
+end

data/lib/parse/webhooks/payload.rb

@@ -0,0 +1,360 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "active_model"
+require "active_support"
+require "active_support/inflector"
+require "active_support/core_ext/object"
+require "active_support/core_ext/string"
+require "active_support/core_ext"
+require "active_model/serializers/json"
+
+module Parse
+  class Webhooks
+    # Represents the data structure that Parse server sends to a registered webhook.
+    # Parse Parse allows you to receive Cloud Code webhooks on your own hosted
+    # server. The `Parse::Webhooks` class is a lightweight Rack application that
+    # routes incoming Cloud Code webhook requests and payloads to locally
+    # registered handlers. The payloads are {Parse::Webhooks::Payload} type of objects that
+    # represent that data that Parse sends webhook handlers.
+    class Payload
+      # The set of keys that can be contained in a Parse hash payload for a webhook.
+      ATTRIBUTES = { master: nil, user: nil,
+                     installationId: nil, params: nil,
+                     functionName: nil, object: nil,
+                     original: nil, update: nil,
+                     query: nil, log: nil,
+                     objects: nil,
+                     triggerName: nil }.freeze
+      include ::ActiveModel::Serializers::JSON
+      # @!attribute [rw] master
+      #   @return [Boolean] whether the master key was used for this request.
+      # @!attribute [rw] user
+      #   @return [Parse::User] the user who performed this request or action.
+      # @!attribute [rw] installation_id
+      #   @return [String] The identifier of the device that submitted the request.
+      # @!attribute [rw] params
+      #   @return [Hash] The list of function arguments submitted for a function request.
+      # @!attribute [rw] function_name
+      #   @return [String] the name of the function.
+      # @!attribute [rw] object
+      #  In a beforeSave, this attribute is the final object that will be persisted.
+      #  @return [Hash] the object hash related to a webhook trigger request.
+      #  @see #parse_object
+      # @!attribute [rw] trigger_name
+      #  @return [String] the name of the trigger (ex. beforeSave, afterSave, etc.)
+      # @!attribute [rw] original
+      #  In a beforeSave, for previously saved objects, this attribute is the Parse::Object
+      #  that was previously in the persistent store.
+      #  @return [Hash] the object hash related to a webhook trigger request.
+      #  @see #parse_object
+      # @!attribute [rw] raw
+      #   @return [Hash] the raw payload from Parse server.
+      # @!attribute [rw] update
+      #   @return [Hash] the update payload in the request.
+      # @!attribute [r] query
+      # The query request in a beforeFind trigger. Available in Parse Server 2.3.1 or later.
+      #   @return [Parse::Query]
+      # @!attribute [r] objects
+      # The set of matching objects in an afterFind trigger. Available in Parse Server 2.3.1 or later.
+      #   @return [<Parse::Object>]
+      # @!attribute [r] log
+      # Logging information if available. Available in Parse Server 2.3.1 or later.
+      #   @return [Hash] the set of matching objects in an afterFind trigger.
+      attr_accessor :master, :user, :installation_id, :params, :function_name, :object, :trigger_name
+      attr_accessor :query, :log, :objects
+      attr_accessor :original, :update, :raw
+      # @!visibility private
+      attr_accessor :webhook_class
+      alias_method :installationId, :installation_id
+      alias_method :functionName, :function_name
+      alias_method :triggerName, :trigger_name
+
+      # You would normally never create a {Parse::Webhooks::Payload} object since it is automatically
+      # provided to you when using Parse::Webhooks.
+      # @see Parse::Webhooks
+      def initialize(hash = {})
+        hash = JSON.parse(hash, max_nesting: 20) if hash.is_a?(String)
+        hash = Hash[hash.map { |k, v| [k.to_s.underscore.to_sym, v] }]
+        @raw = hash
+        @master = hash[:master]
+        # Strip protected mass-assignment keys (sessionToken, _rperm, _wperm,
+        # _hashed_password, authData, roles, etc.) BEFORE constructing the
+        # user object. Without this, an attacker reaching the webhook
+        # endpoint with a valid key (or with the optional unauthenticated
+        # mode enabled) can forge any of these fields on +payload.user+
+        # via the +objectId+-present hydration branch that bypasses the
+        # +Parse::Object#apply_attributes!+ protected-key filter.
+        if hash[:user].present?
+          @user = Parse::User.new(self.class.scrub_protected_keys(hash[:user]))
+        end
+        @installation_id = hash[:installation_id]
+        @params = hash[:params]
+        @params = @params.with_indifferent_access if @params.is_a?(Hash)
+        @function_name = hash[:function_name]
+        @object = self.class.scrub_protected_keys(hash[:object])
+        @trigger_name = hash[:trigger_name]
+        @original = self.class.scrub_protected_keys(hash[:original])
+        @update = self.class.scrub_protected_keys(hash[:update]) || {}
+        # Added for beforeFind and afterFind triggers
+        @query = hash[:query]
+        @objects = hash[:objects] || []
+        @log = hash[:log]
+      end
+
+      # @!visibility private
+      # Routing metadata that must be preserved on payload hashes even
+      # though the general mass-assignment denylist forbids it. Stripping
+      # +className+ here breaks +parse_class+/+parse_object+ resolution and
+      # silently disables +payload_class_mismatch?+. The denylist still
+      # protects +Parse::Object#apply_attributes!+ at hydration time.
+      PAYLOAD_PRESERVED_KEYS = %w[className __type].freeze
+
+      # @!visibility private
+      # Returns a copy of +obj+ with the +PROTECTED_MASS_ASSIGNMENT_KEYS+
+      # removed, except for routing metadata in +PAYLOAD_PRESERVED_KEYS+.
+      # Operates on string and symbol keys (Parse Server uses camelCase
+      # strings on the wire; downstream code may have already symbolized).
+      # Pass-through for non-Hash input.
+      def self.scrub_protected_keys(obj)
+        return obj unless obj.is_a?(Hash)
+        denied = Parse::Properties::PROTECTED_MASS_ASSIGNMENT_KEYS
+        obj.reject do |k, _|
+          name = k.to_s
+          next false if PAYLOAD_PRESERVED_KEYS.include?(name)
+          denied.include?(name) || denied.include?(name.underscore)
+        end
+      end
+
+      # @return [ATTRIBUTES]
+      def attributes
+        ATTRIBUTES
+      end
+
+      # Method to print to standard that utilizes the an internal id to make it easier
+      # to trace incoming requests.
+      def wlog(s)
+        # generates a unique random number in order to be used in logging. This
+        # is useful when debugging issues in production where one server instance
+        # may be running multiple threads and you want to trace the incoming call.
+        @rid ||= rand(999).to_s.rjust(3)
+        puts "[> #{@rid}] #{s}"
+        @rid
+      end
+
+      # true if this is a webhook function request.
+      def function?
+        @function_name.present?
+      end
+
+      # true if the master key was used for this request.
+      def master?
+        @master.present?
+      end
+
+      # @return [String] the name of the Parse class for this request.
+      def parse_class
+        return @webhook_class if @webhook_class.present?
+        return nil unless @object.present?
+        @object[Parse::Model::KEY_CLASS_NAME] || @object[:className]
+      end
+
+      # @return [String] the objectId in this request.
+      def parse_id
+        return nil unless @object.present?
+        @object[Parse::Model::OBJECT_ID] || @object[:objectId]
+      end
+
+      alias_method :objectId, :parse_id
+
+      # true if this is a webhook trigger request.
+      def trigger?
+        @trigger_name.present?
+      end
+
+      # true if this is a beforeSave or beforeDelete webhook trigger request.
+      def before_trigger?
+        before_save? || before_delete? || before_find?
+      end
+
+      # true if this is a afterSave or afterDelete webhook trigger request.
+      def after_trigger?
+        after_save? || after_delete? || after_find?
+      end
+
+      # true if this is a beforeSave webhook trigger request.
+      def before_save?
+        trigger? && @trigger_name.to_sym == :beforeSave
+      end
+
+      # true if this is a afterSave webhook trigger request.
+      def after_save?
+        trigger? && @trigger_name.to_sym == :afterSave
+      end
+
+      # true if this is a beforeDelete webhook trigger request.
+      def before_delete?
+        trigger? && @trigger_name.to_sym == :beforeDelete
+      end
+
+      # true if this is a afterDelete webhook trigger request.
+      def after_delete?
+        trigger? && @trigger_name.to_sym == :afterDelete
+      end
+
+      # true if this is a beforeFind webhook trigger request.
+      def before_find?
+        trigger? && @trigger_name.to_sym == :beforeFind
+      end
+
+      # true if this is a afterFind webhook trigger request.
+      def after_find?
+        trigger? && @trigger_name.to_sym == :afterFind
+      end
+
+      # true if this request is a trigger that contains an object.
+      def object?
+        trigger? && @object.present?
+      end
+
+      # @return [Parse::Object] a Parse::Object from the original object
+      def original_parse_object
+        return nil unless @original.is_a?(Hash)
+        # Always pass the trigger's expected class explicitly so the
+        # className inside the payload cannot redirect this hydration to a
+        # different class.
+        Parse::Object.build(@original, parse_class)
+      end
+
+      # This method returns a Parse::Object by combining the original object, if was provided,
+      # with the final object. This will return a dirty tracked Parse::Object subclass,
+      # that will have information on which fields have changed between the previous state
+      # in the persistent store and the one about to be saved.
+      # @param pristine [Boolean] whether the object should be returned without dirty tracking.
+      # @return [Parse::Object] a dirty tracked Parse::Object subclass instance
+      def parse_object(pristine = false)
+        return nil unless object?
+        return Parse::Object.build(@object, parse_class) if pristine
+        # Memoize so pre-block guard application and the user webhook handler
+        # observe the same instance. Otherwise field_guards applied on the
+        # framework's pre-built object would be invisible to the block's
+        # later parse_object call (which would construct a fresh dirty-tracked
+        # object from @object/@original).
+        return @parse_object if defined?(@parse_object) && !@parse_object.nil?
+        @parse_object = build_parse_object
+      end
+
+      # @!visibility private
+      # Returns +true+ when +@object+/+@original+ contain a className that
+      # disagrees with the trigger's expected class. Used to skip building
+      # a typed object when the payload was clearly forged or routed
+      # incorrectly.
+      def payload_class_mismatch?
+        expected = parse_class
+        return false if expected.nil?
+        [@object, @original, @update].any? do |h|
+          h.is_a?(Hash) && h["className"] && h["className"] != expected
+        end
+      end
+
+      # Force a fresh build, discarding any memoized parse_object. Used by the
+      # webhook framework after mutating @object / @update so a subsequent
+      # parse_object call picks up the modified payload state.
+      # @!visibility private
+      def reset_parse_object_cache!
+        @parse_object = nil
+      end
+
+      private
+
+      def build_parse_object
+        # if its a before trigger, then we build the original object and apply the updates
+        # in order to create a Parse::Object that has the dirty tracking information
+        # if no original is nil, then it means this is a brand new object, so we create
+        # one from the className
+        if before_trigger?
+          # if original is present, then this is a modified object
+          if @original.present? && @original.is_a?(Hash)
+            o = Parse::Object.build @original, parse_class
+            o.apply_attributes! @object, dirty_track: true
+
+            if o.is_a?(Parse::User) && @update.present? && @update["authData"].present?
+              o.auth_data = @update["authData"]
+            end
+            return o
+          else #else the object must be new
+            klass = Parse::Object.find_class parse_class
+            # if we have a class, return that with updated changes, otherwise
+            # default to regular object
+            if klass.present?
+              o = klass.new(@object || {})
+              if o.is_a?(Parse::User) && @update.present? && @update["authData"].present?
+                o.auth_data = @update["authData"]
+              end
+              return o
+            end # if klass.present?
+          end # if we have original
+        end # if before_trigger?
+        Parse::Object.build(@object, parse_class)
+      end
+
+      public
+
+      # This method will intentionally raise a {Parse::Webhooks::ResponseError} with
+      # a specific message. When used inside of a registered cloud code webhook
+      # function or trigger, will halt processing and return the proper error response
+      # code back to the Parse server.
+      # @param msg [String] the error message to send back.
+      # @raise Parse::Webhooks::ResponseError
+      # @return [Parse::Webhooks::ResponseError] the raised exception
+      def error!(msg = "")
+        raise Parse::Webhooks::ResponseError, msg
+      end
+
+      # @return [Parse::Query] the Parse query for a beforeFind trigger.
+      def parse_query
+        return nil unless parse_class.present? && @query.is_a?(Hash)
+        Parse::Query.new parse_class, @query
+      end
+
+      # Returns true if this webhook was triggered by a Ruby Parse Stack request.
+      # This is determined by checking for the '_RB_' prefix in the request ID header.
+      # This flag is useful for preventing callback loops and implementing intelligent
+      # callback handling based on the request origin.
+      # @return [Boolean] true if the request originated from Ruby Parse Stack
+      def ruby_initiated?
+        @ruby_initiated ||= begin
+            request_id = nil
+
+            if @raw.respond_to?(:[])
+              # Check for headers at the top level first
+              request_id = @raw["x-parse-request-id"] || @raw["X-Parse-Request-Id"] ||
+                           @raw[:x_parse_request_id] || @raw[:'X-Parse-Request-Id']
+
+              # If not found at top level, check nested headers
+              if request_id.nil?
+                headers_sym = @raw[:headers] if @raw[:headers].is_a?(Hash)
+                headers_str = @raw["headers"] if @raw["headers"].is_a?(Hash)
+
+                if headers_sym
+                  request_id = headers_sym["x-parse-request-id"] || headers_sym["X-Parse-Request-Id"]
+                elsif headers_str
+                  request_id = headers_str["x-parse-request-id"] || headers_str["X-Parse-Request-Id"]
+                end
+              end
+            end
+
+            request_id&.start_with?("_RB_") || false
+          end
+      end
+
+      # Returns true if this webhook was triggered by a client request (JavaScript, iOS, Android, etc.)
+      # This is the inverse of ruby_initiated? and is useful for callback logic that should
+      # only run for client-initiated operations.
+      # @return [Boolean] true if the request originated from a client (not Ruby)
+      def client_initiated?
+        !ruby_initiated?
+      end
+    end # Payload
+  end
+end