sessions 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a11c0aa8a096b0cc19e25a62967da2414cdf8732a2587cdd9a23ed7d989fd67
-  data.tar.gz: ea2e6a1fa8a96771886c86e74d6dfa391fffa4138e825006511222dd221652a4
+  metadata.gz: f088a81ac84fec5df0bfd521c3d4012fa6a91a4a84e22e997e22d18ef1658b1b
+  data.tar.gz: d50021247992ad1bef65b9a4d5f678146e774501b6adaa0af87840ec1e8ce988
 SHA512:
-  metadata.gz: d4aa37c48143f477dc820e85b8a44158682f4f40991411bb382af74fefd20d0001050dd2e7324830cea73e4edc459e252f3762aaea034bd4386bacda488f088c
-  data.tar.gz: d29228d847cb0acd7e6b348a872de1ae988afdbe5e70c69509f24a41aa18992109f57ba2964cddc66a08a6f09802cbdfe9a55d1a8d9fc4e6d01caeb92d9db6a8
+  metadata.gz: ab013f9e59218a51e6f580deaa8d1bf01e45a4fd22eded95d91e1d4e2ba434d433bceedddf06d349dcfdfa63fd2b3678c8aaa9742729353da439e6e01778115e
+  data.tar.gz: 10eabd4758d01e1cf0ed44df351f8182dfe27c80f4fec7ee2024f0500da199a1ca356c77c72d444efface0c56f091f9d1312c9d46a2c2bd80ea77a6115fe94a9

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.2 (2026-06-16)
+
+Production-found hardening for Devise/Warden adoption, the path that turns already-authenticated pre-gem sessions into registry rows.
+
+- **Adoption is now keyed by owner + scope, not user agent or time.** One pre-existing authenticated session marker is enough; Hotwire Native devices legitimately present both a WebView UA and a native HTTP-client UA, and clients that drop `Set-Cookie` responses must not mint one adopted row per UA or per day.
+- **Concurrent adoption bursts are now atomic when the upgrade migration has run.** Adopted rows get a nullable `adoption_key` with a plain unique index. Normal sessions keep it `NULL`, so the index behaves like a portable partial unique index across PostgreSQL, MySQL and SQLite. Racing requests either create the one keyed row or catch the uniqueness collision, re-select it, and touch it — still inside `Sessions.safely`, so tracking never breaks login.
+- **Existing installs have an explicit upgrade path.** Run `rails generate sessions:upgrade` and `rails db:migrate` to add `sessions.adoption_key`. Fresh installs get the column from `sessions:install`.
+- **The adapter degrades gracefully before the migration.** If `adoption_key` is absent, it still reuses any existing adopted row for the same owner + scope, eliminating the UA split and 24-hour leak while the schema upgrade is pending; the database-level race guarantee starts once the migration is deployed.
+
 ## 0.1.1 (2026-06-12)
 
 Production-found fix, hours after 0.1.0: a client that forwards cookies **read-only** — the canonical case is a native app's HTTP layer that attaches the WebView's cookie but drops `Set-Cookie` responses — re-enters the Devise-mode *adoption* path on every request, because the session token the gem writes never persists client-side. Each pass minted a fresh adopted row (and adoption also skipped the per-user cap), so one phone on a polling screen accumulated hundreds of "live devices" in an hour.

data/README.md

@@ -96,6 +96,17 @@ That's it. Every sign-in from now on lands on the devices page and in the trail
 >
 > **API-only app?** The gem boots and tracks fine (use the model APIs and `Sessions.track_login`), but the devices page is HTML — mounting the engine needs an `ActionController::Base`-derived `config.parent_controller`, which API-only apps don't have.
 
+### Upgrading
+
+Existing apps upgrading from 0.1.0 or 0.1.1 should copy the upgrade migration and run it:
+
+```bash
+rails generate sessions:upgrade
+rails db:migrate
+```
+
+This adds `sessions.adoption_key`, the portable unique guard that makes pre-gem session adoption atomic under concurrent native-app request bursts. Fresh installs already get it from `sessions:install`.
+
 ## What `sessions` does (and doesn't) do
 
 **Does:**

data/lib/generators/sessions/templates/add_adoption_key_to_sessions.rb.erb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# v0.1.2 upgrade: adopted rows are keyed by owner+scope so clients that never
+# persist Set-Cookie responses cannot create unbounded duplicate sessions.
+# Existing adopted rows keep NULL keys; the adapter claims one lazily on the
+# next request. Normal, non-adopted sessions also keep NULL, so this plain
+# unique index behaves like a portable partial unique index across PostgreSQL,
+# MySQL and SQLite.
+class AddSessionsAdoptionKeyTo<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_column :<%= table_name %>, :adoption_key, :string unless column_exists?(:<%= table_name %>, :adoption_key)
+    add_index :<%= table_name %>, :adoption_key, unique: true unless index_exists?(:<%= table_name %>, :adoption_key)
+  end
+end

data/lib/generators/sessions/templates/add_sessions_columns.rb.erb

