sessions 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 342cda70d0a4f3ed6b760d8dee9ff8dea68c97151d932e77c478474e216fe9ef
-  data.tar.gz: 6885d70e1cc6cbb5ebd9850c0b3f5d015ce22d1aeae5ba2968b0fd5bb33412e0
+  metadata.gz: f088a81ac84fec5df0bfd521c3d4012fa6a91a4a84e22e997e22d18ef1658b1b
+  data.tar.gz: d50021247992ad1bef65b9a4d5f678146e774501b6adaa0af87840ec1e8ce988
 SHA512:
-  metadata.gz: a15d061c3b9397265aa2e7581ed5e06ce64ae50943a54aa71b45539dfe528153004422b9c782d1dcd5cd2b62a55edef8612ed26c4f8a55ee8d91c0379f3d9133
-  data.tar.gz: 4ecef8ccd7f56454a31feb6623245c38585dbae7601fdb681daa6192e764964a4c47300dc3b8aaaa6dbe2811246a66c304210d202e5a6f9e46c40085d34a246f
+  metadata.gz: ab013f9e59218a51e6f580deaa8d1bf01e45a4fd22eded95d91e1d4e2ba434d433bceedddf06d349dcfdfa63fd2b3678c8aaa9742729353da439e6e01778115e
+  data.tar.gz: 10eabd4758d01e1cf0ed44df351f8182dfe27c80f4fec7ee2024f0500da199a1ca356c77c72d444efface0c56f091f9d1312c9d46a2c2bd80ea77a6115fe94a9

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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.
+
+- **Adoption is now idempotent**: a re-entering client matches its recent adopted row (same user, scope, and user agent within 24h) and just touches it — no new row, no token rotation (rotating would kick a sibling client validly holding that row's token, e.g. the app's WebView next to its native HTTP stack).
+- **The per-user session cap now applies to suppressed (adopted) writes too** — it's the hard limit on live rows, whatever path creates them.
+
+Plus a full-codebase audit pass:
+
+- **The remote-revocation kick now ships its own flash copy.** The Warden adapter throws `message: :session_revoked`, and Devise's failure app resolves it via `devise.failure.session_revoked` — a key nothing shipped, so revoked devices saw a literal "Translation missing: en.devise.failure.user.session_revoked" at the exact moment the flagship feature fired. The gem now provides the key in English and Spanish (override it like any I18n key), pinned by a test that mirrors Devise's exact lookup (`I18n.t(:"#{scope}.#{message}", scope: "devise.failure", default: [message])`).
+- **`config.strategy_methods` now truly overrides built-ins on a shared key.** The mapping merge let the built-in value win a duplicate key (e.g. remapping `"Rememberable"`), contradicting the documented host-wins contract; host entries now win both the iteration order and key conflicts.
+- **Failed-login identity capture also reads `email_address`** — the omakase-era key, and what Devise apps with `authentication_keys = [:email_address]` post. Those failures used to record `identity: nil`, quietly gutting ATO triage and `repeated_failed_logins` for that setup.
+- **The installer now validates the Devise auth model fit.** Default (non-polymorphic) mode assumes a `User` class — the same assumption `rails generate authentication` makes. A Devise app on `Member`/`Account` used to pass detection and then break at `db:migrate` (foreign key to a missing `users` table); the installer now reads `Devise.mappings` and stops with the fix (`--polymorphic`) before writing anything, and warns (without blocking) when extra scopes ride alongside `User`, since those stay silently untracked in default mode. Unreadable mappings stay permissive. README gained the matching callout.
+- **API-only hosts boot.** The engine controller's class body used `helper`/`helper_method`/`layout` unconditionally — none of which exist on `ActionController::API` — and production eager-loads engine controllers whether or not the engine is mounted, so an API-only app bundling the gem for the model/trail APIs failed to boot. The view-layer DSL is now capability-guarded (mounting the HTML page still requires a `Base`-derived parent, as documented).
+- **Generated migrations honor exotic primary-key types.** `primary_key_type: :string` (ULID-style apps) now flows through to the events table's PK and the `session_id` linkage column (previously coerced to `bigint`, breaking the trail↔registry join), and the serial pseudo-types map to their plain integer column equivalents for reference columns — a `t.bigserial` reference would mint its own sequence.
+- `sessions_format_date`/`sessions_format_time` tolerate `nil` (custom views passing a nullable column used to hit `nil.strftime` *inside* the fallback rescue).
+
 ## 0.1.0 (2026-06-12)
 
 First release — the missing session layer for Rails. 🔐

