standard_id 0.31.0 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f929d1f67a0302d3b2f93043c5ac009d8d98195a8c1f3f5c7e79ca45210873dc
-  data.tar.gz: 1b58091aeb06c9d3a13a3fc57dd710688dd75c8be48d2d950b19bfc400cb00d0
+  metadata.gz: 9186b11b608c1e58f0ea0a2c957eac6e88aaeb7ea18012fe133b40c5d77c54e9
+  data.tar.gz: 888389931fa6d8854c4632f175db13409c32991905870cdcbb2c16bc53c912cb
 SHA512:
-  metadata.gz: b4dbbac7f24a1cb89efa9787e2acbed6ab4f8fa531d84c525344f3069c4d6bd0be2d5a17f014074f700c5af88be2b6c071ed6d1ecb94d1b27fec172bf8d3b169
-  data.tar.gz: 265319cf5f65851df3e4a7f8a24d3aa4765d001a27e4d89797e10cc372f4515d558b785863810cd71e7f8d577e4388c1b8f98dfe273218824e29fa7f8e3f9183
+  metadata.gz: 423dc3b53caf3fad0e0ba2ea41230627a07328e27fdb29439bfaaafb0701b1887f78744321c2579ac8018741a96fda684230d488604702b865e5b8193ebecce4
+  data.tar.gz: c16d76284752125e7191ca9ae7770a9fed1c3f0af6078f0221bfb294eaddf78f16701c1954147467f9118916d9d662d50dae5b6844589ffc76d65b14af406ab2

data/CHANGELOG.md

@@ -7,6 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.32.0] - 2026-07-28
+
+### Changed
+
+- **Session token digests now default to HMAC-SHA256 instead of BCrypt.**
+  `Session#token_digest` was a BCrypt hash at bcrypt-ruby's default cost 12.
+  BCrypt's cost factor exists to make brute-force of a *low-entropy* secret
+  expensive; session tokens are `SecureRandom.urlsafe_base64(32)` — 256 bits —
+  so guessing one is infeasible at any hash speed, and the stretching bought
+  nothing while costing real CPU on every authenticated request.
+
+  The cost was measured in a consuming app, and it is not small: **~181 ms per
+  verify**, paid per *request* rather than per session creation, which collapsed
+  API throughput **19.7×** versus the same requests authenticated by JWT (5.07
+  vs 99.95 rps at concurrency 1). Every endpoint in that mix shifted by the same
+  ~185 ms. Note this is CPU, not lock contention — bcrypt releases the GVL, so
+  four concurrent verifies complete in 3.87× less wall time than four serial
+  ones; it saturates cores rather than serializing requests.
+
+  The new digest is HMAC-SHA256 under `secret_key_base`, domain-separated from
+  `lookup_hash` by both construction and a versioned prefix so the two values
+  can never coincide. This aligns session tokens with how the gem already
+  handles comparable credentials: `RefreshToken` digests with SHA256, and
+  `Session#lookup_hash` is SHA256.
+
+  **Nothing is stranded.** Existing rows are never rewritten and no token
+  rotation is needed. `Session#authenticate_token` reads the scheme off the
+  *stored* digest — BCrypt digests are self-identifying by their `$2<x>$`
+  prefix — so old and new digests verify side by side indefinitely. Sessions
+  issued before upgrading keep working at their old cost until they expire or
+  are re-issued; sessions issued after are fast.
+
+  **Consumer impact — read this if you verify token digests yourself.** If you
+  authenticate opaque session tokens through `Session.authenticate_by_token` or
+  `Session#authenticate_token` (the API added in 0.30), there is nothing to do.
+
+  If you still hand-roll the pre-0.30 pattern —
+
+  ```ruby
+  BCrypt::Password.new(session.token_digest) == token
+  ```
+
+  — **this release breaks you**, and loudly: a newly-created session's digest is
+  a 64-character HMAC, so `BCrypt::Password.new` raises
+  `BCrypt::Errors::InvalidHash` (or, if you rescue that, rejects every new
+  session). That pattern was the only option before 0.30, so it is worth
+  grepping for. Two ways out, either fine:
+
+  1. **Switch to the gem's verifier** (recommended, and correct on both
+     schemes): `StandardId::Session.api_compatible.active.authenticate_by_token(token)`,
+     or `session.authenticate_token(token)` if you already hold the row.
+  2. **Stay on BCrypt for now** by setting `config.session.token_digest_cost`
+     to your preferred cost. New sessions keep being BCrypt-digested and your
+     existing code keeps working, so you can migrate callers on your own
+     schedule. You can flip it back at any time — the scheme is read off each
+     stored digest, so mixing the two is always safe.
+
+  **If you want BCrypt anyway**, set `config.session.token_digest_cost` to the
+  cost you want; that setting now opts *in* to BCrypt rather than merely tuning
+  it. Its previous meaning is preserved for anyone who set it deliberately, and
+  changing it remains safe in both directions because the scheme is read off the
+  stored digest, not off configuration.
+
 ## [0.31.0] - 2026-07-27
 
 ### Fixed

