booqable 1.1.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13ee5f72ca221d2613d8691dd8c04fa189a38fbed8276b60878d2cce4c7f4f23
-  data.tar.gz: 54028d30a657d3651ad0d49fab923efba00e09fa9f0d2e36906e8cf068975abd
+  metadata.gz: eb7d9650b7c441ded7b819566722c9dd860d83c28338407897c3e359367954a3
+  data.tar.gz: 6fd5b29991f14b4503b244fcb05db3613c7d87baf215904274066081a2d71107
 SHA512:
-  metadata.gz: 51cb9ed5b66956cee3e429c51057e12884574fe3c8b3b907d6998caa1b037b5ca861c929ea7b26e8364369bf424b3686feff274149fa6a169da09d8048118390
-  data.tar.gz: d6389d7f934088b0447dba290054456f10380578f5b38622275d6e846c99872a5060c21b192b8524aa7d867fe1b58917c9ad03eebfacef716b83eca28dab8549
+  metadata.gz: 38b96b39b3d88bfe1209a102f15117f2f7292d38f0ffebb5d2d0e80cbf93d8cb5622462b9bfef7a3cc784a52f25c4bdcad97333de5401a7d8cc2ca0abcbaae15
+  data.tar.gz: f53f2f5c9347c8f3ea266abfc8882b42e8e1239c9df104cb46277a2467ad22710fc68a7417808eb32ac37d1ee0a3891a9e704e558101dbb30962b54da2d1b917

data/CHANGELOG.md

@@ -1,4 +1,17 @@
-## [Unreleased]
+## [1.2.1] - 2026-06-10
+
+- Require `oauth2 >= 2.0.22` to address GHSA-pp92-crg2-gfv9, where a
+  protocol-relative redirect `Location` could override the request authority and
+  leak the bearer `Authorization` header to an attacker-controlled host.
+
+
+## [1.2.0] - 2026-05-27
+
+- Add optional `around_refresh_token` configuration. When provided, the OAuth
+  middleware yields the read + expiry-check + refresh sequence to the callable
+  so host applications can serialize concurrent token refreshes (e.g. with a
+  database transaction and advisory lock). The gem keeps no lock dependency.
+
 
 ## [1.1.0] - 2026-03-11
 

data/README.md