data/README.md

@@ -91,6 +91,22 @@ end
 
 That's it. Every sign-in from now on lands on the devices page and in the trail — on Rails 8 auth there is literally nothing else to wire (the gem decorates the generated `Session` model automatically; your app code stays untouched).
 
+> [!NOTE]
+> **Auth model isn't `User`?** (Devise on `Member`/`Account`, or several `devise_for` scopes): install with `rails generate sessions:install --polymorphic` — the session owner becomes polymorphic and every scope/model gets tracked; put `has_sessions` on each of them. The default install assumes a `User` class (the same assumption `rails generate authentication` makes), and the installer stops with exactly this advice when your Devise mappings don't fit it.
+>
+> **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/app/controllers/sessions/application_controller.rb

@@ -33,12 +33,19 @@ module Sessions
 
     before_action :sessions_authenticate!
 
-    helper Sessions::EngineHelper
-    helper_method :sessions_current_user, :sessions_current_session
+    # The view-layer DSL (`helper`, `helper_method`, `layout`) doesn't exist
+    # on ActionController::API — and an API-only host that bundles the gem
+    # purely for the model/trail APIs still EAGER LOADS this class in
+    # production, mounted or not. Guarding keeps such hosts bootable; the
+    # HTML devices page itself still requires a Base-derived
+    # config.parent_controller (the default), which is the only setup it's
+    # rendered under.
+    helper Sessions::EngineHelper if respond_to?(:helper)
+    helper_method :sessions_current_user, :sessions_current_session if respond_to?(:helper_method)
 
     # nil falls through to the parent controller's regular layout
     # resolution, so by default the page looks like the rest of the host.
-    layout :sessions_layout
+    layout :sessions_layout if respond_to?(:layout)
 
     private
 

data/app/helpers/sessions/engine_helper.rb

@@ -102,14 +102,21 @@ module Sessions
 
     # "Signed in May 2, 2026" — localized when the host bundles date
     # formats (rails-i18n or its own locale files), with a safe fallback so
-    # a bare host never 500s over a missing `date.formats.long`.
+    # a bare host never 500s over a missing `date.formats.long`. nil-safe:
+    # without the guard, I18n.l(nil) raises I18n::ArgumentError and the
+    # rescue would then call nil.strftime — a trap for custom views passing
+    # a nullable column.
     def sessions_format_date(date)
+      return nil unless date
+
       I18n.l(date, format: :long)
     rescue I18n::MissingTranslationData, I18n::ArgumentError
       date.strftime("%Y-%m-%d")
     end
 
     def sessions_format_time(time)
+      return nil unless time
+
       I18n.l(time, format: :short)
     rescue I18n::MissingTranslationData, I18n::ArgumentError
       time.strftime("%Y-%m-%d %H:%M")

data/config/locales/en.yml

@@ -57,3 +57,14 @@ en:
       composite: "%{client} on %{platform}"
       unknown: "Unknown device"
       bot: "Bot (%{name})"
+  # The flash a remotely-revoked device sees on its next request, rendered by
+  # Devise's failure app (the Warden adapter kicks with
+  # `throw :warden, message: :session_revoked`). Devise's lookup is
+  # `I18n.t(:"#{scope}.#{message}", scope: "devise.failure", default: [message])`
+  # — see Devise::FailureApp#i18n_message (devise/lib/devise/failure_app.rb).
+  # Without this key the flash literally reads
+  # "Translation missing: en.devise.failure.user.session_revoked".
+  # Hosts override it like any I18n key (app locale files load after engines).
+  devise:
+    failure:
+      session_revoked: "That session was signed out remotely. Please sign in again."

data/config/locales/es.yml

@@ -57,3 +57,10 @@ es:
       composite: "%{client} en %{platform}"
       unknown: "Dispositivo desconocido"
       bot: "Bot (%{name})"
+  # El aviso que ve un dispositivo cuya sesión fue revocada en remoto, en su
+  # siguiente petición (lo muestra la failure app de Devise; el adaptador de
+  # Warden expulsa con `throw :warden, message: :session_revoked`). Sin esta
+  # clave, el flash mostraría literalmente "Translation missing: …".
+  devise:
+    failure:
+      session_revoked: "Esa sesión se cerró de forma remota. Vuelve a iniciar sesión."

data/lib/generators/sessions/install_generator.rb