data/app/models/standard_id/session.rb

@@ -23,9 +23,10 @@ module StandardId
     #
     # `by_token` is NOT authentication on its own: it matches the SHA256
     # `lookup_hash`, which exists only to find the candidate row from an
-    # indexed column. The credential is the BCrypt `token_digest`, and every
-    # consumer previously had to remember to verify it by hand (and to rescue
-    # BCrypt::Errors::InvalidHash). This is that step, done once, here.
+    # indexed column. The credential is `token_digest` (see #authenticate_token
+    # for the two schemes it may hold), and every consumer previously had to
+    # remember to verify it by hand — and to rescue BCrypt::Errors::InvalidHash.
+    # This is that step, done once, here.
     #
     # Honours the current scope, so callers keep their own filters:
     #
@@ -43,20 +44,55 @@ module StandardId
       session.authenticate_token(token) ? session : nil
     end
 
-    # Timing-safe verification of `token` against this session's stored
-    # BCrypt digest. Re-hashes the presented token with the stored salt and
-    # compares the two digests with a constant-time compare, so the response
-    # time carries no information about how much of the digest matched.
+    # Keyed digest of an opaque session token — the default scheme.
+    #
+    # HMAC-SHA256 under `secret_key_base`, domain-separated from `lookup_hash`
+    # by both construction (HMAC vs plain SHA256) and an explicit versioned
+    # prefix, so the two stored values can never coincide even though both
+    # derive from the same token and secret.
+    #
+    # Why not BCrypt (which this was, and which `token_digest_cost` still
+    # selects): BCrypt's cost factor exists to make brute-force of a LOW-entropy
+    # secret expensive. Session tokens are `SecureRandom.urlsafe_base64(32)` —
+    # 256 bits — so guessing one is infeasible regardless of how fast the hash
+    # is, and the stretching bought nothing while costing a measured ~181 ms of
+    # CPU on EVERY authenticated request (cost 12). That is the same reasoning
+    # under which `RefreshToken` digests with plain SHA256 and `lookup_hash`
+    # with SHA256; this brings session tokens in line with both.
+    DIGEST_PREFIX = "standard_id.session.token_digest.v1:".freeze
+
+    def self.hmac_token_digest(token)
+      OpenSSL::HMAC.hexdigest(
+        "SHA256", Rails.configuration.secret_key_base, "#{DIGEST_PREFIX}#{token}"
+      )
+    end
+
+    # Timing-safe verification of `token` against this session's stored digest.
+    #
+    # Handles BOTH schemes, because digests written before the HMAC default —
+    # and any written since by an app that sets `token_digest_cost` — are
+    # BCrypt. A BCrypt digest is self-identifying by its `$2<x>$` prefix, so the
+    # scheme is read off the stored value rather than off configuration; that
+    # way a config change never strands existing sessions, and no rewrite of
+    # stored digests is needed. Both branches end in a constant-time compare, so
+    # the response time carries no information about how much of the digest
+    # matched.
     #
     # @return [Boolean] false for a blank or malformed digest — never raises.
     def authenticate_token(token)
       return false if token.blank? || token_digest.blank?
 