@@ -105,6 +105,30 @@ client = Booqable::Client.new(
 client.authenticate_with_code(params[:code])
 ```
 
+#### Serializing concurrent token refreshes
+
+When multiple processes share the same OAuth token (e.g. the same installation
+serving concurrent requests), pass an `around_refresh_token` callable to
+serialize the read + expiry-check + refresh sequence. The middleware yields
+to the callable once per request; the host application decides how to lock.
+
+```ruby
+Booqable::Client.new(
+  # ...other oauth options...
+  around_refresh_token: ->(&block) {
+    AppInstallation.transaction do
+      installation.with_advisory_lock!("app_installation:#{installation.id}", transaction: true) do
+        installation.reload
+        block.call
+      end
+    end
+  }
+)
+```
+
+The gem itself has no advisory-lock dependency — `around_refresh_token` is
+just a callable that takes a block.
+
 ### Single-Use Token Authentication
 
 For server-to-server communication requiring enhanced security:

data/lib/booqable/auth.rb

@@ -57,7 +57,8 @@ module Booqable
         api_endpoint: api_endpoint,
         redirect_uri: redirect_uri,
         read_token: read_token,
-        write_token: write_token
+        write_token: write_token,
+        around_refresh_token: around_refresh_token
       } if oauth_authenticated?
 
       builder.use Booqable::Middleware::Auth::ApiKey, {

data/lib/booqable/client.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "did_you_mean"
+
 module Booqable
   # Client for the Booqable API
   #
@@ -40,11 +42,22 @@ module Booqable
       access_token
     ]
 
+    # Accepted aliases for configuration options, mapping the alias to its
+    # canonical {Booqable::Configurable} key.
+    OPTION_ALIASES = {
+      skip_retries: :no_retries
+    }.freeze
+
     # Initialize a new Client
     #
     # @param options [Hash] Configuration options for the client
     # @see Booqable::Configurable For a complete list of supported configuration options
     def initialize(options = {})
+      options = normalize_aliases(options)
+
+      unknown_keys = options.keys.map(&:to_sym) - Booqable::Configurable.keys
+      raise ArgumentError, unknown_options_message(unknown_keys) unless unknown_keys.empty?
+
       # Use options passed in, but fall back to module defaults
       #
       # This may look like a `.keys.each` which should be replaced with `#each_key`, but
@@ -94,5 +107,34 @@ module Booqable
 
       inspected
     end
+
+    private
+
+    # Rewrite any aliased option keys to their canonical configuration key.
+    #
+    # @param options [Hash] options as passed to {#initialize}
+    # @return [Hash] options with aliases replaced by their canonical keys
+    def normalize_aliases(options)
+      options.to_h do |key, value|
+        [ OPTION_ALIASES.fetch(key.to_sym, key), value ]
+      end
+    end
+
+    # Build an error message for unknown configuration options, suggesting
+    # similarly-named valid options via did_you_mean when one is close enough.
+    #
+    # @param unknown_keys [Array<Symbol>] options that aren't valid config keys
+    # @return [String]
+    def unknown_options_message(unknown_keys)
+      dictionary = Booqable::Configurable.keys + OPTION_ALIASES.keys
+      spell_checker = DidYouMean::SpellChecker.new(dictionary: dictionary)
+
+      message = "unknown configuration option(s): #{unknown_keys.join(", ")}"
+
+      suggestions = unknown_keys.flat_map { |key| spell_checker.correct(key) }.uniq
+      message += ". Did you mean: #{suggestions.join(", ")}?" unless suggestions.empty?
+
+      message
+    end
   end
 end

data/lib/booqable/configurable.rb

@@ -48,6 +48,7 @@ module Booqable
                   :proxy,
                   :read_token,
                   :redirect_uri,
+                  :around_refresh_token,
                   :single_use_token,
                   :single_use_token_algorithm,
                   :single_use_token_company_id,
@@ -81,6 +82,7 @@ module Booqable
           proxy
           read_token
           redirect_uri
+          around_refresh_token
           single_use_token
           single_use_token_algorithm
           single_use_token_company_id

data/lib/booqable/default.rb

@@ -151,6 +151,17 @@ module Booqable
         Proc.new { }
       end
 
+      # Default `around_refresh_token` callable
+      #
+      # When non-nil, the OAuth middleware yields its read+check+refresh
+      # sequence to this callable so the host application can serialize
+      # concurrent refreshes (e.g. with an advisory lock).
+      #
+      # @return [Proc, nil]
+      def around_refresh_token
+        nil
+      end
+
       # Default API key from ENV
       # @return [String, nil] API key for authentication
       def api_key

data/lib/booqable/middleware/auth/oauth.rb

@@ -24,6 +24,10 @@ module Booqable
         # @option options [String] :api_endpoint API endpoint URL for the OAuth provider
         # @option options [Proc] :read_token Proc to read stored token
         # @option options [Proc] :write_token Proc to store new token
+        # @option options [Proc, nil] :around_refresh_token Optional callable
+        #   invoked with a block around the read+check+refresh sequence. The
+        #   host application can use it to serialize concurrent refreshes
+        #   (e.g. wrap the block in a database transaction + advisory lock).
         # @raise [KeyError] If required options are not provided
         def initialize(app, options = {})
           super(app)
@@ -33,6 +37,7 @@ module Booqable
           @api_endpoint = options.fetch(:api_endpoint)
           @read_token = options.fetch(:read_token)
           @write_token = options.fetch(:write_token)
+          @around_refresh_token = options[:around_refresh_token]
 
           @client = OAuthClient.new(
             client_id: @client_id,
@@ -50,10 +55,12 @@ module Booqable
         # @param env [Faraday::Env] The request environment
         # @return [Faraday::Response] The response from the next middleware
         def call(env)
-          @token = @client.get_access_token_from_hash(@read_token.call)
+          around_refresh_token do
+            @token = @client.get_access_token_from_hash(@read_token.call)
 
-          if @token.expired? || @token.expires_at.nil?
-            @token = refresh_token!
+            if @token.expired? || @token.expires_at.nil?
+              @token = refresh_token!
+            end
           end
 
           env.request_headers["Authorization"] ||= "Bearer #{@token.token}"
@@ -63,6 +70,16 @@ module Booqable
 
         private
 
+        # Yield to the configured around-callback, if any
+        #
+        # When a host application provides one (e.g. an advisory lock), the
+        # read+check+refresh sequence runs inside it so concurrent callers
+        # cannot interleave a read with another caller's refresh.
+        def around_refresh_token(&block)
+          return yield unless @around_refresh_token
+          @around_refresh_token.call(&block)
+        end
+
         # Refresh the expired OAuth token
         #
         # Uses the refresh token to obtain a new access token and stores it

data/lib/booqable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Booqable
-  VERSION = "1.1.0"
+  VERSION = "1.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: booqable
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Hrvoje Šimić
@@ -86,6 +86,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.22
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -93,6 +96,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.22
 - !ruby/object:Gem::Dependency
   name: jwt
   requirement: !ruby/object:Gem::Requirement
@@ -166,7 +172,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Official Booqable API client for Ruby.
 test_files: []