clerk-sdk-ruby 8.0.0 → 8.0.1

data/lib/clerk/sessions.rb

@@ -636,6 +636,152 @@ module Clerk
 
 
     
+    def get_reverification(session_id:, reverification_id:, retries: nil, timeout_ms: nil, http_headers: nil)
+      # get_reverification - Retrieve a reverification
+      # Retrieve a reverification scoped to a session. A resource server can use this to validate a reverification id it received from its client: confirm it is real, scoped to the expected session, completed, and how fresh each factor is. Single-use / replay detection is the caller's responsibility (the id is stable, so the caller dedups consumed ids).
+      #
+      request = Models::Operations::GetReverificationRequest.new(
+        session_id: session_id,
+        reverification_id: reverification_id
+      )
+      url, params = @sdk_configuration.get_server_details
+      base_url = Utils.template_url(url, params)
+      url = Utils.generate_url(
+        Models::Operations::GetReverificationRequest,
+        base_url,
+        '/sessions/{session_id}/reverifications/{reverification_id}',
+        request
+      )
+      headers = {}
+      
+      headers['Accept'] = 'application/json'
+      headers['user-agent'] = @sdk_configuration.user_agent
+      retries ||= @sdk_configuration.retry_config
+      retries ||= Utils::RetryConfig.new(
+        backoff: Utils::BackoffStrategy.new(
+          exponent: 1.5,
+          initial_interval: 500,
+          max_elapsed_time: 3_600_000,
+          max_interval: 60_000
+        ),
+        retry_connection_errors: true,
+        strategy: 'backoff'
+      )
+      retry_options = retries.to_faraday_retry_options(initial_time: Time.now)
+      retry_options[:retry_statuses] = [500, 501, 502, 503, 504, 505]
+
+      security = @sdk_configuration.security_source&.call
+
+      timeout = (timeout_ms.to_f / 1000) unless timeout_ms.nil?
+      timeout ||= @sdk_configuration.timeout
+
+
+      connection = @sdk_configuration.client.dup
+      connection.use Utils::RetryMiddleware, retry_options
+
+      hook_ctx = SDKHooks::HookContext.new(
+        config: @sdk_configuration,
+        base_url: base_url,
+        oauth2_scopes: nil,
+        operation_id: 'GetReverification',
+        security_source: @sdk_configuration.security_source
+      )
+
+      error = nil
+      http_response = nil
+      
+
+      begin
+        http_response = connection.get(url) do |req|
+          req.headers.merge!(headers)
+          req.options.timeout = timeout unless timeout.nil?
+          Utils.configure_request_security(req, security)
+          http_headers&.each do |key, value|
+            req.headers[key.to_s] = value
+          end
+
+          @sdk_configuration.hooks.before_request(
+            hook_ctx: SDKHooks::BeforeRequestHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            request: req
+          )
+        end
+      rescue StandardError => e
+        error = e
+      ensure
+        if http_response.nil? || Utils.error_status?(http_response.status)
+          http_response = @sdk_configuration.hooks.after_error(
+            error: error,
+            hook_ctx: SDKHooks::AfterErrorHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+        else
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+        end
+
+        if http_response.nil?
+          raise error if !error.nil?
+          raise 'no response'
+        end
+      end
+
+      content_type = http_response.headers.fetch('Content-Type', 'application/octet-stream')
+      if Utils.match_status_code(http_response.status, ['200'])
+        if Utils.match_content_type(content_type, 'application/json')
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+          response_data = http_response.env.response_body
+          obj = Crystalline.unmarshal_json(JSON.parse(response_data), Models::Components::Reverification)
+          response = Models::Operations::GetReverificationResponse.new(
+            status_code: http_response.status,
+            content_type: content_type,
+            raw_response: http_response,
+            reverification: obj
+          )
+
+          return response
+        else
+          raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown content type received'
+        end
+      elsif Utils.match_status_code(http_response.status, ['400', '401', '404'])
+        if Utils.match_content_type(content_type, 'application/json')
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+          response_data = http_response.env.response_body
+          obj = Crystalline.unmarshal_json(JSON.parse(response_data), Models::Errors::ClerkErrors)
+          obj.raw_response = http_response
+          raise obj
+        else
+          raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown content type received'
+        end
+      elsif Utils.match_status_code(http_response.status, ['4XX'])
+        raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'API error occurred'
+      elsif Utils.match_status_code(http_response.status, ['5XX'])
+        raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'API error occurred'
+      else
+        raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown status code received'
+
+      end
+    end
+
+
+    
     def revoke(session_id:, retries: nil, timeout_ms: nil, http_headers: nil)
       # revoke - Revoke a session
       # Sets the status of a session as "revoked", which is an unauthenticated state.

data/lib/clerk/users.rb

@@ -45,6 +45,11 @@ module Clerk
       # list - List all users
       # Returns a list of all users.
       # The users are returned sorted by creation date, with the newest users appearing first.
+      #
+      # To walk more than a few pages, paginate with `starting_after` rather than `offset`.
+      # A cursor page costs the same no matter how far into the list it sits, while a large `offset`
+      # has to walk and discard every row before it, so it gets progressively slower and eventually
+      # times out. Cursor pagination requires the `created_at` ordering, which is the default.
       url, params = @sdk_configuration.get_server_details
       base_url = Utils.template_url(url, params)
       url = "#{base_url}/users"
@@ -4171,7 +4176,7 @@ module Clerk
     
     def delete_passkey(user_id:, passkey_identification_id:, retries: nil, timeout_ms: nil, http_headers: nil)
       # delete_passkey - Delete a user passkey
-      # Delete the passkey identification for a given user and notify them through email.
+      # Delete the passkey identification for a given user. The user is notified through email or SMS unless the passkey registration was never completed.
       request = Models::Operations::UserPasskeyDeleteRequest.new(
         user_id: user_id,
         passkey_identification_id: passkey_identification_id
@@ -4332,6 +4337,8 @@ module Clerk
     def list_trusted_devices(user_id:, retries: nil, timeout_ms: nil, http_headers: nil)
       # list_trusted_devices - List a user's trusted devices
       # Returns the active trusted devices enrolled by the user.
+      #
+      # @deprecated method: This will be removed in a future release, please migrate away from it as soon as possible.
       request = Models::Operations::ListUserTrustedDevicesRequest.new(
         user_id: user_id
       )
@@ -4491,6 +4498,8 @@ module Clerk
     def revoke_trusted_device(user_id:, trusted_device_id:, retries: nil, timeout_ms: nil, http_headers: nil)
       # revoke_trusted_device - Revoke a user's trusted device
       # Revokes an active trusted device enrolled by the user.
+      #
+      # @deprecated method: This will be removed in a future release, please migrate away from it as soon as possible.
       request = Models::Operations::RevokeUserTrustedDeviceRequest.new(
         user_id: user_id,
         trusted_device_id: trusted_device_id
@@ -4648,6 +4657,325 @@ module Clerk
 
 
     
+    def list_biometric_credentials(user_id:, retries: nil, timeout_ms: nil, http_headers: nil)
+      # list_biometric_credentials - List a user's biometric credentials
+      # Returns the active biometric credentials enrolled by the user.
+      request = Models::Operations::ListUserBiometricCredentialsRequest.new(
+        user_id: user_id
+      )
+      url, params = @sdk_configuration.get_server_details
+      base_url = Utils.template_url(url, params)
+      url = Utils.generate_url(
+        Models::Operations::ListUserBiometricCredentialsRequest,
+        base_url,
+        '/users/{user_id}/biometric_credentials',
+        request
+      )
+      headers = {}
+      
+      headers['Accept'] = 'application/json'
+      headers['user-agent'] = @sdk_configuration.user_agent
+      retries ||= @sdk_configuration.retry_config
+      retries ||= Utils::RetryConfig.new(
+        backoff: Utils::BackoffStrategy.new(
+          exponent: 1.5,
+          initial_interval: 500,
+          max_elapsed_time: 3_600_000,
+          max_interval: 60_000
+        ),
+        retry_connection_errors: true,
+        strategy: 'backoff'
+      )
+      retry_options = retries.to_faraday_retry_options(initial_time: Time.now)
+      retry_options[:retry_statuses] = [500, 501, 502, 503, 504, 505]
+
+      security = @sdk_configuration.security_source&.call
+
+      timeout = (timeout_ms.to_f / 1000) unless timeout_ms.nil?
+      timeout ||= @sdk_configuration.timeout
+
+
+      connection = @sdk_configuration.client.dup
+      connection.use Utils::RetryMiddleware, retry_options
+
+      hook_ctx = SDKHooks::HookContext.new(
+        config: @sdk_configuration,
+        base_url: base_url,
+        oauth2_scopes: nil,
+        operation_id: 'ListUserBiometricCredentials',
+        security_source: @sdk_configuration.security_source
+      )
+
+      error = nil
+      http_response = nil
+      
+
+      begin
+        http_response = connection.get(url) do |req|
+          req.headers.merge!(headers)
+          req.options.timeout = timeout unless timeout.nil?
+          Utils.configure_request_security(req, security)
+          http_headers&.each do |key, value|
+            req.headers[key.to_s] = value
+          end
+
+          @sdk_configuration.hooks.before_request(
+            hook_ctx: SDKHooks::BeforeRequestHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            request: req
+          )
+        end
+      rescue StandardError => e
+        error = e
+      ensure
+        if http_response.nil? || Utils.error_status?(http_response.status)
+          http_response = @sdk_configuration.hooks.after_error(
+            error: error,
+            hook_ctx: SDKHooks::AfterErrorHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+        else
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+        end
+
+        if http_response.nil?
+          raise error if !error.nil?
+          raise 'no response'
+        end
+      end
+
+      content_type = http_response.headers.fetch('Content-Type', 'application/octet-stream')
+      if Utils.match_status_code(http_response.status, ['200'])
+        if Utils.match_content_type(content_type, 'application/json')
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+          response_data = http_response.env.response_body
+          obj = Crystalline.unmarshal_json(JSON.parse(response_data), Models::Components::BiometricCredentialList)
+          response = Models::Operations::ListUserBiometricCredentialsResponse.new(
+            status_code: http_response.status,
+            content_type: content_type,
+            raw_response: http_response,
+            biometric_credential_list: obj
+          )
+
+          return response
+        else
+          raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown content type received'
+        end
+      elsif Utils.match_status_code(http_response.status, ['403', '404'])
+        if Utils.match_content_type(content_type, 'application/json')
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+          response_data = http_response.env.response_body
+          obj = Crystalline.unmarshal_json(JSON.parse(response_data), Models::Errors::ClerkErrors)
+          obj.raw_response = http_response
+          raise obj
+        else
+          raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown content type received'
+        end
+      elsif Utils.match_status_code(http_response.status, ['500'])
+        if Utils.match_content_type(content_type, 'application/json')
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+          response_data = http_response.env.response_body
+          obj = Crystalline.unmarshal_json(JSON.parse(response_data), Models::Errors::ClerkErrors)
+          obj.raw_response = http_response
+          raise obj
+        else
+          raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown content type received'
+        end
+      elsif Utils.match_status_code(http_response.status, ['4XX'])
+        raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'API error occurred'
+      elsif Utils.match_status_code(http_response.status, ['5XX'])
+        raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'API error occurred'
+      else
+        raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown status code received'
+
+      end
+    end
+
+
+    
+    def revoke_biometric_credential(user_id:, biometric_credential_id:, retries: nil, timeout_ms: nil, http_headers: nil)
+      # revoke_biometric_credential - Revoke a user's biometric credential
+      # Revokes an active biometric credential enrolled by the user.
+      request = Models::Operations::RevokeUserBiometricCredentialRequest.new(
+        user_id: user_id,
+        biometric_credential_id: biometric_credential_id
+      )
+      url, params = @sdk_configuration.get_server_details
+      base_url = Utils.template_url(url, params)
+      url = Utils.generate_url(
+        Models::Operations::RevokeUserBiometricCredentialRequest,
+        base_url,
+        '/users/{user_id}/biometric_credentials/{biometric_credential_id}',
+        request
+      )
+      headers = {}
+      
+      headers['Accept'] = 'application/json'
+      headers['user-agent'] = @sdk_configuration.user_agent
+      retries ||= @sdk_configuration.retry_config
+      retries ||= Utils::RetryConfig.new(
+        backoff: Utils::BackoffStrategy.new(
+          exponent: 1.5,
+          initial_interval: 500,
+          max_elapsed_time: 3_600_000,
+          max_interval: 60_000
+        ),
+        retry_connection_errors: true,
+        strategy: 'backoff'
+      )
+      retry_options = retries.to_faraday_retry_options(initial_time: Time.now)
+      retry_options[:retry_statuses] = [500, 501, 502, 503, 504, 505]
+
+      security = @sdk_configuration.security_source&.call
+
+      timeout = (timeout_ms.to_f / 1000) unless timeout_ms.nil?
+      timeout ||= @sdk_configuration.timeout
+
+
+      connection = @sdk_configuration.client.dup
+      connection.use Utils::RetryMiddleware, retry_options
+
+      hook_ctx = SDKHooks::HookContext.new(
+        config: @sdk_configuration,
+        base_url: base_url,
+        oauth2_scopes: nil,
+        operation_id: 'RevokeUserBiometricCredential',
+        security_source: @sdk_configuration.security_source
+      )
+
+      error = nil
+      http_response = nil
+      
+
+      begin
+        http_response = connection.delete(url) do |req|
+          req.headers.merge!(headers)
+          req.options.timeout = timeout unless timeout.nil?
+          Utils.configure_request_security(req, security)
+          http_headers&.each do |key, value|
+            req.headers[key.to_s] = value
+          end
+
+          @sdk_configuration.hooks.before_request(
+            hook_ctx: SDKHooks::BeforeRequestHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            request: req
+          )
+        end
+      rescue StandardError => e
+        error = e
+      ensure
+        if http_response.nil? || Utils.error_status?(http_response.status)
+          http_response = @sdk_configuration.hooks.after_error(
+            error: error,
+            hook_ctx: SDKHooks::AfterErrorHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+        else
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+        end
+
+        if http_response.nil?
+          raise error if !error.nil?
+          raise 'no response'
+        end
+      end
+
+      content_type = http_response.headers.fetch('Content-Type', 'application/octet-stream')
+      if Utils.match_status_code(http_response.status, ['200'])
+        if Utils.match_content_type(content_type, 'application/json')
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+          response_data = http_response.env.response_body
+          obj = Crystalline.unmarshal_json(JSON.parse(response_data), Models::Components::BiometricCredential)
+          response = Models::Operations::RevokeUserBiometricCredentialResponse.new(
+            status_code: http_response.status,
+            content_type: content_type,
+            raw_response: http_response,
+            biometric_credential: obj
+          )
+
+          return response
+        else
+          raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown content type received'
+        end
+      elsif Utils.match_status_code(http_response.status, ['403', '404'])
+        if Utils.match_content_type(content_type, 'application/json')
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+          response_data = http_response.env.response_body
+          obj = Crystalline.unmarshal_json(JSON.parse(response_data), Models::Errors::ClerkErrors)
+          obj.raw_response = http_response
+          raise obj
+        else
+          raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown content type received'
+        end
+      elsif Utils.match_status_code(http_response.status, ['500'])
+        if Utils.match_content_type(content_type, 'application/json')
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+          response_data = http_response.env.response_body
+          obj = Crystalline.unmarshal_json(JSON.parse(response_data), Models::Errors::ClerkErrors)
+          obj.raw_response = http_response
+          raise obj
+        else
+          raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown content type received'
+        end
+      elsif Utils.match_status_code(http_response.status, ['4XX'])
+        raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'API error occurred'
+      elsif Utils.match_status_code(http_response.status, ['5XX'])
+        raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'API error occurred'
+      else
+        raise ::Clerk::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown status code received'
+
+      end
+    end
+
+
+    
     def delete_web3_wallet(user_id:, web3_wallet_identification_id:, retries: nil, timeout_ms: nil, http_headers: nil)
       # delete_web3_wallet - Delete a user web3 wallet
       # Delete the web3 wallet identification for a given user.

data/lib/clerk/utils/utils.rb

@@ -78,11 +78,15 @@ module Clerk
 
     
     def self.match_content_type(content_type, pattern)
-      return true if content_type == pattern || ['*', '*/*'].include?(pattern)
+      return true if ['*', '*/*'].include?(pattern)
+
+      # Media types are case-insensitive (RFC 9110 section 8.3.1).
+      pattern = pattern.strip.downcase
+      return true if content_type.strip.downcase == pattern
 
       pieces = content_type.split(';')
       pieces.each do |piece|
-        return true if pattern == piece.strip
+        return true if pattern == piece.strip.downcase
       end
 
       false

data/lib/clerk_sdk_ruby.rb

@@ -44,6 +44,7 @@ module Clerk
   autoload :OrganizationPermissions, 'clerk/organizationpermissions'
   autoload :RoleSets, 'clerk/rolesets'
   autoload :ScimDirectories, 'clerk/scimdirectories'
+  autoload :Directories, 'clerk/directories'
   autoload :AdminPortalLinkTokens, 'clerk/admin_portal_link_tokens'
   autoload :APIKeys, 'clerk/api_keys'
   autoload :M2m, 'clerk/m2m'

data/test/clerk/org_permissions_v2_test.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require_relative '../../lib/clerk'
+
+module Clerk
+  # Coverage for Clerk::SDK#compute_org_permissions_from_v2_token, which decodes
+  # the `fea` / `o.per` / `o.fpm` triple of a v2 session token into
+  # `org:<feature>:<action>` strings.
+  class OrgPermissionsV2Test < Minitest::Test
+    ACTIONS = (0...64).map { |n| "act_#{n}" }.freeze
+
+    def sdk
+      @sdk ||= Clerk::SDK.new(secret_key: 'sk_test_not_used')
+    end
+
+    def permissions_for(fea:, per:, fpm:)
+      claims = {'fea' => fea, 'o' => {'per' => per, 'fpm' => fpm}}
+      sdk.send(:compute_org_permissions_from_v2_token, claims)
+    end
+
+    # --- happy path (regression guard) ----------------------------------------
+
+    def test_small_masks_decode_with_bit_zero_least_significant
+      result = permissions_for(
+        fea: 'o:leads,o:whatsapp',
+        per: 'chat_read,chat_send,connect,view_history',
+        fpm: '3,10'
+      )
+
+      assert_equal ['org:leads:chat_read', 'org:leads:chat_send',
+                    'org:whatsapp:chat_send', 'org:whatsapp:view_history'], result
+    end
+
+    def test_zero_mask_grants_nothing
+      assert_empty permissions_for(fea: 'o:leads', per: 'chat_read,chat_send', fpm: '0')
+    end
+
+    def test_non_org_scoped_features_are_skipped
+      result = permissions_for(
+        fea: 'u:billing,o:leads',
+        per: 'chat_read,chat_send',
+        fpm: '3,1'
+      )
+
+      assert_equal ['org:leads:chat_read'], result
+    end
+
+    # --- wide masks ------------------------------------------------------------
+
+    def test_mask_with_bit_62_set
+      result = permissions_for(fea: 'o:leads', per: ACTIONS.join(','), fpm: (2**62).to_s)
+
+      assert_equal ['org:leads:act_62'], result
+    end
+
+    def test_positive_bignum_mask_with_bit_63_set
+      # 2**63 + 1 -- above the signed 64-bit range, but Ruby Integers are
+      # arbitrary-precision so this must still decode to indices 0 and 63.
+      result = permissions_for(fea: 'o:leads', per: ACTIONS.join(','), fpm: '9223372036854775809')
+
+      assert_equal ['org:leads:act_0', 'org:leads:act_63'], result
+    end
+
+    # --- the security regression: negative masks must fail closed --------------
+
+    def test_negative_mask_grants_nothing
+      # A signed 64-bit overflow on the producing side yields a negative mask.
+      # `(-9223372036854775807).to_s(2)` is "-111...1", which -- walked character
+      # by character -- would otherwise grant 63 permissions.
+      result = permissions_for(fea: 'o:leads', per: ACTIONS.join(','), fpm: '-9223372036854775807')
+
+      assert_empty result
+    end
+
+    def test_negative_mask_does_not_affect_other_features
+      result = permissions_for(
+        fea: 'o:leads,o:whatsapp',
+        per: ACTIONS.join(','),
+        fpm: '3,-9223372036854775807'
+      )
+
+      assert_equal ['org:leads:act_0', 'org:leads:act_1'], result
+    end
+
+    def test_non_numeric_masks_grant_nothing
+      ['abc', '1e3', '0x10', ' 3', '3 ', '1.5', '+3', ''].each do |mask|
+        assert_empty permissions_for(fea: 'o:leads', per: ACTIONS.join(','), fpm: mask),
+                     "expected mask #{mask.inspect} to grant nothing"
+      end
+    end
+
+    # --- malformed claims must not raise ---------------------------------------
+
+    def test_more_mappings_than_features_does_not_raise
+      result = permissions_for(fea: 'o:leads', per: 'chat_read,chat_send', fpm: '1,3,7')
+
+      assert_equal ['org:leads:chat_read'], result
+    end
+
+    def test_feature_without_a_scope_separator_does_not_raise
+      result = permissions_for(fea: 'leads,o:whatsapp', per: 'chat_read', fpm: '1,1')
+
+      assert_equal ['org:whatsapp:chat_read'], result
+    end
+
+    def test_missing_claims_do_not_raise
+      assert_empty permissions_for(fea: nil, per: nil, fpm: nil)
+      assert_empty permissions_for(fea: 'o:leads', per: nil, fpm: '3')
+      assert_empty permissions_for(fea: nil, per: 'chat_read', fpm: '3')
+    end
+
+    # --- masks wider than the permission vocabulary ----------------------------
+
+    def test_mask_wider_than_permission_list_does_not_emit_empty_permissions
+      # 0b1111 against a two-action vocabulary: only the first two bits map.
+      result = permissions_for(fea: 'o:leads', per: 'chat_read,chat_send', fpm: '15')
+
+      assert_equal ['org:leads:chat_read', 'org:leads:chat_send'], result
+      refute(result.any? { |permission| permission.end_with?(':') },
+             "expected no permissions with an empty action name, got #{result.inspect}")
+    end
+
+    def test_high_bit_beyond_permission_list_is_ignored
+      result = permissions_for(fea: 'o:leads', per: 'chat_read', fpm: (2**63 | 1).to_s)
+
+      assert_equal ['org:leads:chat_read'], result
+    end
+  end
+end