@@ -78,6 +78,48 @@ module Sessions
         MSG
       end
 
+      # Default (non-polymorphic) mode assumes a `User` class — the same
+      # assumption `rails generate authentication` makes: `belongs_to :user`
+      # and a foreign key to `users`. A Devise app whose auth model is
+      # Member/Account would pass detection and then break at db:migrate
+      # (FK to a missing `users` table) or at runtime (`belongs_to :user`
+      # constantizing a class that doesn't exist) — catch it HERE, with the
+      # fix in the error message. `--polymorphic` works with any model(s).
+      def check_devise_auth_model_fit!
+        return if polymorphic?
+        return unless devise_detected?
+        # An adopted omakase table already proves whatever owner shape the
+        # host made work — nothing for us to second-guess.
+        return if adopt_existing_table?
+
+        classes = devise_auth_class_names
+        return if classes.empty?         # mappings unreadable — stay permissive
+        return if classes == ["User"]    # the default assumption holds
+
+        if classes.include?("User")
+          # User plus other scopes: default mode tracks User and SILENTLY
+          # skips the rest (the runtime adapter's row_accepts? guard) —
+          # surface that tradeoff at install time, but proceed.
+          say "⚠️  Multiple Devise models detected (#{classes.join(", ")}).", :yellow
+          say "   The default install tracks only User — sessions for the other models", :yellow
+          say "   stay untracked. Re-run with --polymorphic to track them all.", :yellow
+          return
+        end
+
+        raise Thor::Error, <<~MSG
+          ❌ Your Devise model is #{classes.join(", ")} — not User. The default install
+          assumes a `User` class (`belongs_to :user`, foreign key to `users`, the
+          same assumption `rails generate authentication` makes) and would break
+          at migrate/runtime.
+
+          Re-run with the polymorphic owner, which works with any model(s):
+
+            rails generate sessions:install --polymorphic
+
+          …then declare `has_sessions` on #{classes.join(" and ")}.
+        MSG
+      end
+
       def create_migration_files
         if adopt_existing_table?
           migration_template "add_sessions_columns.rb.erb",
@@ -191,6 +233,19 @@ module Sessions
         defined?(::Devise) ? true : false
       end
 
+      # The class names behind the host's `devise_for` scopes, as strings
+      # (never constantized — the generator must not boot-order-couple to
+      # app models). On Rails 8, `Devise.mappings` itself force-loads the
+      # lazy routes (Devise 5.x, lib/devise.rb), so an empty hash genuinely
+      # means "no devise_for drawn yet" — nothing to validate against.
+      def devise_auth_class_names
+        return [] unless devise_detected?
+
+        ::Devise.mappings.values.map { |mapping| mapping.class_name.to_s }.uniq.sort
+      rescue StandardError
+        []
+      end
+
       def adopt_existing_table?
         return @adopt_existing_table if defined?(@adopt_existing_table)
 

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
@@ -79,16 +86,26 @@ class Create<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_ve
 
   private
 
-  # Honor the host's configured primary key type (uuid vs bigint). Reads the
-  # same setting `rails g model` uses, so an app generated with
+  # Honor the host's configured primary key type (uuid, string/ULID, bigint…).
+  # Reads the same setting `rails g model` uses, so an app generated with
   # `config.generators { |g| g.orm :active_record, primary_key_type: :uuid }`
   # gets uuid sessions tables and uuid foreign keys, automatically.
   def primary_and_foreign_key_types
     config = Rails.configuration.generators
     setting = config.options[config.orm][:primary_key_type]
-    primary_key_type = setting || :primary_key
-    foreign_key_type = setting || :bigint
-    [ primary_key_type, foreign_key_type ]
+    [ setting || :primary_key, reference_column_type(setting) ]
+  end
+
+  # Reference columns hold VALUES of the PK type, so the serial pseudo-types
+  # map to their plain integer equivalents — a `t.bigserial` reference would
+  # mint its own auto-increment sequence, which is exactly wrong for a
+  # foreign key. Everything else (uuid, string ULIDs, …) passes through.
+  def reference_column_type(setting)
+    case setting
+    when nil, :bigserial then :bigint
+    when :serial then :integer
+    else setting
+    end
   end
 
   # match? (not equality): PostGIS apps report adapter_name "PostGIS" and

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

@@ -85,17 +85,26 @@ class CreateSessionsEvents < ActiveRecord::Migration<%= migration_version %>
   def primary_and_foreign_key_types
     config = Rails.configuration.generators
     setting = config.options[config.orm][:primary_key_type]
