clerk-sdk-ruby 3.3.0 → 4.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7744ad750d46b3102978f5b07956bb4f9b6a34635282fc3b0e082a98be92da47
-  data.tar.gz: 30e879ce6e9f2945a85451b9141b077f5d3ea31dbe4d30b16ceda2fe18a7aa32
+  metadata.gz: 7b3b121821e34e9882661931f7e5c7ccdd630095905252ba53c8a48b9c62320c
+  data.tar.gz: ab0b8077553effb1c8521204787499ee28e0a544629980a7b098789a5c474e14
 SHA512:
-  metadata.gz: a0c95f53c97b59dcf24ff4963b746a75e6f20ed4d26118aecaad0b04e43f8ca694b96d4f73017d62e03d58e8a0128f05161dd6825c7c89b3e2bb5cda6f291d76
-  data.tar.gz: d1f6220cfbd9d28114631d09d896f883eda94ec8589531099ff8033995e598ed92866cec7b1797d2c3534d487218eea1173be80f56b11594209132e653a26feb
+  metadata.gz: 007f6ba6dc18e7d1e54173160e069bc76869b7c13a645eea53943669536ad3963e95272a2ace2d64cd7c9c68d3386dbe5695726e235f559f59f8b15f1addec99
+  data.tar.gz: a0ecb1901197fe8e2a01269326dfb61bdf6da2dd0b9c22298fb580370d6cf2527f5e5f1eaa0a19687b3d242104bf8784a740ac80bfae0df1ff576e1b03c14451

data/.github/workflows/main.yml

@@ -16,3 +16,5 @@ jobs:
         gem install bundler -v 2.2.15
         bundle install
         bundle exec rake
+env:
+  CLERK_PUBLISHABLE_KEY: 'pk_test_ZXhhbXBsZS5jb20k'

data/.github/workflows/semgrep.yml

@@ -0,0 +1,24 @@
+name: Semgrep
+on:
+  workflow_dispatch: {}
+  pull_request: {}
+  push:
+    branches:
+      - main
+    paths:
+      - .github/workflows/semgrep.yml
+  schedule:
+    # random HH:MM to avoid a load spike on GitHub Actions at 00:00
+    - cron: '15 18 * * *'
+jobs:
+  semgrep:
+    name: semgrep/ci
+    runs-on: ubuntu-22.04
+    env:
+      SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
+    container:
+      image: returntocorp/semgrep
+    if: (github.actor != 'dependabot[bot]')
+    steps:
+      - uses: actions/checkout@v3
+      - run: semgrep ci

data/CHANGELOG.md

@@ -1,22 +1,17 @@
-## unreleased
 
-## 3.3.0 - 2024-11-22
+## 4.0.0.beta2 - 2024-02-26
 
