feat: Add helpers for step up auth

Resolves USER-980

lib/clerk.rb

@@ -2,6 +2,7 @@
 
 require_relative "clerk/version"
 require_relative "clerk/sdk"
+require_relative "clerk/constants"
 
 module Clerk
   class << self

lib/clerk/authenticatable.rb

@@ -73,6 +73,14 @@ def clerk_user_signed_in?
       !!clerk_verified_session_claims
     end
 
+    def clerk_session_needs_reverification?(params=StepUp::PRESETS[:strict])
+      request.env['clerk'].needs_reverification?(params)
+    end
+
+    def clerk_render_reverification(missing_config={})
+      render status: 403, json: request.env['clerk'].reverification_mismatch_payload
+    end
+
     def clerk_sign_in_url
       ENV.fetch("CLERK_SIGN_IN_URL")
     end

lib/clerk/constants.rb

@@ -0,0 +1,10 @@
+module Clerk
+  module StepUp
+    PRESETS = {
+      very_strict: { after_minutes: 10,   level: :multi_factor  },
+      strict:      { after_minutes: 10,   level: :second_factor },
+      moderate:    { after_minutes: 60,   level: :second_factor },
+      lax:         { after_minutes: 1440, level: :second_factor }
+    }
+  end
+end

lib/clerk/rack_middleware_v2.rb

@@ -60,6 +60,46 @@ def org_permissions
       @session_claims["org_permissions"]
     end
 
+    # Returns true if the session needs to perform step up verification
+    def needs_reverification?(params)
+      return false if session_claims.nil?
+
+      fva           = session_claims["fva"]
+      level         = params[:level]
+      after_minutes = Integer(params[:after_minutes])
+
+      return false if fva.nil? || after_minutes.nil? || level.nil?
+
+      factor1_age, factor2_age = fva
+      factor1_enabled = (factor1_age == -1 ? false : after_minutes > factor1_age)
+      factor2_enabled = (factor2_age == -1 ? false : after_minutes > factor2_age)
+
+      case level
+      when :first_factor  then factor1_enabled
+      when :second_factor then factor2_enabled
+      when :multi_factor
+        factor2_age == -1 ? factor1_enabled : factor1_enabled && factor2_enabled
+      end
+    end
+
+    def reverification_mismatch_payload(missing_config={})
+      {
+        clerk_error: {
+          type:     "forbidden",
+          reason:   "reverification-mismatch",
+          metadata: { reverification: missing_config, }
+        }
+      }
+    end
+
+    def reverification_response(missing_config={})
+      [
+        403,
+        { "Content-Type" => "application/json" },
+        [reverification_mismatch_payload(missing_config).to_json],
+      ]
+    end
+
     private
 
     def fetch_user(user_id)