-    primary_key_type = setting || :primary_key
-    foreign_key_type = setting || :bigint
-    [ primary_key_type, foreign_key_type ]
+    [ setting || :primary_key, reference_column_type(setting) ]
   end
 
   # session_id must match the sessions table's PRIMARY KEY type (uuid hosts
-  # store uuid linkage; bigint hosts store bigint).
+  # store uuid linkage, string/ULID hosts string, bigint hosts bigint).
   def session_id_column_type
     config = Rails.configuration.generators
-    setting = config.options[config.orm][:primary_key_type]
-    setting == :uuid ? :uuid : :bigint
+    reference_column_type(config.options[config.orm][:primary_key_type])
+  end
+
+  # Reference columns hold VALUES of the PK type, so the serial pseudo-types
+  # map to their plain integer equivalents — a `t.bigserial` reference would
+  # mint its own auto-increment sequence, which is exactly wrong for a
+  # foreign key. Everything else (uuid, string ULIDs, …) passes through.
+  def reference_column_type(setting)
+    case setting
+    when nil, :bigserial then :bigint
+    when :serial then :integer
+    else setting
+    end
   end
 
   # match? (not equality): PostGIS apps report adapter_name "PostGIS" and

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

@@ -36,8 +36,9 @@ module Sessions
       SKIP_ENV_KEY = "sessions.skip" # = Sessions::SKIP_ENV_KEY (set by Sessions.skip!)
 
       # The `throw :warden` message on revoked sessions — Devise's failure
-      # app surfaces it like :timeout/:session_limited (add a
-      # `devise.failure.session_revoked` translation for custom copy).
+      # app surfaces it like :timeout/:session_limited. The gem SHIPS the
+      # `devise.failure.session_revoked` copy (en + es, config/locales/);
+      # hosts override that key for custom wording.
       THROW_MESSAGE = :session_revoked
 
       module_function
@@ -107,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! }
 
@@ -185,11 +191,83 @@ module Sessions
         Sessions.safely("warden.adopt") do
           next unless row_accepts?(record)
 
-          row = create_row_for(record, warden, scope, suppress_login_event: true)
-          row&.update_columns(auth_detail: { "adopted" => true })
+          # 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.
+          #
+          # 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
+
+          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 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")
+
+        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
       # serialized user key and our token stash) — an admin scope riding
       # the same rack session, and unrelated host session data (carts,
@@ -225,7 +303,9 @@ module Sessions
           credentials = request.params[scope.to_s]
           next unless credentials.is_a?(Hash)
 
-          identity = credentials.values_at("email", "login", "username", "phone").compact.first
+          # `email_address` included: it's the omakase-era key, and Devise
+          # apps configure `authentication_keys = [:email_address]` too.
+          identity = credentials.values_at("email", "email_address", "login", "username", "phone").compact.first
 
           Sessions::Event.record_failure(
             request,

data/lib/sessions/classifier.rb

@@ -153,7 +153,13 @@ module Sessions
     end
 
     def method_for_strategy(strategy_name)
-      Sessions.config.strategy_methods.merge(STRATEGY_METHODS).each do |substring, method|
+      # Host entries are consulted FIRST (Hash#merge keeps the receiver's
+      # keys in front, so config substrings win the iteration order) and the
+      # block makes them WIN on a shared key too — a bare `merge` would let
+      # the built-in value silently clobber a host override of, say,
+      # "Rememberable".
+      mappings = Sessions.config.strategy_methods.merge(STRATEGY_METHODS) { |_key, custom, _builtin| custom }
+      mappings.each do |substring, method|
         return method if strategy_name.include?(substring)
       end
       nil

data/lib/sessions/models/concerns/model.rb

@@ -335,7 +335,14 @@ module Sessions
 
     def sessions_record_login
       Sessions.safely("record_login") do
-        next if sessions_suppress_login_event
+        if sessions_suppress_login_event
+          # Suppressed writes (adoption) skip the trail event, dedup and
+          # the new-device hook — but never the cap: it's the hard limit on
+          # LIVE rows, and a misbehaving client looping through adoption
+          # must hit it like everyone else.
+          sessions_enforce_cap!
+          next
+        end
 
         # Same browser signing in again (abandoned session, expired
         # remember-me, browser update — anything) replaces its old row

data/lib/sessions/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sessions
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  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