-- changed: Align reverification names with other SDKs [https://github.com/clerk/clerk-sdk-ruby/pull/73]
+Note: this is identical to 4.0.0.beta1, which was yanked because it was not generated from the main branch.
 
+- feat: replace interstitial with handshake (internal mechanisms) [https://github.com/clerk/clerk-sdk-ruby/pull/45]
+- chore: re-organize and refactor internal code to extract functionality of rack middleware [https://github.com/clerk/clerk-sdk-ruby/pull/45]
+- changed: `CLERK_PUBLISHABLE_KEY` or `publishable_key` in `Clerk.configure` is **required** [https://github.com/clerk/clerk-sdk-ruby/pull/46]
 
-## 3.3.0.beta1 - 2024-11-04
+## [YANKED] 4.0.0.beta1 - 2024-02-26
 
-- feat: Add helpers for Step Up auth / re-verification [https://github.com/clerk/clerk-sdk-ruby/pull/72]
-
-## 3.2.0 - 2024-04-08
-
-- fix: Infinite redirect loop when client_uat=0 and `__session` exists [https://github.com/clerk/clerk-sdk-ruby/pull/55]
-
-## 3.1.0 - 2024-03-19
-
-- fix: Incompatible __client_uat & __session should show interstitial (#51) [https://github.com/clerk/clerk-sdk-ruby/pull/51]
-- fix: Incorrect check that lead to infinite redirect loop introduced by (#51) [https://github.com/clerk/clerk-sdk-ruby/pull/51]
+- feat: replace interstitial with handshake (internal mechanisms) [https://github.com/clerk/clerk-sdk-ruby/pull/45]
+- chore: re-organize and refactor internal code to extract functionality of rack middleware [https://github.com/clerk/clerk-sdk-ruby/pull/45]
+- changed: `CLERK_PUBLISHABLE_KEY` or `publishable_key` in `Clerk.configure` is **required** [https://github.com/clerk/clerk-sdk-ruby/pull/46]
 
 ## 3.0.0 - 2024-01-09
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    clerk-sdk-ruby (3.2.0)
+    clerk-sdk-ruby (4.0.0.beta2)
       concurrent-ruby (~> 1.1)
       faraday (>= 1.4.1, < 3.0)
       jwt (~> 2.5)

data/README.md

@@ -87,8 +87,9 @@ supported configuration settings their environment variable equivalents:
 
 ```ruby
 Clerk.configure do |c|
-  c.api_key = "your_api_key" # if omitted: ENV["CLERK_API_KEY"] - API calls will fail if unset
-  c.base_url = "https://..." # if omitted: "https://api.clerk.dev/v1/"
+  c.api_key = "your_api_key" # if omitted: ENV["CLERK_SECRET_KEY"] - API calls will fail if unset
+  c.base_url = "https://..." # if omitted: ENV["CLERK_API_BASE"] - defaults to "https://api.clerk.com/v1/"
+  c.publishable_key = "pk_(test|live)_...." # if omitted: ENV["CLERK_PUBLISHABLE_KEY"] - Handshake mechanism (check section below) will fail if unset
   c.logger = Logger.new(STDOUT) # if omitted, no logging
   c.middleware_cache_store = ActiveSupport::Cache::FileStore.new("/tmp/clerk_middleware_cache") # if omitted: no caching
   c.excluded_routes ["/foo", "/bar/*"]
@@ -159,24 +160,45 @@ single key (`errors`) containing an array of error objects.
 Read the [API documentation](https://clerk.com/docs/reference/backend-api)
 for details on expected parameters and response formats.
 
+<a name="handshake"></a>
+
+### Handshake
+
+The Client Handshake is a mechanism that is used to resolve a request’s authentication state from “unknown” to definitively signed in or signed out. Clerk’s session management architecture relies on a short-lived session JWT to validate requests, along with a long-lived session that is used to keep the session JWT fresh by interacting with the Frontend API. The long-lived session token is stored in an HttpOnly cookie associated with the Frontend API domain. If a short-lived session JWT is expired on a request to an application’s backend, the SDK doesn’t know if the session has ended, or if a new short-lived JWT needs to be issued. When an SDK gets into this state, it triggers the handshake.
+
+With the handshake, we can resolve the authentication state on the backend and ensure the request is properly handled as signed in or out, instead of being in a potentially “unknown” state. The handshake flow relies on redirects to exchange session information between FAPI and the application, ensuring the resolution of unknown authentication states minimizes performance impact and behaves consistently across different framework and language implementations.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
 `bundle exec rake` to run the tests. You can also run `bin/console` for an
 interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To
-release a new version, update the version number in `version.rb`, and then run
-`bundle exec rake release`, which will create a git tag for the version, push
-git commits and the created tag, and push the `.gem` file to
-[rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. 
+
+## Release
+
+To release a new version:
+- update the version number in `version.rb`
+- update `CHANGELOG.md` to include information about the changes
+- merge changes into main
+- run `bundle exec rake release`
+
+If gem publishing is NOT executed automatically:
+- run `gem push pkg/clerk-sdk-ruby-{version}.gem` to push the `.gem` file to [rubygems.org](https://rubygems.org)
+
+The `bundle exec rake release` command:
+- creates a git tag with the version found in `version.rb`
+- pushes the git tag
+
+## Yank release
+
+We should avoid yanking a releasing but if it's necessary execute `gem yank clerk-sdk-ruby -v {version}`
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at
-https://github.com/clerkinc/clerk-sdk-ruby.
+Bug reports and pull requests are welcome on GitHub at https://github.com/clerkinc/clerk-sdk-ruby.
 
 ## License
 
-The gem is available as open source under the terms of the
-[MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/clerk/authenticatable.rb

@@ -73,16 +73,6 @@ module Clerk
       !!clerk_verified_session_claims
     end
 
-    def clerk_user_needs_reverification?(params=StepUp::PRESETS[:strict])
-      !request.env['clerk'].is_user_reverified?(params)
-    end
-
-    def clerk_render_reverification(missing_config=nil)
-      payload = request.env['clerk'].reverification_error_payload(missing_config)
-
-      render status: 403, json: payload
-    end
-
     def clerk_sign_in_url
       ENV.fetch("CLERK_SIGN_IN_URL")
     end

data/lib/clerk/authenticate_context.rb

@@ -0,0 +1,183 @@
+require "ostruct"
+require "forwardable"
+require "base64"
+
+module Clerk
+    ##
+    # This class represents a parameter object used to contain all request and configuration
+    # information required by the middleware to resolve the current request state.
+    # link: https://refactoring.guru/introduce-parameter-object
+    class AuthenticateContext
+        extend Forwardable
+
+        ##
+        # Expose the url of the request that this parameter object was created from as a URI object.
+        attr_reader :clerk_url
+
+        ##
+        # Expose properties that does not require validations or complex logic to retrieve
+        # values by delegating them to the cookies or headers variables.
+        def_delegators :@cookies, :session_token_in_cookie, :client_uat
+        def_delegators :@headers, :session_token_in_header, :sec_fetch_dest
+
+        ##
+        # Creates a new parameter object using Rack::Request and Clerk::Config objects.
+        def initialize(request, config)
+            @clerk_url = URI.parse(request.url)
+            @config = config
+
+            @cookies = OpenStruct.new({
+                session_token_in_cookie: request.cookies[SESSION_COOKIE],
+                client_uat: request.cookies[CLIENT_UAT_COOKIE],
+                handshake_token: request.cookies[HANDSHAKE_COOKIE],
+                dev_browser: request.cookies[DEV_BROWSER_COOKIE]
+            })
+
+            @headers = OpenStruct.new({
+                session_token_in_header: request.env[AUTHORIZATION_HEADER].to_s.gsub(/bearer/i, '').strip,
+                sec_fetch_dest: request.env[SEC_FETCH_DEST_HEADER],
+                accept: request.env[ACCEPT_HEADER].to_s,
+                origin: request.env[ORIGIN_HEADER].to_s,
+                host: request.host,
+                port: request.port
+            })
+        end
+
+        ##
+        # The following properties are part of the props supported in all the AuthenticateContext
+        # objects across all of our SDKs (eg JS, Go)
+        def secret_key
+            @config.api_key.to_s
+        end
+
+        def publishable_key
+            @config.publishable_key.to_s
+        end
+
+        def domain
+            # TODO(dimkl): Add multi-domain support
+            ""
+        end
+
+        def is_satellite?
+            # TODO(dimkl): Add multi-domain support
+            false
+        end
+
+        def proxy_url
+            # TODO(dimkl): Add multi-domain support
+            ""
+        end
+
+        def handshake_token
+            @handshake_token ||= retrieve_from_query_string(@clerk_url, HANDSHAKE_COOKIE) || @cookies.handshake_token.to_s
+        end
+
+        def clerk_synced?
+            # TODO(dimkl): Add multi-domain support
+            false
+        end
+
+        def clerk_redirect_url
+             # TODO(dimkl): Add multi-domain support
+             ""
+        end
+
+        def dev_browser
+            @dev_browser ||= retrieve_from_query_string(@clerk_url, DEV_BROWSER_COOKIE) || @cookies.dev_browser.to_s
+        end
+
+        # The frontend_api returned is without protocol prefix
+        def frontend_api
+            return "" if !valid_publishable_key?(publishable_key.to_s)
+
+            @frontend_api ||= if !proxy_url.empty?
+                proxy_url
+            elsif development_instance? && !domain.empty?
+                "clerk.#{domain}"
+            else
+                # remove $ postfix
+                decode_publishable_key(publishable_key).chop
+            end
+        end
+
+        def development_instance?
+            secret_key.start_with?("sk_test_")
+        end
+
+        def production_instance?
+            secret_key.start_with?("sk_live_")
+        end
+
+        def document_request?
+            @headers.sec_fetch_dest == "document"
+        end
+
+        def accepts_html?
+            @headers.accept && @headers.accept.start_with?('text/html')
+        end
+        
+        def eligible_for_multi_domain?
+            is_satellite? && document_request? && !clerk_synced?
+        end
+
+        def active_client?
+            @cookies.client_uat.to_i > 0
+        end
+
+        def cross_origin_request?
+            # origin contains scheme+host and optionally port (omitted if 80 or 443)
+            # ref. https://www.rfc-editor.org/rfc/rfc6454#section-6.1
+            return false if @headers.origin.nil?
+      
+            # strip scheme
+            origin = @headers.origin.strip.sub(/\A(\w+:)?\/\//, '')
+            return false if origin.empty?
+      
+            # Rack's host and port helpers are reverse-proxy-aware; that
+            # is, they prefer the de-facto X-Forwarded-* headers if they're set
+            request_host = @headers.host
+            request_host << ":#{@headers.port}" if @headers.port != 80 && @headers.port != 443
+      
+            origin != request_host
+        end
+
+        def dev_browser?
+            !dev_browser.empty?
+        end
+
+        def session_token_in_header?
+            !session_token_in_header.to_s.empty?
+        end
+
+        def handshake_token?
+            !handshake_token.to_s.empty?
+        end
+
+        def session_token_in_cookie?
+            !session_token_in_cookie.to_s.empty?
+        end
+
+        private
+
+        def valid_publishable_key?(pk)
+            valid_publishable_key_prefix?(pk) && valid_publishable_key_postfix?(pk)
+        end
+
+        def valid_publishable_key_prefix?(pk)
+            pk.start_with?("pk_live_") || pk.start_with?("pk_test_")
+        end
+
+        def valid_publishable_key_postfix?(pk)
+            decode_publishable_key(pk).end_with?("$")
+        end
+
+        def decode_publishable_key(pk)
+            Base64.decode64(pk.split("_")[2].to_s)
+        end
+
+        def retrieve_from_query_string(url, key)
+            Rack::Utils.parse_query(url.query)[key]
+        end
+    end
+end

data/lib/clerk/authenticate_request.rb

@@ -0,0 +1,253 @@
+module Clerk
+    ##
+    # This class represents a service object used to determine the current request state
+    # for the current env passed based on a provided Clerk::AuthenticateContext.
+    # There is only 1 public method exposed (`resolve`) to be invoked with a env parameter.
+    class AuthenticateRequest
+        attr_reader :auth_context
+
+        ##
+        # Creates a new instance using Clerk::AuthenticateContext object.
+        def initialize(auth_context)
+            @auth_context = auth_context
+        end
+
+        ##
+        # Determines the current request state by verifying a Clerk token in headers or cookies.
+        # The possible outcomes of this method are `signed-in`, `signed-out` or `handshake` states.
+        # The return values are the same as a return value of a rack middleware `[http_status_code, headers, body]`.
+        # When used in a middleware the consumer of this service should return the return value when there is an
+        # `http_status_code` provided otherwise the should continue with the middleware chain.
+        # The headers provided in the return value is a hash of { header_key => header_value } and in the case
+        # of a `Set-Cookie` header the `header_value` used is a list of raw HTTP Set-Cookie directives.
+        def resolve(env)
+            if auth_context.session_token_in_header?
+                resolve_header_token(env)
+            else
+                resolve_cookie_token(env)
+            end
+        end
+
+        protected
+
+        def resolve_header_token(env)
+            begin
+                # malformed JWT
+                return signed_out(reason: TokenVerificationErrorReason::TOKEN_INVALID) if !sdk.decode_token(auth_context.session_token_in_header)
+
+                claims = verify_token(auth_context.session_token_in_header)
+                return signed_in(env, claims, auth_context.session_token_in_header) if claims
+            rescue JWT::DecodeError
+                # malformed JSON authorization header
+                return signed_out(reason: TokenVerificationErrorReason::TOKEN_INVALID)
+            rescue JWT::ExpiredSignature
+                return signed_out(enforce_auth: true, reason: TokenVerificationErrorReason::TOKEN_EXPIRED)
+            rescue JWT::InvalidIatError
+                return signed_out(enforce_auth: true, reason: TokenVerificationErrorReason::TOKEN_NOT_ACTIVE_YET)
+            end
+
+            # Clerk.js should refresh the token and retry
+            return signed_out(enforce_auth: true)
+        end
+
+        def resolve_cookie_token(env)
+            # in cross-origin XHRs the use of Authorization header is mandatory.
+            # TODO: add reason
+            return signed_out if auth_context.cross_origin_request?
+
+            if auth_context.handshake_token?
+                return resolve_handshake(env)
+            end
+
+            if auth_context.development_instance? && auth_context.dev_browser?
+                return handle_handshake_maybe_status(env, reason: AuthErrorReason::DEV_BROWSER_SYNC)
+            end
+
+            # TODO(dimkl): Add multi-domain support for production
+            # if auth_context.production_instance? && auth_context.eligible_for_multi_domain?
+                # return handle_handshake_maybe_status(env, reason: AuthErrorReason::SATELLITE_COOKIE_NEEDS_SYNCING)
+            # end
+
+            # TODO(dimkl): Add multi-domain support for development
+            # if auth_context.development_instance? && auth_context.eligible_for_multi_domain?
+                # trigger handshake using auth_context.sign_in_url as base redirect_url
+                # return handle_handshake_maybe_status(env, reason: AuthErrorReason::SATELLITE_COOKIE_NEEDS_SYNCING, '', headers);
+            # end
+
+            # TODO(dimkl): Add multi-domain support for development in primary
+            # if auth_context.development_instance? && !auth_context.is_satellite? && auth_context.clerk_redirect_url
+                # trigger handshake using auth_context.clerk_redirect_url as base redirect_url + mark it as clerk_synced
+                # return handle_handshake_maybe_status(env, reason: AuthErrorReason::PRIMARY_RESPONDS_TO_SYNCING, '', headers);
+            # end
+
+            if !auth_context.active_client? && !auth_context.session_token_in_cookie?
+                return signed_out(reason: AuthErrorReason::SESSION_TOKEN_AND_UAT_MISSING)
+            end
+
+            # This can eagerly run handshake since client_uat is SameSite=Strict in dev
+            if !auth_context.active_client? && auth_context.session_token_in_cookie?
+                return handle_handshake_maybe_status(env, reason: AuthErrorReason::SESSION_TOKEN_WITHOUT_CLIENT_UAT)
+            end
+
+            if auth_context.active_client? && !auth_context.session_token_in_cookie?
+                return handle_handshake_maybe_status(env, reason: AuthErrorReason::CLIENT_UAT_WITHOUT_SESSION_TOKEN)
+            end
+
+            begin
+                token = verify_token(auth_context.session_token_in_cookie)
+                return signed_out if !token
+
+                if token["iat"] < auth_context.client_uat
+                    return handle_handshake_maybe_status(env, reason: AuthErrorReason::SESSION_TOKEN_OUTDATED);
+                end
+
+                return signed_in(env, token, auth_context.session_token_in_cookie)
+            rescue JWT::ExpiredSignature
+                handshake(env, reason: TokenVerificationErrorReason::TOKEN_EXPIRED)
+            rescue JWT::InvalidIatError
+                handshake(env, reason: TokenVerificationErrorReason::TOKEN_NOT_ACTIVE_YET)
+            end
+
+            signed_out
+        end
+
+        def resolve_handshake(env)
+            headers = { 
+                "Access-Control-Allow-Origin" => "null",
+                "Access-Control-Allow-Credentials" => "true"
+            }
+            
+            session_token = ''
+
+            # Return signed-out outcome if the handshake verification fails
+            handshake_payload = verify_token(auth_context.handshake_token)
+            return signed_out(enforce_auth: true, reason: TokenVerificationErrorReason::JWK_FAILED_TO_RESOLVE) if !handshake_payload
+
+            # Retrieve the cookie directives included in handshake token payload and convert it to set-cookie headers
+            # Also retrieve the session token separately to determine the outcome of the request
+            cookies_to_set = handshake_payload[HANDSHAKE_COOKIE_DIRECTIVES_KEY] || []
+            cookies_to_set.each do |cookie|
+                headers[COOKIE_HEADER] ||= []
+                headers[COOKIE_HEADER] << cookie
+
+                if cookie.start_with?("#{SESSION_COOKIE}=")
+                    session_token = cookie.split(';')[0].split('=')[1]
+                end
+            end
+
+            # Clear handshake token from query params and set headers to redirect to the initial request url
+            if auth_context.development_instance?
+                redirect_url = auth_context.clerk_url.dup
+                remove_from_query_string(redirect_url, HANDSHAKE_COOKIE)
+                remove_from_query_string(redirect_url, HANDSHAKE_HELP_QUERY_PARAM)
+
+                headers[LOCATION_HEADER] = redirect_url.to_s
+            end
+            
+            if !session_token
+                return signed_out(reason: AuthErrorReason::SESSION_TOKEN_MISSING, headers: headers)
+            end
+
+            verify_token_with_retry(env, session_token)
+        end
+
+        def handle_handshake_maybe_status(env, **opts)
+            return signed_out if !eligible_for_handshake?
+            handshake(env, **opts)
+        end
+
+        # A outcome
+        def handshake(env, **opts)
+            redirect_headers = { LOCATION_HEADER => redirect_to_handshake }
+            [307, debug_auth_headers(**opts).merge(redirect_headers), []]
+        end
+
+        # B outcome
+        def signed_out(**opts)
+            headers = opts.delete(:headers) || {}
+            enforce_auth = opts.delete(:enforce_auth)
+
+            if enforce_auth
+                [401, debug_auth_headers(**opts).merge(headers), []]
+            else
+                [nil, headers, []]
+            end
+        end
+
+        # C outcome
+        def signed_in(env, claims, token, **headers)
+            env["clerk"] = ProxyV2.new(session_claims: claims, session_token: token)
+            [nil, headers, []]
+        end
+
+        def eligible_for_handshake?
+            auth_context.document_request? || (!auth_context.document_request? && auth_context.accepts_html?)
+        end
+
+        private
+
+        def redirect_to_handshake
+            redirect_url = auth_context.clerk_url.dup
+            remove_from_query_string(redirect_url, DEV_BROWSER_COOKIE)
+
+            handshake_url = URI.parse("https://#{auth_context.frontend_api}/v1/client/handshake")
+            handshake_url_qs = Rack::Utils.parse_query(handshake_url.query)
+            handshake_url_qs["redirect_url"] = redirect_url
+
+            if auth_context.development_instance? && auth_context.dev_browser?
+                handshake_url_qs[DEV_BROWSER_COOKIE] = auth_context.dev_browser
+            end
+
+            handshake_url.query = handshake_url_qs.to_query
+            handshake_url.to_s
+        end
+
+        def remove_from_query_string(url, key)
+            qs = Rack::Utils.parse_query(url.query)
+            qs.delete(key)
+            url.query = qs.to_query
+        end
+
+        def verify_token(token, **opts)
+            return false if token.nil? || token.strip.empty?
+        
+            begin
+                sdk.verify_token(token, **opts)
+            rescue JWT::ExpiredSignature, JWT::InvalidIatError => e
+                raise e
+            rescue JWT::DecodeError, JWT::RequiredDependencyError => e
+                false
+            end
+        end
+
+        # Verify session token and provide a 1-day leeway for development if initial verification
+        # fails for development instance due to invalid exp or iat
+        def verify_token_with_retry(env, token)
+            claims = verify_token(token)
+            return signed_in(env, claims, token) if claims
+        rescue JWT::ExpiredSignature, JWT::InvalidIatError => e
+            if auth_context.development_instance?
+                # TODO: log possible Clock skew detected
+            
+                # Retry with a generous clock skew allowance (1 day)
+                claims = verify_token(token, timeout: 86_400)
+                return signed_in(env, claims, token) if claims
+            end
+            
+            # Raise error if handshake resolution fails in production
+            raise e
+        end
+
+        def sdk
+            Clerk::SDK.new
+        end
+    
+        def debug_auth_headers(reason: nil, message: nil, status: nil)
+            {
+                AUTH_REASON_HEADER => reason,
+                AUTH_MESSAGE_HEADER => message,
+                AUTH_STATUS_HEADER => status,
+            }.compact
+        end
+    end
+end

data/lib/clerk/constants.rb

@@ -1,10 +1,50 @@
 module Clerk
-  module StepUp
-    PRESETS = {
-      strict_mfa:  { 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
+    SESSION_COOKIE = "__session".freeze
+    CLIENT_UAT_COOKIE = "__client_uat".freeze
+    
+    # Dev Browser
+    DEV_BROWSER_COOKIE = "__clerk_db_jwt".freeze
+
+    # Handshake
+    HANDSHAKE_COOKIE = "__clerk_handshake".freeze
+    HANDSHAKE_HELP_QUERY_PARAM = "__clerk_help".freeze
+    HANDSHAKE_COOKIE_DIRECTIVES_KEY = "handshake".freeze
+
+    # auth debug response headers
+    AUTH_STATUS_HEADER = "X-Clerk-Auth-Status".freeze
+    AUTH_REASON_HEADER = "X-Clerk-Auth-Reason".freeze
+    AUTH_MESSAGE_HEADER = "X-Clerk-Auth-Message".freeze
+
+    #
+    CONTENT_TYPE_HEADER = "Content-Type".freeze
+    SEC_FETCH_DEST_HEADER = "HTTP_SEC_FETCH_DEST".freeze
+    
+    # headers used in response - should be lowered case and without http prefix
+    LOCATION_HEADER = "Location".freeze
+    COOKIE_HEADER = "Set-Cookie".freeze
+
+    # clerk url related headers
+    AUTHORIZATION_HEADER = "HTTP_AUTHORIZATION".freeze
+    ACCEPT_HEADER = "HTTP_ACCEPT".freeze
+    USER_AGENT_HEADER = "HTTP_USER_AGENT".freeze
+    ORIGIN_HEADER = "HTTP_ORIGIN".freeze
+
+    module TokenVerificationErrorReason
+        TOKEN_INVALID = "token-invalid".freeze
+        TOKEN_EXPIRED = "token-expired".freeze
+        TOKEN_NOT_ACTIVE_YET = "token-not-active-yet".freeze
+        JWK_FAILED_TO_RESOLVE = "jwk-failed-to-resolve".freeze
+    end
+
+    module AuthErrorReason
+        CLIENT_UAT_WITHOUT_SESSION_TOKEN = "client-uat-but-no-session-token".freeze
+        DEV_BROWSER_SYNC = "dev-browser-sync".freeze
+        PRIMARY_RESPONDS_TO_SYNCING = "primary-responds-to-syncing".freeze
+        SATELLITE_COOKIE_NEEDS_SYNCING = "satellite-needs-syncing".freeze
+        SESSION_TOKEN_AND_UAT_MISSING = "session-token-and-uat-missing".freeze
+        SESSION_TOKEN_MISSING = "session-token-missing".freeze
+        SESSION_TOKEN_OUTDATED = "session-token-outdated".freeze
+        SESSION_TOKEN_WITHOUT_CLIENT_UAT = "session-token-but-no-client-uat".freeze
+        UNEXPECTED_ERROR = "unexpected-error".freeze
+    end
+end

data/lib/clerk/rack_middleware.rb

@@ -17,7 +17,7 @@ module Clerk
     attr_reader :session_id, :error
     def initialize(env)
       req = Rack::Request.new(env)
-      @token = req.cookies["__session"]
+      @token = req.cookies[SESSION_COOKIE]
       @session_id = req.params["_clerk_session_id"]
       @session = nil
       @user_id = nil

data/lib/clerk/rack_middleware_v2.rb

@@ -1,4 +1,6 @@
 require "clerk"
+require_relative "authenticate_context"
+require_relative "authenticate_request"
 
 module Clerk
   class ProxyV2
@@ -60,51 +62,6 @@ module Clerk
       @session_claims["org_permissions"]
     end
 
-    # Returns true if the session needs to perform step up verification
-    def is_user_reverified?(params)
-      return false if session_claims.nil?
-
-      fva           = session_claims["fva"]
-      level         = params[:level]
-      after_minutes = Integer(params[:after_minutes])
-
-      # the feature is disabled
-      return true if fva.nil?
-
-      return false if after_minutes.nil? || level.nil?
-
-      factor1_age, factor2_age = fva
-      is_valid_factor1 = factor1_age != -1 && after_minutes > factor1_age
-      is_valid_factor2 = factor2_age != -1 && after_minutes > factor2_age
-
-      case level
-      when :first_factor
-        is_valid_factor1
-      when :second_factor
-        factor2_age == -1 ? is_valid_factor1 : is_valid_factor2
-      when :multi_factor
-        factor2_age == -1 ? is_valid_factor1 : is_valid_factor1 && is_valid_factor2
-      end
-    end
-
-    def reverification_error_payload(missing_config)
-      {
-        clerk_error: {
-          type:     "forbidden",
-          reason:   "reverification-error",
-          metadata: { reverification: missing_config, }
-        }
-      }
-    end
-
-    def reverification_response(missing_config=nil)
-      [
-        403,
-        { "Content-Type" => "application/json" },
-        [reverification_error_payload(missing_config).to_json],
-      ]
-    end
-
     private
 
     def fetch_user(user_id)
@@ -164,167 +121,47 @@ module Clerk
       end
 
       env["clerk"] = Clerk::ProxyV2.new
-      header_token = req.env["HTTP_AUTHORIZATION"]
-      header_token = header_token.strip.sub(/\ABearer /, '') if header_token
-      cookie_token = req.cookies["__session"]
-      client_uat = req.cookies["__client_uat"]
-
-      ##########################################################################
-      #                                                                        #
-      #                          HEADER AUTHENTICATION                         #
-      #                                                                        #
-      ##########################################################################
-      if header_token
-        begin
-          return signed_out(env) if !sdk.decode_token(header_token) # malformed JWT
-        rescue JWT::DecodeError
-          return signed_out(env)  # malformed JSON authorization header
-        end
-
-        begin
-          token = verify_token(header_token)
-          return signed_in(env, token, header_token) if token
-        rescue JWT::ExpiredSignature, JWT::InvalidIatError
-          unknown(interstitial: false)
-        end
-
-        # Clerk.js should refresh the token and retry
-        return unknown(interstitial: false)
-      end
-
-      # in cross-origin XHRs the use of Authorization header is mandatory.
-      if cross_origin_request?(req)
-        return signed_out(env)
-      end
-
-      if development_or_staging? && !browser_request?(req)
-        # the interstitial won't work if the user agent is not a browser, so
-        # short-circuit and avoid rendering it
-        #
-        # We only limit this to dev/stg because we're not yet sure how robust
-        # this strategy is, yet. In the future, we might enable it for prod too.
-        return signed_out(env)
-      end
-
-      ##########################################################################
-      #                                                                        #
-      #                             COOKIE AUTHENTICATION                      #
-      #                                                                        #
-      ##########################################################################
-
-      if development_or_staging? && (req.referrer.nil? || cross_origin_request?(req))
-        return unknown(interstitial: true)
-      end
-
-      # Show interstitial when there is no client_uat and cookie token
-      if client_uat.to_s.empty? && cookie_token.to_s.empty?
-        return unknown(interstitial: true)
-      end
 
-      if client_uat == "0"
-        return signed_out(env)
-      end
+      auth_context = AuthenticateContext.new(req, Clerk.configuration)
+      auth_request = AuthenticateRequest.new(auth_context)
 
-      # Show interstitial when there is client_uat is incompatible with cookie token
-      has_cookie_token_without_client = client_uat.to_s.empty? && cookie_token
-      has_client_without_cookie_token = client_uat.to_s != "" && cookie_token.to_s.empty?
-      return unknown(interstitial: true) if has_cookie_token_without_client || has_client_without_cookie_token
+      status, auth_request_headers, body = auth_request.resolve(env)
+      return [status, auth_request_headers, body] if status
+      
+      status, headers, body = @app.call(env)
 
-      begin
-        token = verify_token(cookie_token)
-        return signed_out(env) if !token
+      if !auth_request_headers.empty?
+        # Remove them to avoid overriding existing cookies set in headers by other middlewares
+        auth_request_cookies = auth_request_headers.delete(COOKIE_HEADER)
+        # merge non-cookie related headers into response headers
+        headers.merge!(auth_request_headers)
 
-        if token["iat"] && client_uat && Integer(client_uat) <= token["iat"]
-          return signed_in(env, token, cookie_token)
-        end
-      rescue JWT::ExpiredSignature, JWT::InvalidIatError
-        unknown(interstitial: true)
+        set_cookie_headers!(headers, auth_request_cookies) if auth_request_cookies
       end
 
-      unknown(interstitial: true)
+      [status, headers, body]
     end
 
     private
 
-    # Outcome A
-    def signed_in(env, claims, token)
-      env["clerk"] = ProxyV2.new(session_claims: claims, session_token: token)
-
-      @app.call(env)
-    end
-
-    # Outcome B
-    def signed_out(env)
-      @app.call(env)
-    end
-
-    # Outcome C
-    def unknown(interstitial: false, **opts)
-      return [401, interstitial_headers(**opts), []] if !interstitial
-
-      # Load Clerk.js to update the __session and __client_uat cookies.
-      [401, interstitial_headers(**opts), [sdk.interstitial]]
-    end
-
-    def development_or_staging?
-      Clerk.configuration.api_key &&
-      (Clerk.configuration.api_key.start_with?("test_") ||
-        Clerk.configuration.api_key.start_with?("sk_test_"))
-    end
-
-    def production?
-      Clerk.configuration.api_key &&
-      (Clerk.configuration.api_key.start_with?("live_") ||
-        Clerk.configuration.api_key.start_with?("sk_live_"))
-    end
-
-    def cross_origin_request?(req)
-      # origin contains scheme+host and optionally port (omitted if 80 or 443)
-      # ref. https://www.rfc-editor.org/rfc/rfc6454#section-6.1
-      origin = req.env["HTTP_ORIGIN"]
-      return false if origin.nil?
-
-      # strip scheme
-      origin = origin.strip.sub(/\A(\w+:)?\/\//, '')
-      return false if origin.empty?
-
-      # Rack's host and port helpers are reverse-proxy-aware; that
-      # is, they prefer the de-facto X-Forwarded-* headers if they're set
-      request_host = req.host
-      request_host << ":#{req.port}" if req.port != 80 && req.port != 443
-
-      origin != request_host
-    end
-
-    def browser_request?(req)
-      user_agent = req.env["HTTP_USER_AGENT"]
-
-      !user_agent.nil? && user_agent.starts_with?("Mozilla/")
-    end
-
-    def verify_token(token)
-      return false if token.nil? || token.strip.empty?
-
-      begin
-        sdk.verify_token(token)
-      rescue JWT::ExpiredSignature, JWT::InvalidIatError => e
-        raise e
-      rescue JWT::DecodeError, JWT::RequiredDependencyError => e
-        false
+    def set_cookie_headers!(headers, cookie_headers)
+      cookie_headers.each do |cookie_header|
+        cookie_key = cookie_header.split(';')[0].split('=')[0]
+        cookie =  Rack::Utils.parse_cookies_header(cookie_header)
+        cookie_params = convert_http_cookie_to_cookie_setter_params(cookie, cookie_key)
+        Rack::Utils.set_cookie_header!(headers, cookie_key, cookie_params)
       end
     end
 
-    def sdk
-      Clerk::SDK.new
-    end
-
-    def interstitial_headers(reason: nil, message: nil, status: nil)
-      {
-        "Content-Type" => "text/html",
-        "X-Clerk-Auth-Reason" => reason,
-        "X-Clerk-Auth-Message" => message,
-        "X-Clerk-Auth-Status" => status,
-      }.compact
+    def convert_http_cookie_to_cookie_setter_params(cookie, cookie_key)
+      # convert cookie to to match cookie setter method params (lowercase symbolized keys with `:value` key)
+      cookie_params = cookie.transform_keys { |k| k.downcase.to_sym }
+      # drop the current cookie name key to avoid polluting the expected cookie params
+      cookie_params[:value] = cookie.delete(cookie_key)
+      # fix issue with cookie expiration expected to be Date type
+      cookie_params[:expires] = Date.parse(cookie_params[:expires]) if cookie_params[:expires]
+      
+      cookie_params
     end
   end
 end

data/lib/clerk/sdk.rb

@@ -96,7 +96,7 @@ module Clerk
                    end
                  end
 
-      body = if response["Content-Type"] == "application/json"
+      body = if response[CONTENT_TYPE_HEADER] == "application/json"
                JSON.parse(response.body)
              else
                response.body
@@ -155,10 +155,6 @@ module Clerk
       Resources::JWKS.new(self)
     end
 
-    def interstitial(refresh=false)
-      request(:get, "internal/interstitial")
-    end
-
     # Returns the decoded JWT payload without verifying if the signature is
     # valid.
     #
@@ -185,7 +181,7 @@ module Clerk
         { keys: SDK.jwks_cache.fetch(self, kid_not_found: (options[:invalidate] || options[:kid_not_found]), force_refresh: force_refresh_jwks) }
       end
 
-      JWT.decode(token, nil, true, algorithms: algorithms, jwks: jwk_loader).first
+      JWT.decode(token, nil, true, algorithms: algorithms, exp_leeway: timeout, jwks: jwk_loader).first
     end
   end
 end

data/lib/clerk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clerk
-  VERSION = "3.3.0"
+  VERSION = "4.0.0.beta2"
 end

data/lib/clerk.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "clerk/version"
-require_relative "clerk/sdk"
 require_relative "clerk/constants"
+require_relative "clerk/sdk"
 
 module Clerk
   class << self
@@ -17,7 +17,7 @@ module Clerk
 
   class Config
     PRODUCTION_BASE_URL = "https://api.clerk.dev/v1/".freeze
-    attr_accessor :api_key, :base_url, :logger, :middleware_cache_store
+    attr_accessor :api_key, :base_url, :publishable_key, :logger, :middleware_cache_store
 
     # An array of route paths on which the middleware will not execute.
     #
@@ -51,6 +51,8 @@ module Clerk
         @api_key = secret_key
       end
 
+      @publishable_key = ENV.fetch("CLERK_PUBLISHABLE_KEY")
+
       @excluded_routes = []
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: clerk-sdk-ruby
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 4.0.0.beta2
 platform: ruby
 authors:
 - Clerk
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-22 00:00:00.000000000 Z
+date: 2024-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -94,6 +94,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/main.yml"
+- ".github/workflows/semgrep.yml"
 - ".gitignore"
 - CHANGELOG.md
 - CODEOWNERS
@@ -109,6 +110,8 @@ files:
 - docs/clerk-logo-light.png
 - lib/clerk.rb
 - lib/clerk/authenticatable.rb
+- lib/clerk/authenticate_context.rb
+- lib/clerk/authenticate_request.rb
 - lib/clerk/constants.rb
 - lib/clerk/errors.rb
 - lib/clerk/jwks_cache.rb
@@ -149,11 +152,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
 summary: Clerk SDK for Ruby.