api_keys 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62087b06751cfbfe1b08bc1db54179fa1ce72844da86166a5198887d7b834a3f
-  data.tar.gz: 51ddeccbaee055eaf9d1cec6677b9514b478bf0ff4764768dee7e40e731c8685
+  metadata.gz: 465a7a5c57c770d52195e2c8a182b00d60ea19dc8cc879ebfdb83b3e16d810f2
+  data.tar.gz: daa04e5c07e2dbfe8200c9a43189a2249b680e00737f6c201646a1495847fb06
 SHA512:
-  metadata.gz: 5b8adba5c3631e272a77bfd600f4667981bf91048e529aeac7b5f6f0c6d9b1967c989edff1ee23ee9d2a2bb9da3d83a9206e7b0a20ca26f741ebb8bae5abc586
-  data.tar.gz: e0bbcb9c1bf0be08bdbe9ffe035e7dbe60a2cddc0520474fb94c40ca6cba53c46fc8f4ce5cb9537fd14ab4392149ac294a89d7599a61ba95e66a5f8e1864fd6b
+  metadata.gz: a4b8b2a0f2386cbbe52505afc68e6ca972aaf4106efa27d72aaa09441805760eea8772666133734c288c39cd8542db096a712bc17ad514a1be8331875faf741d
+  data.tar.gz: 3bd195acb458ff535ed41ceb699d3bf6972ace5cc7d46e80a58ac743849ef3549baaaf29baacf836c5ede49587cd93c1a2532ea002f9d5667802d6c830712de6

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.8.0] - 2026-10-25
+
+### Added
+
+- `config.require_bearer_scheme`. When true, the authentication header is accepted only as `Bearer <token>` (any case, spaces or tabs after the scheme); a bare token, another scheme such as `Basic`, or a lone `Bearer` gets the ordinary 401 `invalid_token`, is never looked up, and never falls back to `config.query_param`. It applies to whichever header `config.header` names. The default, false, keeps accepting a bare token as every earlier version did. Asked for by ReplyBrain, whose public API should parse one credential shape only.
+
 ## [0.7.0] - 2026-10-24
 
 Four features that an invoicing app on the fleet runs in production today, moved into the gem with their tests so that apps on the fleet can delete their own copies. Each one is opt-in: an app that does not use it sees no change.

data/README.md

@@ -1298,9 +1298,19 @@ See the [Key Types](#key-types-stripe-style-publishable--secret-keys) section be
 
 Some highlights:
 
+### Require the `Bearer` scheme
+
+Clients send `Authorization: Bearer ak_123abc...`. For compatibility, a bare `Authorization: ak_123abc...` is accepted too. A public API should accept one shape only, so turn the bare token off:
+
+```ruby
+config.require_bearer_scheme = true
+```
+
+Now a header without the scheme (a bare token, `Basic …`, `Token …`) gets the same 401 `invalid_token` as any wrong key, and is never looked up. It applies to whichever header you configured in `config.header`, and a refused header never falls back to the query parameter.
+
 ### Accept API keys via query params instead of Authentication HTTP headers
 
-By default, the `api_key` gem expects API keys to come *exclusively* as HTTP Authentication Bearer tokens, for security purposes. But you can allow users to make requests to your endpoints with the API key token passed as a URL query param too, like this:
+By default, the `api_key` gem expects API keys to come *exclusively* in the `Authorization` header, for security purposes. But you can allow users to make requests to your endpoints with the API key token passed as a URL query param too, like this:
 
 ```
 https://example.com/api/endpoint?api_key=ak_123abc...

data/lib/api_keys/configuration.rb

@@ -16,7 +16,13 @@ module ApiKeys
     # == Accessors ==
 
     # Core Authentication
-    attr_reader :header, :query_param
+    #
+    # @!attribute [rw] require_bearer_scheme
+    #   @return [Boolean] Accept the header only as "Bearer <token>". A value
+    #     without the scheme is refused like any invalid token (401
+    #     `invalid_token`). false (the default) also accepts the bare token,
+    #     as every earlier version did.
+    attr_reader :header, :query_param, :require_bearer_scheme
 
     # Token Generation
     attr_reader :token_prefix, :token_length, :token_alphabet
@@ -192,7 +198,7 @@ module ApiKeys
     BOOLEAN_SETTINGS = %i[
       require_key_name track_requests_count https_only_production https_strict_mode
       enable_async_operations debug_logging strict_environment_isolation
-      dashboard_allow_cross_environment
+      dashboard_allow_cross_environment require_bearer_scheme
     ].freeze
 
     def header=(value)
@@ -633,6 +639,7 @@ module ApiKeys
       # Core Authentication
       @header = "Authorization" # Expects "Bearer <token>"
       @query_param = nil # No query param lookup by default
+      @require_bearer_scheme = false # Also accept a bare token in the header
 
       # Token Generation
       @token_prefix = -> { "ak_" }

data/lib/api_keys/services/authenticator.rb

@@ -18,8 +18,9 @@ module ApiKeys
       # The longest authentication header that can still carry a valid token:
       # the token plus the "Bearer" scheme and generous separator whitespace.
       MAX_CREDENTIAL_HEADER_BYTESIZE = MAX_TOKEN_BYTESIZE + 64
-      # Stands in for a header refused before parsing. It is not a String, so
-      # it can never match a key and always yields :invalid_token.
+      # Stands in for a refused header: malformed, or without the Bearer
+      # scheme the app requires. It is not a String, so it can never match a
+      # key and always yields :invalid_token.
       MALFORMED_CREDENTIAL = Object.new.freeze
       MAX_BCRYPT_CANDIDATES = 32
       MAX_KNOWN_PREFIXES = 1_024
@@ -146,7 +147,13 @@ module ApiKeys
               log_debug "[ApiKeys Auth] Extracted token from Bearer scheme."
               return match[1]
             end
-            # Fallback: return the raw header value if no Bearer scheme
+            # A bare token is accepted unless the app requires the scheme.
+            # Refused, it is an invalid token: the header was present, so it
+            # never falls through to the query parameter.
+            if config.require_bearer_scheme
+              log_debug "[ApiKeys Auth] Refused a header without the Bearer scheme."
+              return MALFORMED_CREDENTIAL
+            end
             log_debug "[ApiKeys Auth] No Bearer scheme, using raw header value as token."
             return header_value
           end

data/lib/api_keys/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ApiKeys
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/generators/api_keys/templates/initializer.rb

@@ -9,6 +9,11 @@ ApiKeys.configure do |config|
   # Default: "Authorization" (expects "Bearer <token>")
   # config.header = "Authorization"
 
+  # Accept the header only as "Bearer <token>", refusing a bare token with
+  # 401 invalid_token. Recommended for public APIs.
+  # Default: false (a bare token is accepted too)
+  # config.require_bearer_scheme = true
+
   # The query parameter name to check as a fallback if the header is missing.
   # WARNING: Query parameters appear in logs, browser history, and Referer headers.
   # Only enable for development/testing. Set to nil to disable (recommended).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_keys
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - rameerez