@@ -17,6 +17,12 @@ class AddSessionsColumnsTo<%= table_name.camelize %> < ActiveRecord::Migration<%
       # The Warden scope ("user") — multi-scope Devise apps.
       t.string :scope
 
+      # Adopted sessions (pre-gem logins that had no sessions token yet)
+      # get one deterministic owner+scope key. Normal sessions keep this
+      # NULL, so the unique index below constrains only adopted rows while
+      # staying portable across PostgreSQL, MySQL and SQLite.
+      t.string :adoption_key
+
       # How this session started: password / oauth / google_one_tap /
       # passkey / magic_link / otp / sso / token / unknown — plus the
       # provider ("google", "apple", "github") and per-method extras
@@ -62,6 +68,7 @@ class AddSessionsColumnsTo<%= table_name.camelize %> < ActiveRecord::Migration<%
 
     add_index :<%= table_name %>, :device_id
     add_index :<%= table_name %>, :token_digest, unique: true
+    add_index :<%= table_name %>, :adoption_key, unique: true
     add_index :<%= table_name %>, :auth_method
     add_index :<%= table_name %>, :auth_provider
     add_index :<%= table_name %>, :country_code

data/lib/generators/sessions/templates/create_sessions.rb.erb

@@ -30,6 +30,12 @@ class Create<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_ve
       # The Warden scope ("user") — multi-scope Devise apps.
       t.string :scope
 
+      # Adopted sessions (pre-gem logins that had no sessions token yet)
+      # get one deterministic owner+scope key. Normal sessions keep this
+      # NULL, so the unique index below constrains only adopted rows while
+      # staying portable across PostgreSQL, MySQL and SQLite.
+      t.string :adoption_key
+
       # How this session started: password / oauth / google_one_tap /
       # passkey / magic_link / otp / sso / token / unknown — plus the
       # provider and per-method extras.
@@ -71,6 +77,7 @@ class Create<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_ve
 
     add_index :<%= table_name %>, :device_id
     add_index :<%= table_name %>, :token_digest, unique: true
+    add_index :<%= table_name %>, :adoption_key, unique: true
     add_index :<%= table_name %>, :auth_method
     add_index :<%= table_name %>, :auth_provider
     add_index :<%= table_name %>, :country_code

data/lib/generators/sessions/templates/madmin/session_resource.rb

@@ -36,6 +36,7 @@ class SessionResource < Madmin::Resource
   # NEVER rendered: the token digest is a credential hash, and the raw
   # header blobs are noise next to the parsed columns above.
   attribute :token_digest, show: false, form: false
+  attribute :adoption_key, show: false, form: false
   attribute :auth_detail, show: false, form: false
   attribute :client_hints, show: false, form: false
 

data/lib/generators/sessions/upgrade_generator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module Sessions
+  module Generators
+    # `rails generate sessions:upgrade` — copies version-to-version
+    # migrations for apps that installed a prior release. The install
+    # generator remains the source for fresh apps; this generator gives
+    # existing hosts an explicit, reviewable upgrade path.
+    class UpgradeGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Install sessions upgrade migrations"
+
+      class_option :model, type: :string, default: "Session",
+                           desc: "Session model name (escape hatch for apps with a custom session class)"
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_upgrade_migrations
+        migration_template "add_adoption_key_to_sessions.rb.erb",
+                           File.join(db_migrate_path, "add_sessions_adoption_key_to_#{table_name}.rb")
+      end
+
+      def display_post_upgrade_message
+        say "\n🔐 sessions upgrade migrations have been installed.", :green
+        say "\nTo complete the upgrade:"
+        say "  1. Review the generated migration."
+        say "  2. Run 'rails db:migrate'."
+        say "     ⚠️  Deploy the migration before relying on adoption hardening.", :yellow
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+
+      def model_name
+        options[:model].presence || "Session"
+      end
+
+      def table_name
+        model_name.underscore.pluralize.tr("/", "_")
+      end
+    end
+  end
+end

data/lib/sessions/adapters/warden.rb

@@ -108,17 +108,22 @@ module Sessions
         end
       end
 
-      def create_row_for(record, warden, scope, suppress_login_event: false)
+      def create_row_for(record, warden, scope, suppress_login_event: false, attributes: {})
         token = Sessions.generate_token
         request = warden.request
+        model = Sessions.session_model
 
-        row = Sessions.session_model.new(
+        row = model.new(
           user: record,
           scope: scope.to_s,
           ip_address: Sessions::IpAddress.resolve(request),
           user_agent: request.user_agent,
           token_digest: Sessions.token_digest(token)
-        )
+        ).tap do |session|
+          attributes.each do |column, value|
+            session[column] = value if model.column_names.include?(column.to_s)
+          end
+        end
         row.sessions_suppress_login_event = suppress_login_event
         Sessions.with_request(request) { row.save! }
 
@@ -188,34 +193,79 @@ module Sessions
 
           # IDEMPOTENT, because a client that can't persist cookies re-enters
           # adoption on EVERY request: the SESSION_KEY we write rides a