-      stored = BCrypt::Password.new(token_digest)
-      ActiveSupport::SecurityUtils.secure_compare(
-        stored.to_s,
-        BCrypt::Engine.hash_secret(token, stored.salt)
-      )
+      if token_digest.start_with?("$2")
+        stored = BCrypt::Password.new(token_digest)
+        ActiveSupport::SecurityUtils.secure_compare(
+          stored.to_s,
+          BCrypt::Engine.hash_secret(token, stored.salt)
+        )
+      else
+        ActiveSupport::SecurityUtils.secure_compare(
+          token_digest, self.class.hmac_token_digest(token)
+        )
+      end
     rescue BCrypt::Errors::InvalidHash, BCrypt::Errors::InvalidSalt
       false
     end
@@ -94,11 +130,17 @@ module StandardId
       @token ||= SecureRandom.urlsafe_base64(32)
     end
 
+    # HMAC by default; BCrypt only when an app explicitly asks for it by setting
+    # `token_digest_cost`. That inverts the previous default (BCrypt at
+    # bcrypt-ruby's cost 12) — see .hmac_token_digest for why — while leaving
+    # the escape hatch meaning exactly what it says for anyone who set it
+    # deliberately. Existing rows are untouched either way: #authenticate_token
+    # reads the scheme off the stored digest, not off this config.
     def generate_token_digest
       configured_cost = StandardId.config.session.token_digest_cost
       self.token_digest =
         if configured_cost.nil?
-          BCrypt::Password.create(token)
+          self.class.hmac_token_digest(token)
         else
           cost = configured_cost.clamp(BCrypt::Engine::MIN_COST, BCrypt::Engine::MAX_COST)
           BCrypt::Password.create(token, cost: cost)

data/lib/standard_id/config/schema.rb

@@ -173,18 +173,24 @@ StandardId::ConfigSchema.define do
     field :device_session_lifetime, type: :integer, default: 2592000 # 30 days in seconds
     field :service_session_lifetime, type: :integer, default: 7776000 # 90 days in seconds
 
-    # BCrypt cost factor for the session token digest. Default `nil` means
-    # use bcrypt-ruby's built-in default (cost 12 in production, MIN_COST
-    # in the test env). Since session tokens are 256-bit random
-    # (`SecureRandom.urlsafe_base64(32)`), any cost >= 10 is well beyond
-    # realistic brute-force, and dropping from 12 to 10 saves ~200ms of
-    # CPU per session creation. Host apps with many logins-per-second can
-    # set this to `10`; apps that value hash work over login latency can
-    # leave it alone or raise it.
+    # Opt IN to BCrypt for the session token digest, at this cost factor.
     #
-    # When set, value is clamped to BCrypt::Engine::MIN_COST..MAX_COST.
-    # Applies only to newly-created sessions; existing token_digests keep
-    # their original cost.
+    # Default `nil` means HMAC-SHA256 under `secret_key_base`, which is the
+    # right primitive here: session tokens are 256-bit random
+    # (`SecureRandom.urlsafe_base64(32)`), and BCrypt's cost factor exists to
+    # slow brute-force of LOW-entropy secrets. Against a token that cannot be
+    # guessed at any hash speed the stretching bought nothing, while costing a
+    # measured ~181 ms of CPU on every authenticated API request at cost 12 —
+    # note this is paid per REQUEST, not merely per session creation.
+    #
+    # Set it only if you specifically want hash work on this path anyway. When
+    # set, the value is clamped to BCrypt::Engine::MIN_COST..MAX_COST.
+    #
+    # Changing it is always safe and never strands a session:
+    # Session#authenticate_token reads the scheme off the stored digest (BCrypt
+    # digests are self-identifying by their `$2<x>$` prefix), so both schemes
+    # verify side by side and existing rows are never rewritten. As before, a
+    # change applies only to newly-created sessions.
     field :token_digest_cost, type: :integer, default: nil
 
     # Callable that resolves the session class to create for a given auth flow.

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.31.0"
+  VERSION = "0.32.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.31.0
+  version: 0.32.0
 platform: ruby
 authors:
 - Jaryl Sim