sessions 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 342cda70d0a4f3ed6b760d8dee9ff8dea68c97151d932e77c478474e216fe9ef
-  data.tar.gz: 6885d70e1cc6cbb5ebd9850c0b3f5d015ce22d1aeae5ba2968b0fd5bb33412e0
+  metadata.gz: 7a11c0aa8a096b0cc19e25a62967da2414cdf8732a2587cdd9a23ed7d989fd67
+  data.tar.gz: ea2e6a1fa8a96771886c86e74d6dfa391fffa4138e825006511222dd221652a4
 SHA512:
-  metadata.gz: a15d061c3b9397265aa2e7581ed5e06ce64ae50943a54aa71b45539dfe528153004422b9c782d1dcd5cd2b62a55edef8612ed26c4f8a55ee8d91c0379f3d9133
-  data.tar.gz: 4ecef8ccd7f56454a31feb6623245c38585dbae7601fdb681daa6192e764964a4c47300dc3b8aaaa6dbe2811246a66c304210d202e5a6f9e46c40085d34a246f
+  metadata.gz: d4aa37c48143f477dc820e85b8a44158682f4f40991411bb382af74fefd20d0001050dd2e7324830cea73e4edc459e252f3762aaea034bd4386bacda488f088c
+  data.tar.gz: d29228d847cb0acd7e6b348a872de1ae988afdbe5e70c69509f24a41aa18992109f57ba2964cddc66a08a6f09802cbdfe9a55d1a8d9fc4e6d01caeb92d9db6a8

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 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,11 @@ 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.
+
 ## 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/create_sessions.rb.erb

@@ -79,16 +79,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/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
@@ -185,11 +186,38 @@ module Sessions
         Sessions.safely("warden.adopt") do
           next unless row_accepts?(record)
 
+          # 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))
+            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 })
         end
       end
 
+      def recent_adopted_row(record, warden, scope)
+        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"] }
+      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 +253,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.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sessions
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - rameerez