-          # Set-Cookie the client drops, so the next request adopts again —
-          # unbounded rows (production-found: a native HTTP layer that
-          # forwarded cookies read-only minted one adopted row per location
-          # ping, hundreds per ride). Same user, same scope, same UA,
-          # recently adopted → that's this same client: touch it, mint
-          # nothing. No token rotation either — a sibling client sharing the
-          # cookie jar (the app's WebView next to its native HTTP stack) may
-          # hold a VALID key to this row, and rotating would kick it.
-          if (row = recent_adopted_row(record, warden, scope))
+          # Set-Cookie the client drops, so the next request adopts again.
+          #
+          # Adoption is intentionally coarse: it is a low-fidelity marker for
+          # "this owner already had an authenticated session when the gem
+          # arrived", not a real login. One owner+scope marker is enough. Do
+          # not key it on UA (Hotwire Native devices legitimately use WebView
+          # and native-client UAs) or time (cookie-dropping clients would mint
+          # one per day forever). When the adoption_key column is present, the
+          # unique index makes the first concurrent burst atomic.
+          adoption_key = adoption_key_for(record, scope)
+          if (row = adopted_row(record, scope, adoption_key: adoption_key))
             Sessions.safely("warden.adopt.touch") { row.touch_last_seen!(warden.request) }
             next
           end
 
-          row = create_row_for(record, warden, scope, suppress_login_event: true)
-          row&.update_columns(auth_detail: { "adopted" => true })
+          create_adopted_row(record, warden, scope, adoption_key: adoption_key)
+        end
+      end
+
+      def create_adopted_row(record, warden, scope, adoption_key:)
+        attributes = { auth_detail: { "adopted" => true } }
+        attributes[:adoption_key] = adoption_key if adoption_key_column?
+
+        create_row_for(record, warden, scope, suppress_login_event: true, attributes: attributes)
+      rescue ActiveRecord::RecordNotUnique
+        adopted_row(record, scope, adoption_key: adoption_key)&.tap do |row|
+          Sessions.safely("warden.adopt.touch") { row.touch_last_seen!(warden.request) }
         end
       end
 
-      def recent_adopted_row(record, warden, scope)
+      def adopted_row(record, scope, adoption_key:)
         model = Sessions.session_model
         rows = model.where(user: record)
         rows = rows.where(scope: scope.to_s) if model.column_names.include?("scope")
-        rows = rows.where(user_agent: warden.request.user_agent) if model.column_names.include?("user_agent")
 
-        rows.where(model.arel_table[:created_at].gt(24.hours.ago))
-            .order(created_at: :desc)
-            .limit(10)
-            .detect { |row| row.try(:auth_detail).to_h["adopted"] }
+        row = model.find_by(adoption_key: adoption_key) if adoption_key_column?(model) && adoption_key.present?
+        row = nil unless adopted_row?(row)
+        row ||= rows.order(created_at: :desc).detect { |candidate| adopted_row?(candidate) }
+
+        claim_adoption_key(row, adoption_key)
+      end
+
+      def adopted_row?(row)
+        row && row.try(:auth_detail).to_h["adopted"]
+      end
+
+      def claim_adoption_key(row, adoption_key)
+        return row unless row
+        return row unless adoption_key_column?(row.class)
+        return row if adoption_key.blank? || row.try(:adoption_key).present?
+
+        row.update_columns(adoption_key: adoption_key)
+        row.adoption_key = adoption_key
+        row
+      rescue ActiveRecord::RecordNotUnique
+        row.class.find_by(adoption_key: adoption_key) || row
+      end
+
+      def adoption_key_for(record, scope)
+        owner_id = record.respond_to?(:to_key) ? Array(record.to_key).join("/") : record.try(:id)
+        return if owner_id.blank?
+
+        owner_type = if record.class.respond_to?(:polymorphic_name)
+                       record.class.polymorphic_name
+                     else
+                       record.class.name
+                     end
+
+        "adopt:#{Sessions.token_digest([owner_type, owner_id, scope.to_s].join("\0"))}"
+      end
+
+      def adoption_key_column?(model = Sessions.session_model)
+        model.column_names.include?("adoption_key")
       end
 
       # SCOPE-PRECISE teardown: only this scope's warden entries go (the

data/lib/sessions/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sessions
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sessions
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-06-12 00:00:00.000000000 Z
+date: 2026-06-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -163,6 +163,7 @@ files:
 - gemfiles/rails_8.1.gemfile
 - lib/generators/sessions/install_generator.rb
 - lib/generators/sessions/madmin_generator.rb
+- lib/generators/sessions/templates/add_adoption_key_to_sessions.rb.erb
 - lib/generators/sessions/templates/add_sessions_columns.rb.erb
 - lib/generators/sessions/templates/create_sessions.rb.erb
 - lib/generators/sessions/templates/create_sessions_events.rb.erb
@@ -173,6 +174,7 @@ files:
 - lib/generators/sessions/templates/madmin/sessions_controller.rb
 - lib/generators/sessions/templates/session.rb.erb
 - lib/generators/sessions/templates/sessions_sweep_job.rb
+- lib/generators/sessions/upgrade_generator.rb
 - lib/generators/sessions/views_generator.rb
 - lib/sessions.rb
 - lib/sessions/adapters/omakase.rb