sessions 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10c90937b69181aefb74b594f97b4f0142d75148aac755cb3e180866df74e249
-  data.tar.gz: 94219c51f790720e0bff485db1242f288b48161ffb5adab0bf066be22d189a30
+  metadata.gz: b7cca6c52bb926f1a07896ba44ec9cf3abba216dd8d49793febc1a405b27e6e1
+  data.tar.gz: 00770fa40d62a4e305df2b8a8530519873368fe097359d64d92fc8a19b522897
 SHA512:
-  metadata.gz: 978aea94d42c6259b8add5117692fbfd28ef071b5c9a078ec45900173bc76041481cba36433d7ce6eaf2d6dafa2d7cf1365e92c2b55a6c0946f19ca212d3c8dd
-  data.tar.gz: 4d956731a73bbc7750f67161f6a69acc9e7befa96c0ad8b5e02bfb7ccedbac4002cc2fa39b43ab0643c07a062c0d3e84315757d72ccac0a291ca1a0ad3cb09a2
+  metadata.gz: a3c27ee309a2d4a74c78e05b573068af4d5736cdaccf23e19f36565d58349ad550a344da601b1ce71c601e917c2c311405756b2af6cd7f314aeedc07502251c1
+  data.tar.gz: 4bd16a0366a8cdd01f69b426af63959d58f6e847b722e12f696ab196d3c9da3a540cec6ff6a7155040a51a823a9ba029f75828d04ffbb36f682b6bd9ed4687a8

data/Appraisals

@@ -7,16 +7,22 @@
 # fine on 7.1 because the concern only uses 7.1-era APIs).
 appraise "rails-7.1" do
   gem "rails", "~> 7.1.0"
+  # json 3 removed the quirks_mode option that ActiveSupport before 8.1 passes.
+  gem "json", "< 3"
 end
 
 appraise "rails-7.2" do
   gem "rails", "~> 7.2.0"
+  # json 3 removed the quirks_mode option that ActiveSupport before 8.1 passes.
+  gem "json", "< 3"
 end
 
 # The version that shipped `rails generate authentication` — the substrate
 # this gem decorates.
 appraise "rails-8.0" do
   gem "rails", "~> 8.0.0"
+  # json 3 removed the quirks_mode option that ActiveSupport before 8.1 passes.
+  gem "json", "< 3"
 end
 
 # The latest Rails — also adds the rate_limit.action_controller notification

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.3.0 (2026-10-18)
+
+Adds re-authentication assertions. This release is additive: it needs no migration, and existing installs change nothing until they call the new API.
+
+- **Record a fresh re-authentication on the session row.** Call `session.reauthenticated!(method: :password)` after your own credential check succeeds. The gem never checks credentials. The state lives in `auth_detail`, so no migration is needed. `session.reauthenticated_within?(5.minutes)` tells whether it is recent. `session.reauthenticated_at` and `session.reauthentication_method` read it back. An ended or expired session is never recent. Both methods reload the row under a lock, so a revocation in another process counts.
+- **Issue a short-lived signed assertion of it.** `session.reauthentication_assertion(audience:, purpose:)` returns a signed token for one audience and one purpose. It raises `Sessions::Reauthentication::NotRecent` when the re-authentication is not recent.
+- **Verify the assertion in another service.** `Sessions::Reauthentication.verify(token, audience:, key:, subject:, purpose:, max_age:)` returns an `Assertion` or `nil`. The other service needs only the shared key and `require "sessions/reauthentication"`: no database, no cookie, no models. `verify` refuses another key, audience, subject or purpose, a changed or expired token, a timestamp more than 30 seconds in the future, and a re-authentication older than `max_age`.
+- **Subjects carry the owner class.** A subject is `"<owner class>:<id>"`, so owners of two classes with the same id never match. A stored polymorphic type is resolved to its full class name, also when `store_full_class_name` is false.
+- **Replay protection is possible.** Each assertion has a unique `jti` and an `expires_at`. To refuse replays, record each accepted `jti` until `expires_at`.
+- **Opt-in controller helpers.** `include Sessions::ReauthenticationHelpers` gives `record_sessions_reauthentication!(owner, method:)`, `sessions_reauthenticated?(owner)` and `sessions_reauthentication_assertion(owner, audience:, purpose:)`. They act only on a current session of the named owner. Use `scope:` for apps with more than one Warden scope.
+- **New configuration.** `reauthentication_key` (a String of 32 bytes or more, or a callable), `reauthentication_window` (default 5 minutes) and `reauthentication_assertion_ttl` (default 1 minute).
+
+## 0.2.2 (2026-07-06)
+
+Closes the revocation-semantics gaps found auditing the 0.2.x lifecycle model against production data.
+
+- **Explicit revocations now kick tokenless remembered devices too.** Remember-me restores reattach to their device row as a tokenless tracking hint (0.1.3 semantics). Hints still never turn absence or housekeeping into a logout — but when the authenticated owner, the signed browser-continuity cookie, and the row all agree it is the same device AND that row was explicitly ended (`admin_revoked`, `user_revoked`, `logout_everywhere`, …), the next request now kicks, exactly as the admin/devices UI promises. Previously such devices kept their live host session until it expired naturally (remember-me revival was already blocked; the active rack session was not).
+- **`Sessions.current` resolves hint-tracked rows.** Remembered devices get their "this device" badge back on the devices page — and the page's refuse-to-revoke-current guard (plus `revoke_other_sessions!(current:)`) works for them again. The hint is corroborated against the signed browser-continuity cookie before being trusted.
+- **Sweep expiry no longer masquerades as revocation.** `Sessions.sweep!` ends idle/over-age sessions with `end!(reason: :expired)` (audit event written, kicks on resume) instead of `revoke!` — no more account-wide remember-me rotation or `on_session_revoked` fire for timeout policy, matching the adapter's inline expiry and Devise's own timeoutable semantics.
+- **Plain callable-object hooks receive `on_repeated_failed_logins` again.** 0.2.1's keyword-slicing dispatch introspected `#parameters`, which only Procs and Methods expose; a class-based hook (`def call(identity:, count:, event:)`) silently lost the alert. Dispatch now introspects `#method(:call)` for such objects.
+
+## 0.2.1 (2026-07-03)
+
+- Prevent fresh-install and adopted-table migrations from creating the `ended_by` polymorphic index twice.
+- Preserve custom string/ULID primary-key types in the 0.2 lifecycle upgrade migration.
+- Make generated Madmin revocation controls lifecycle-aware so ended rows cannot report a second successful revoke.
+- Correct the 0.2 documentation for `event.session`: it resolves retained lifecycle rows after logout/revocation and becomes `nil` only after hard deletion.
+- Document that Devise's `bypass_sign_in` skips the Warden callbacks required to register a new session.
+- Bound the device parser dependency to the tested `browser` 6.x API line.
+- Let `config.layout` be a callable (`->(controller) { ... }`) for hosts that switch layouts between web and native shells.
+- Pass `user:` (resolved best-effort, never persisted on the failed event) to `on_repeated_failed_logins` when the hook opts into the keyword.
+- Add `sessions_devices_for(user)` / `sessions_history_for(user)` helpers so ejected/custom views keep live-device and enumeration-safe history semantics in one place.
+- Add `rails generate sessions:madmin --user-panel` for the repeated per-user admin security panel concern/view.
+
 ## 0.2.0 (2026-06-21)
 
 Lifecycle-row rewrite and auth-safety correction for the Hotwire Native / Devise remember-me hardening introduced in 0.1.3.

data/README.md

@@ -98,7 +98,7 @@ That's it. Every sign-in from now on lands on the devices page and in the trail
 
 ### Upgrading
 
-Existing apps upgrading from 0.1.0, 0.1.1, or 0.1.2 should copy the upgrade migrations and run them:
+Existing apps upgrading from any 0.1.x release should copy the upgrade migrations and run them:
 
 ```bash
 rails generate sessions:upgrade
@@ -141,7 +141,7 @@ Three ways to ship it, pick your layer:
    (Revoke buttons render when the engine is mounted; without it you get the read-only registry.)
 3. **Eject and restyle** — `rails generate sessions:views` copies every template into `app/views/sessions/`, where your copies shadow the gem's automatically (the Devise move).
 
-The engine inherits from your `ApplicationController` (configurable via `config.parent_controller`), so your layout, auth and locale apply automatically. The current session is resolved on both stacks; destructive actions can be gated behind your own sudo/password-confirm flow with `config.require_reauthentication`. One heads-up: if your app layout leans heavily on host route helpers, isolated-engine rendering means those resolve through `main_app.*` — rendering the partials in your own page (layer 2) sidesteps the whole topic.
+The engine inherits from your `ApplicationController` (configurable via `config.parent_controller`), so your layout, auth and locale apply automatically. `config.layout` can be a string/symbol or a callable (`->(controller) { controller.hotwire_native_app? ? "app" : "web" }`) when native and browser shells differ. The current session is resolved on both stacks; destructive actions can be gated behind a sudo/password-confirm flow with `config.require_reauthentication`. One heads-up: if your app layout leans heavily on host route helpers, isolated-engine rendering means those resolve through `main_app.*` — rendering the partials in your own page (layer 2) sidesteps the whole topic.
 
 A hard rule the page enforces: **you can never touch a session you don't own** (foreign ids 404 — existence never leaks), and the current session is never revocable from the page (that's what sign-out is for).
 
@@ -152,7 +152,7 @@ A hard rule the page enforces: **you can never touch a session you don't own** (
 ```ruby
 Sessions::Event.logins / .failed_logins / .logouts / .revocations / .expirations
 Sessions::Event.recent.last_days(90).for_ip("203.0.113.7")
-event.session       # the live row it created — nil once revoked (that's the point)
+event.session       # the lifecycle row it created (live or explicitly ended)
 event.new_device?   # flagged when the login matched no prior device
 ```
 
@@ -212,6 +212,8 @@ Sessions.record_failed_attempt(request, scope: :user, identity: params[:email],
 
 Custom Warden strategies map with `config.strategy_methods = { "OtpAuthenticatable" => :otp }`. Everything else is `unknown` — the gem never guesses.
 
+Devise's `bypass_sign_in` writes directly to its session serializer and deliberately skips Warden callbacks. Do not use it to establish a new login that must appear in the registry; use `sign_in` instead. It remains appropriate for refreshing the serialization of an already-tracked login.
+
 ### Two-factor flows (TOTP apps, security keys, Touch ID)
 
 Every mainstream Ruby 2FA setup creates the session at **full** authentication — we verified each one against its source — so the registry and trail stay correct without configuration. What varies is the labeling, and where a recipe is needed it's one line:
@@ -278,13 +280,13 @@ Per-attempt alerts are notification fatigue *and* an abuse vector (an attacker h
 
 ```ruby
 config.repeated_failed_logins = { threshold: 5, within: 15.minutes }
-config.on_repeated_failed_logins = ->(identity:, count:, event:) do
-  user = User.find_by(email: identity) or next  # identity is AS TYPED — may match no account
+config.on_repeated_failed_logins = ->(identity:, count:, event:, user:) do
+  next unless user # nil when the typed identity matches no account
   SecurityMailer.with(user: user, event: event).repeated_failed_logins.deliver_later
 end
 ```
 
-The `event` is the attempt that tripped the threshold — IP, location and device included. This complements (not replaces) Devise's `:lockable` and Rails 8's `rate_limit`: they *stop* the attacker; this tells the *user*.
+The `event` is the attempt that tripped the threshold — IP, location and device included. `user:` is resolved in memory for the hook but still not persisted on failed events, preserving the no-enumeration data model. Existing hooks that only accept `identity:, count:, event:` keep working. This complements (not replaces) Devise's `:lockable` and Rails 8's `rate_limit`: they *stop* the attacker; this tells the *user*.
 
 ## 🌍 Geolocation (via `trackdown`, soft dependency)
 
@@ -353,7 +355,55 @@ Scopes are the admin product — `Sessions::Event.failed_logins.last_24_hours.gr
 rails generate sessions:madmin
 ```
 
-…generates the two resources (the lifecycle registry with a per-row **Revoke session** action, and the login trail with its triage scopes as filters) plus their controllers, with madmin's two namespacing footguns pre-solved. The generated files use only stock madmin APIs and are yours to restyle. For a per-user security panel (devices + trail on the user's show page), load `user.sessions.live.by_recency` and `user.session_events.recent` in a member action — including the user's *failed* attempts by matching `Sessions::Event.where(identity: Sessions::Event.normalize_identity(user.email))` (failures never link to accounts; matching the signed-in user's own identity is the safe way to show them).
+…generates the two resources (the lifecycle registry with a per-row **Revoke session** action, and the login trail with its triage scopes as filters) plus their controllers, with madmin's two namespacing footguns pre-solved. The generated files use only stock madmin APIs and are yours to restyle.
+
+For the per-user security panel that most admin dashboards want (live devices + that user's login trail), run:
+
+```bash
+rails generate sessions:madmin --user-panel
+```
+
+That adds a reusable `Sessions::MadminUserPanel` concern and `app/views/madmin/users/sessions.html.erb`. Include the concern in `Madmin::UsersController`, add the printed member routes, and add a `member_action` link from your `UserResource`.
+
+## 🔐 Re-authentication assertions ("prove you just typed your password")
+
+Some actions deserve a fresh password: approving a payment, changing a payout account, confirming something another service will act on. `sessions` records that fresh re-authentication on the session row and can hand out a short-lived, signed **assertion** of it that another service verifies with a shared key — no database, no cookie, no models on the other side.
+
+```ruby
+# config/initializers/sessions.rb
+Sessions.configure do |config|
+  config.reauthentication_key = Rails.application.credentials.reauthentication_key # >= 32 bytes, shared with the verifier
+end
+
+# Your controller, after YOUR check succeeded (the gem never checks credentials):
+class ReauthenticationsController < ApplicationController
+  include Sessions::ReauthenticationHelpers
+
+  def create
+    return render(:new, status: :unprocessable_entity) unless current_user.valid_password?(params[:password])
+
+    record_sessions_reauthentication!(current_user, method: :password)
+    token = sessions_reauthentication_assertion(current_user, audience: "payments", purpose: "payout:42")
+    redirect_to payments_service_url(assertion: token), allow_other_host: true
+  end
+end
+```
+
+The other service needs only `require "sessions/reauthentication"` and the key:
+
+```ruby
+assertion = Sessions::Reauthentication.verify(token, audience: "payments", key: ENV["REAUTH_KEY"],
+                                              subject: "User:#{user_id}", purpose: "payout:42", max_age: 5.minutes)
+assertion&.method      # => "password"
+assertion&.jti         # unique per assertion
+assertion&.expires_at  # to refuse replays, check-and-insert each accepted jti and keep it until this time
+```
+
+The helpers take the owner whose credential you checked and act only on a current session of that owner (`scope:` picks the Warden scope when you sign in more than one). The subject of an assertion is the owner's class and id (`"User:42"`), so two owner classes with the same id never match; `verify` accepts the record or that string as `subject:`.
+
+On the model: `session.reauthenticated!(method: :password)`, `session.reauthenticated_within?(5.minutes)`, `session.reauthenticated_at`, and `session.reauthentication_assertion(audience:, purpose:)` (raises `Sessions::Reauthentication::NotRecent` without a recent re-authentication). An ended or expired session is never recent, and both methods reload the row under a lock first, so a revocation in another process counts. The state lives in `auth_detail`, so no migration is needed.
+
+What an assertion is not: a session or a bearer login. It expires after `reauthentication_assertion_ttl` (default one minute), it names one audience and one purpose, and `verify` returns `nil` for anything else — another key, audience, subject or purpose, a tampered or expired token, a timestamp more than 30 seconds in the future, or a re-authentication older than `max_age`.
 
 ## 🧹 Retention & the sweep
 
@@ -418,8 +468,11 @@ Sessions.configure do |config|
   config.parent_controller       = "::ApplicationController"
   config.current_user_method     = :current_user   # chain: this → current_user → Current.session&.user
   config.authenticate_method     = :authenticate_user!
-  config.layout                  = nil             # nil inherits the parent controller's layout
+  config.layout                  = nil             # nil, "app", or ->(controller) { ... }
   config.require_reauthentication = nil            # ->(controller) { ... } sudo gate
+  config.reauthentication_key    = nil             # shared secret (>= 32 bytes) for re-authentication assertions
+  config.reauthentication_window = 5.minutes       # how recent a re-authentication must be to assert it
+  config.reauthentication_assertion_ttl = 1.minute # how long an issued assertion stays valid
   config.session_class           = "Session"
   config.strategy_methods        = {}              # { "OtpAuthenticatable" => :otp }
 end

data/app/controllers/sessions/application_controller.rb

@@ -112,7 +112,8 @@ module Sessions
     end
 
     def sessions_layout
-      Sessions.config.layout
+      configured = Sessions.config.layout
+      configured.respond_to?(:call) ? configured.call(self) : configured
     end
 
     # The optional sudo gate (ASVS 3.3.4's "having re-entered login

data/app/helpers/sessions/engine_helper.rb

@@ -45,6 +45,29 @@ module Sessions
       EVENT_ICON_NAMES.fetch(event.event.to_s, "information-circle")
     end
 
+    # Semantic queries for custom/ejected views. Keep liveness and
+    # enumeration-safe history semantics in the gem, so host styling changes
+    # don't accidentally regress the data contract.
+    def sessions_devices_for(user, limit: nil)
+      scope = if user.respond_to?(:sessions)
+                user.sessions.live.by_recency
+              else
+                Sessions.session_model.live.where(user: user).by_recency
+              end
+      limit ? scope.limit(limit) : scope
+    end
+
+    def sessions_history_for(user, limit: nil)
+      scope = if user.respond_to?(:session_history)
+                user.session_history.recent
+              elsif user.respond_to?(:session_events)
+                user.session_events.recent
+              else
+                Sessions::Event.where(authenticatable: user).recent
+              end
+      limit ? scope.limit(limit) : scope
+    end
+
     # "Active now" within the touch window, else "Active 3 minutes ago".
     def sessions_last_active_in_words(session)
       # active_now? owns the window (config.touch_every) — the badge can't

data/app/views/sessions/_devices.html.erb

@@ -1,13 +1,13 @@
 <%# The live device registry — renderable from the engine OR straight from %>
 <%# any host view: render "sessions/devices", user: current_user           %>
 <%# Locals:                                                                 %>
-<%#   sessions:        the rows to render (defaults to user.sessions)       %>
+<%#   sessions:        the rows to render (defaults via sessions_devices_for)%>
 <%#   user:            whose devices (only needed when sessions: isn't given)%>
 <%#   current_session: the row serving this request (badged, not revocable) %>
 <%
   current_session = local_assigns[:current_session] || Sessions.current(request)
   sessions = local_assigns[:sessions] ||
-             local_assigns[:user]&.sessions&.live&.by_recency&.to_a ||
+             (sessions_devices_for(local_assigns[:user]).to_a if local_assigns[:user] && respond_to?(:sessions_devices_for)) ||
              []
   routes = sessions_engine_routes if respond_to?(:sessions_engine_routes)
 %>

data/app/views/sessions/_history.html.erb

@@ -1,12 +1,12 @@
 <%# The login-activity trail — renderable from any host view too:          %>
 <%#   render "sessions/history", user: current_user, limit: 10              %>
 <%# Locals:                                                                 %>
-<%#   events: the trail rows (defaults to user.session_events.recent)       %>
+<%#   events: the trail rows (defaults via sessions_history_for)            %>
 <%#   user:   whose history (only needed when events: isn't given)          %>
 <%#   limit:  cap when deriving from user (default 10)                      %>
 <%
   events = local_assigns[:events] ||
-           local_assigns[:user]&.session_events&.recent&.limit(local_assigns.fetch(:limit, 10)) ||
+           (sessions_history_for(local_assigns[:user], limit: local_assigns.fetch(:limit, 10)) if local_assigns[:user] && respond_to?(:sessions_history_for)) ||
            []
 %>
 <% if events.respond_to?(:empty?) && events.empty? %>

data/gemfiles/rails_7.1.gemfile

@@ -4,6 +4,7 @@ source "https://rubygems.org"
 
 gem "rake", "~> 13.0"
 gem "rails", "~> 7.1.0"
+gem "json", "< 3"
 
 group :development do
   gem "appraisal"

data/gemfiles/rails_7.2.gemfile

@@ -4,6 +4,7 @@ source "https://rubygems.org"
 
 gem "rake", "~> 13.0"
 gem "rails", "~> 7.2.0"
+gem "json", "< 3"
 
 group :development do
   gem "appraisal"

data/gemfiles/rails_8.0.gemfile

@@ -4,6 +4,7 @@ source "https://rubygems.org"
 
 gem "rake", "~> 13.0"
 gem "rails", "~> 8.0.0"
+gem "json", "< 3"
 
 group :development do
   gem "appraisal"

data/lib/generators/sessions/madmin_generator.rb

@@ -20,6 +20,9 @@ module Sessions
 
       desc "Generate Madmin resources + controllers for sessions and the login trail"
 
+      class_option :user_panel, type: :boolean, default: false,
+                                desc: "Also generate a per-user Sessions panel concern and view"
+
       def check_for_madmin!
         return if madmin_available?
 
@@ -43,6 +46,13 @@ module Sessions
         template "session_events_controller.rb", "app/controllers/madmin/session_events_controller.rb"
       end
 
+      def create_user_panel
+        return unless options[:user_panel]
+
+        copy_file "user_panel/madmin_user_panel.rb", "app/controllers/concerns/sessions/madmin_user_panel.rb"
+        copy_file "user_panel/sessions.html.erb", "app/views/madmin/users/sessions.html.erb"
+      end
+
       def display_post_install_message
         say "\n🔐 Madmin resources for sessions installed.", :green
         say "\nTo complete the setup:"
@@ -70,9 +80,15 @@ module Sessions
         say "       end"
 
         say "\n  3. (Optional) For a per-user panel (devices + trail on the user's"
-        say "     show page), add a member action to your users controller that"
-        say "     loads `user.sessions.live.by_recency` and `user.session_history.recent`"
-        say "     — the README's Admin section has the full recipe."
+        say "     show page), re-run with --user-panel, include"
+        say "     `Sessions::MadminUserPanel` in Madmin::UsersController, and add:"
+        say ""
+        say "       resources :users do"
+        say "         member do"
+        say "           get :sessions"
+        say "           post :revoke_all_sessions"
+        say "         end"
+        say "       end"
 
         say "\nRevoking from the index ends the row in place: that device is signed out"
         say "on its very next matching request, and the revocation lands in the trail"

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

@@ -23,10 +23,9 @@ class AddSessionsLifecycleTo<%= table_name.camelize %> < ActiveRecord::Migration
   def reference_column_type
     config = Rails.configuration.generators
     case config.options[config.orm][:primary_key_type]
-    when :uuid then :uuid
-    when :string then :string
-    when :integer, :serial then :integer
-    else :bigint
+    when nil, :bigserial then :bigint
+    when :serial then :integer
+    else config.options[config.orm][:primary_key_type]
     end
   end
 

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

@@ -70,7 +70,9 @@ class AddSessionsColumnsTo<%= table_name.camelize %> < ActiveRecord::Migration<%
       # truth for whether a session should still be accepted.
       t.datetime :ended_at
       t.string :ended_reason
-      t.references :ended_by, polymorphic: true, type: foreign_key_type
+      # The explicit index below keeps the generated name consistent across
+      # fresh installs and upgrades. Avoid the implicit duplicate index.
+      t.references :ended_by, polymorphic: true, type: foreign_key_type, index: false
       t.send(json_column_type, :ended_metadata)
     end
 

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

@@ -78,7 +78,10 @@ class Create<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_ve
       # thing a Devise/Warden request is allowed to enforce.
       t.datetime :ended_at
       t.string :ended_reason
-      t.references :ended_by, polymorphic: true, type: foreign_key_type
+      # The explicit index below keeps the generated name consistent across
+      # create-table and upgrade paths. `references` indexes by default, so
+      # disable that implicit index to avoid two identical indexes.
+      t.references :ended_by, polymorphic: true, type: foreign_key_type, index: false
       t.send(json_column_type, :ended_metadata)
 
       t.timestamps

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

@@ -136,11 +136,12 @@ Sessions.configure do |config|
   # end
   #
   # Someone crossed the repeated_failed_logins threshold (see BEHAVIOR
-  # above). The identity is the email AS TYPED — it may match no account,
-  # so resolve it yourself before notifying:
+  # above). The event still stores no account link for failures; user: is a
+  # best-effort in-memory resolution for this hook and nil for unknown
+  # identities:
   #
-  # config.on_repeated_failed_logins = ->(identity:, count:, event:) do
-  #   user = User.find_by(email: identity) or next
+  # config.on_repeated_failed_logins = ->(identity:, count:, event:, user:) do
+  #   next unless user
   #   SecurityMailer.with(user: user, event: event).repeated_failed_logins.deliver_later
   # end
   #
@@ -172,10 +173,10 @@ Sessions.configure do |config|
   # config.authenticate_method = :authenticate_user!
   #
   # Render the devices page with a specific layout (nil inherits whatever
-  # your parent controller uses — set this if your signed-in surfaces use a
-  # different layout, e.g. "app"):
+  # your parent controller uses). Use a callable when web/native shells differ:
   #
   # config.layout = nil
+  # config.layout = ->(controller) { controller.hotwire_native_app? ? "app" : "web" }
   #
   # Optional sudo gate before destructive actions on the devices page (ASVS
   # 3.3.4's "having re-entered login credentials"). The action runs only

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

@@ -2,8 +2,9 @@
 
 # Device lifecycle registry (sessions gem): one row = one signed-in device.
 # `ended_at: nil` is the live set that can act on your app right now; ended
-# rows stay around as durable state/audit context until retention or account
-# erasure removes them. The append-only history lives in Sessions::Event.
+# rows stay around as durable revocation state until account erasure or
+# explicit host cleanup removes them. The append-only history lives in
+# Sessions::Event.
 class SessionResource < Madmin::Resource
   model <%= session_class %>
 
@@ -65,10 +66,12 @@ class SessionResource < Madmin::Resource
   # attributed to the admin, and rotates the user's remember-me credentials
   # in Devise mode. The device is signed out on its next matching request.
   member_action do
-    button_to "Revoke session",
-      main_app.revoke_madmin_session_path(@record),
-      method: :post,
-      class: "rounded-md bg-white px-3 py-2 text-sm font-semibold text-red-700 shadow-sm ring-1 ring-inset ring-red-300 hover:bg-red-50",
-      data: { turbo_confirm: "Revoke this session? The device will be signed out on its next request." }
+    if @record.live?
+      button_to "Revoke session",
+        main_app.revoke_madmin_session_path(@record),
+        method: :post,
+        class: "rounded-md bg-white px-3 py-2 text-sm font-semibold text-red-700 shadow-sm ring-1 ring-inset ring-red-300 hover:bg-red-50",
+        data: { turbo_confirm: "Revoke this session? The device will be signed out on its next request." }
+    end
   end
 end

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

@@ -10,12 +10,16 @@ module Madmin
       session_row = <%= session_class %>.find(params[:id])
       device = session_row.device_name
 
-      session_row.revoke!(reason: :admin_revoked, by: current_user)
-      flash[:notice] = "Session revoked (#{device}). The device will be signed out on its next request."
+      if session_row.live?
+        session_row.revoke!(reason: :admin_revoked, by: current_user)
+        flash[:notice] = "Session revoked (#{device}). The device will be signed out on its next request."
+      else
+        flash[:alert] = "That session had already ended (#{device}). There is no live device to sign out."
+      end
 
       redirect_back fallback_location: main_app.madmin_sessions_path
     rescue ActiveRecord::RecordNotFound
-      flash[:alert] = "That session no longer exists (probably already revoked)."
+      flash[:alert] = "That session no longer exists."
       redirect_back fallback_location: main_app.madmin_sessions_path
     end
 

data/lib/generators/sessions/templates/madmin/user_panel/madmin_user_panel.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Sessions
+  # Optional per-user Madmin panel actions. Include this in
+  # Madmin::UsersController, then draw the routes printed by
+  # `rails generate sessions:madmin --user-panel`.
+  module MadminUserPanel
+    extend ActiveSupport::Concern
+
+    SESSION_EVENTS_PER_PAGE = 30
+
+    def sessions
+      @user = User.find(params[:id])
+      @sessions = @user.sessions.live.by_recency.to_a
+      events = @user.session_history.recent
+
+      @failed_last_24h = events.failed_logins.last_24_hours.count
+      if respond_to?(:pagy, true)
+        @pagy, @events = pagy(events, limit: SESSION_EVENTS_PER_PAGE)
+      else
+        @events = events.limit(SESSION_EVENTS_PER_PAGE)
+      end
+    rescue StandardError => e
+      raise unless defined?(::Pagy::OptionError) && e.is_a?(::Pagy::OptionError)
+
+      @pagy, @events = pagy(events, page: 1, limit: SESSION_EVENTS_PER_PAGE)
+    end
+
+    # Account-takeover response: revoke every live row with admin attribution.
+    # Each row writes its own `revoked` event and, in Devise mode, rotates
+    # remember-me credentials so a long-lived cookie cannot revive the device.
+    def revoke_all_sessions
+      user = User.find(params[:id])
+      count = user.sessions.live.count
+
+      user.revoke_all_sessions!(by: current_user)
+      flash[:notice] = "#{count} #{"session".pluralize(count)} revoked. " \
+                       "Every device will be signed out on its next request."
+
+      redirect_to main_app.sessions_madmin_user_path(user)
+    end
+  end
+end

data/lib/generators/sessions/templates/madmin/user_panel/sessions.html.erb

@@ -0,0 +1,133 @@
+<% content_for :title, "Sessions - #{@user.try(:email) || @user.try(:email_address) || @user.id}" %>
+
+<div class="mx-auto w-full max-w-6xl px-4 py-6">
+  <header class="mb-6 flex flex-wrap items-center justify-between gap-4">
+    <div>
+      <p class="text-sm text-gray-500">
+        <%= link_to "Users", madmin_users_path, class: "hover:text-gray-700" %>
+        <span class="mx-1 text-gray-400">/</span>
+        <%= link_to @user.try(:email) || @user.try(:email_address) || @user.id, madmin_user_path(@user), class: "hover:text-gray-700" %>
+      </p>
+      <h1 class="mt-1 text-2xl font-semibold text-gray-900">Sessions &amp; devices</h1>
+    </div>
+
+    <div class="flex items-center gap-2">
+      <%= link_to "Back to user", madmin_user_path(@user),
+            class: "rounded-md bg-white px-3 py-2 text-sm font-semibold text-gray-700 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-50" %>
+      <% if @sessions.any? %>
+        <%= button_to "Revoke all sessions", revoke_all_sessions_madmin_user_path(@user),
+              method: :post,
+              class: "rounded-md bg-white px-3 py-2 text-sm font-semibold text-red-700 shadow-sm ring-1 ring-inset ring-red-300 hover:bg-red-50",
+              data: { turbo_confirm: "Revoke ALL #{@sessions.size} sessions? Every device will be signed out on its next request." } %>
+      <% end %>
+    </div>
+  </header>
+
+  <div class="mb-6 grid grid-cols-1 gap-4 sm:grid-cols-3">
+    <div class="rounded-lg border border-gray-200 bg-white p-4">
+      <p class="text-xs font-medium uppercase text-gray-500">Live sessions</p>
+      <p class="mt-1 text-2xl font-semibold text-gray-900"><%= @sessions.size %></p>
+    </div>
+    <div class="rounded-lg border border-gray-200 bg-white p-4">
+      <p class="text-xs font-medium uppercase text-gray-500">Last activity</p>
+      <p class="mt-1 text-2xl font-semibold text-gray-900">
+        <% if (latest = @sessions.filter_map(&:last_active_at).max) %>
+          <%= time_ago_in_words(latest) %> ago
+        <% else %>
+          -
+        <% end %>
+      </p>
+    </div>
+    <div class="rounded-lg border border-gray-200 bg-white p-4">
+      <p class="text-xs font-medium uppercase text-gray-500">Failed logins (24h)</p>
+      <p class="mt-1 text-2xl font-semibold <%= @failed_last_24h.positive? ? "text-red-700" : "text-gray-900" %>">
+        <%= @failed_last_24h %>
+      </p>
+    </div>
+  </div>
+
+  <section class="mb-6 overflow-hidden rounded-lg border border-gray-200 bg-white">
+    <header class="border-b border-gray-200 px-6 py-4">
+      <h2 class="text-base font-semibold text-gray-900">Live devices</h2>
+    </header>
+
+    <% if @sessions.any? %>
+      <ul class="divide-y divide-gray-100">
+        <% @sessions.each do |session_row| %>
+          <li class="flex items-start justify-between gap-4 px-6 py-4">
+            <div class="min-w-0">
+              <p class="text-sm font-medium text-gray-900">
+                <%= link_to session_row.device_name, madmin_session_path(session_row), class: "hover:underline" %>
+              </p>
+              <p class="mt-1 text-xs text-gray-500">
+                <% bits = [] %>
+                <% bits << session_row.location if session_row.location %>
+                <% bits << "IP #{session_row.last_seen_ip || session_row.ip_address}" if session_row.last_seen_ip || session_row.ip_address %>
+                <% bits << "via #{session_row.auth_method_label}" if session_row.auth_method_label %>
+                <% bits << "last seen #{time_ago_in_words(session_row.last_active_at)} ago" if session_row.last_active_at %>
+                <%= bits.join(" - ") %>
+              </p>
+            </div>
+
+            <%= button_to "Revoke", revoke_madmin_session_path(session_row),
+                  method: :post,
+                  class: "rounded-md bg-white px-3 py-2 text-sm font-semibold text-red-700 shadow-sm ring-1 ring-inset ring-red-300 hover:bg-red-50",
+                  data: { turbo_confirm: "Revoke #{session_row.device_name}?" } %>
+          </li>
+        <% end %>
+      </ul>
+    <% else %>
+      <div class="px-6 py-10 text-center text-sm text-gray-500">No live sessions.</div>
+    <% end %>
+  </section>
+
+  <section class="overflow-hidden rounded-lg border border-gray-200 bg-white">
+    <header class="border-b border-gray-200 px-6 py-4">
+      <h2 class="text-base font-semibold text-gray-900">Login activity</h2>
+    </header>
+
+    <% if @events.any? %>
+      <div class="overflow-x-auto">
+        <table class="min-w-full divide-y divide-gray-200 text-sm">
+          <thead class="bg-gray-50 text-xs uppercase text-gray-500">
+            <tr>
+              <th class="px-4 py-2 text-left font-medium">When</th>
+              <th class="px-4 py-2 text-left font-medium">Event</th>
+              <th class="px-4 py-2 text-left font-medium">Device</th>
+              <th class="px-4 py-2 text-left font-medium">IP / Location</th>
+              <th class="px-4 py-2 text-left font-medium">Via</th>
+            </tr>
+          </thead>
+          <tbody class="divide-y divide-gray-100">
+            <% @events.each do |event| %>
+              <tr>
+                <td class="whitespace-nowrap px-4 py-3 align-top">
+                  <%= l(event.occurred_at, format: :short) %>
+                </td>
+                <td class="px-4 py-3 align-top">
+                  <%= event.label %>
+                  <% if event.reason %>
+                    <div class="text-xs text-gray-500"><%= event.reason_label %></div>
+                  <% end %>
+                </td>
+                <td class="px-4 py-3 align-top"><%= event.device_name %></td>
+                <td class="whitespace-nowrap px-4 py-3 align-top">
+                  <%= [ event.ip_address, event.location ].compact.join(" - ").presence || "-" %>
+                </td>
+                <td class="px-4 py-3 align-top"><%= event.auth_method_label || "-" %></td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      </div>
+
+      <% if defined?(@pagy) && @pagy.respond_to?(:last) && @pagy.last > 1 %>
+        <div class="border-t border-gray-100 bg-gray-50 px-6 py-3">
+          <%= render "madmin/shared/pagination", pagy: @pagy %>
+        </div>
+      <% end %>
+    <% else %>
+      <div class="px-6 py-10 text-center text-sm text-gray-500">No login activity.</div>
+    <% end %>
+  </section>
+</div>

data/lib/sessions/adapters/warden.rb

@@ -202,12 +202,21 @@ module Sessions
             # v0.1.3 intentionally reattached remember-me restores to an
             # existing device row without writing another login event, storing
             # [row_id, nil] in Warden. That is fine as a tracking hint, but it
-            # must never become an auth/liveness check. Touch when the signed
-            # browser-continuity cookie still agrees; otherwise clear only the
-            # gem's tracking key and let Devise/Rails keep owning auth.
+            # must never become an auth/liveness check FROM ABSENCE: missing
+            # rows, mismatched cookies and quiet housekeeping all fail open.
+            # An EXPLICIT ending is different — when the authenticated owner,
+            # the signed browser-continuity cookie and the row all agree this
+            # is the same device, and that row was deliberately ended
+            # (admin/user revoke, sign-out-everywhere), the revocation must
+            # mean what the UI promised: signed out on its next request.
+            # Housekeeping reasons (superseded) never kick and fall through
+            # to the live-replacement reattach below.
             # Source: https://github.com/rameerez/sessions/blob/v0.1.3/CHANGELOG.md
-            if existing_row_session?(found, record, scope, warden.request) && found.live?
+            same_device = existing_row_session?(found, record, scope, warden.request)
+            if same_device && found.live?
               Sessions.safely("warden.remembered_existing.touch") { found.touch_last_seen!(warden.request) }
+            elsif same_device && found.sessions_kicks_on_resume?
+              kick!(warden, scope)
             elsif (replacement = live_replacement_for(found, record, scope, warden.request))
               attach_existing_row(replacement, warden, scope)
             else

data/lib/sessions/configuration.rb

@@ -181,7 +181,7 @@ module Sessions
     # whatever layout the parent controller resolves — usually the host's
     # `application` layout. Set it when your signed-in surfaces render with
     # a different one (e.g. "app").
-    attr_accessor :layout
+    attr_reader :layout
 
     # ->(controller) — optional sudo gate run before destructive actions on
     # the devices page (ASVS 3.3.4's "having re-entered login credentials").
@@ -192,6 +192,12 @@ module Sessions
     # never through to the destructive action).
     attr_reader :require_reauthentication
 
+    # Re-authentication assertions (Sessions::Reauthentication): the shared
+    # secret that signs them (a String of at least 32 bytes, or a callable
+    # returning one; nil disables issuing), how recent a re-authentication
+    # must be to issue one, and how long an issued assertion stays valid.
+    attr_reader :reauthentication_key, :reauthentication_window, :reauthentication_assertion_ttl
+
     # The host's session-of-record model, as a string. "Session" matches
     # both the Rails 8 generator and the model our install generator writes
     # in Devise mode. Escape hatch for apps with a conflicting legacy
@@ -239,6 +245,9 @@ module Sessions
       @authenticate_method = :authenticate_user!
       @layout = nil
       @require_reauthentication = nil
+      @reauthentication_key = nil
+      @reauthentication_window = 5.minutes
+      @reauthentication_assertion_ttl = 1.minute
       @session_class = "Session"
       @strategy_methods = {}
     end
@@ -377,6 +386,15 @@ module Sessions
       @parent_controller = name
     end
 
+    def layout=(value)
+      if value.nil? || value.respond_to?(:call) || value.is_a?(String) || value.is_a?(Symbol)
+        @layout = value
+        return
+      end
+
+      raise ConfigurationError, "layout must be a String, Symbol, callable, or nil, got #{value.inspect}"
+    end
+
     def require_reauthentication=(value)
       if value.nil?
         @require_reauthentication = nil
@@ -386,6 +404,31 @@ module Sessions
       @require_reauthentication = ensure_callable(value, "require_reauthentication")
     end
 
+    def reauthentication_key=(value)
+      if value.nil? || value.respond_to?(:call) || (value.is_a?(String) && value.bytesize >= 32)
+        @reauthentication_key = value
+        return
+      end
+
+      raise ConfigurationError, "reauthentication_key must be a String of at least 32 bytes, a callable, or nil"
+    end
+
+    # The signing key, resolved from a callable on use (so it can read credentials lazily).
+    def resolved_reauthentication_key
+      key = @reauthentication_key.respond_to?(:call) ? @reauthentication_key.call : @reauthentication_key
+      raise ConfigurationError, "config.reauthentication_key is not set" if key.to_s.empty?
+
+      key
+    end
+
+    def reauthentication_window=(value)
+      @reauthentication_window = ensure_positive_duration(value, "reauthentication_window")
+    end
+
+    def reauthentication_assertion_ttl=(value)
+      @reauthentication_assertion_ttl = ensure_positive_duration(value, "reauthentication_assertion_ttl")
+    end
+
     def session_class=(value)
       name = value.is_a?(Class) ? value.name : value.to_s
       raise ConfigurationError, "session_class can't be blank" if name.strip.empty?
@@ -431,6 +474,12 @@ module Sessions
       value
     end
 
+    def ensure_positive_duration(value, name)
+      return value if value.is_a?(Numeric) && value.positive?
+
+      raise ConfigurationError, "#{name} must be a positive duration (for example 5.minutes), got #{value.inspect}"
+    end
+
     def ensure_callable(value, name)
       unless value.respond_to?(:call)
         raise ConfigurationError, "#{name} must respond to #call (a proc/lambda), got #{value.inspect}"

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

@@ -144,6 +144,97 @@ module Sessions
       update!(auth_detail: detail.merge("second_factor" => kind.to_s))
     end
 
+    # --- Re-authentication ----------------------------------------------------
+
+    # Record that the person re-authenticated on THIS session just now (a
+    # password re-entry, a passkey or a second factor). Call it after your
+    # own check succeeded; the gem never checks credentials itself:
+    #
+    #   if current_user.valid_password?(params[:password])
+    #     Sessions.current(request)&.reauthenticated!(method: :password)
+    #   end
+    #
+    # Stored in `auth_detail` like `second_factor!`, so no migration is needed.
+    def reauthenticated!(method: :password, at: Time.current)
+      unless self.class.column_names.include?("auth_detail")
+        raise Sessions::Error, "re-authentication needs the auth_detail column (rails generate sessions:install)"
+      end
+
+      with_lock do # reloads the row: a revocation by another process counts
+        raise Sessions::Error, "an ended or expired session cannot be re-authenticated" unless reauthenticatable?
+
+        detail = (try(:auth_detail) || {}).to_h
+        update!(auth_detail: detail.merge("reauthenticated_at" => at.utc.iso8601(6),
+                                          "reauthentication_method" => method.to_s))
+      end
+    end
+
+    # When the person last re-authenticated on this session, or nil.
+    def reauthenticated_at
+      value = (try(:auth_detail) || {}).to_h["reauthenticated_at"]
+      value && Time.iso8601(value)
+    rescue ArgumentError
+      nil
+    end
+
+    def reauthentication_method = (try(:auth_detail) || {}).to_h["reauthentication_method"]
+
+    # True when this live, unexpired session re-authenticated within the
+    # duration (default: config.reauthentication_window), on this row as stored.
+    def reauthenticated_within?(duration = Sessions.config.reauthentication_window)
+      at = reauthenticated_at
+      reauthenticatable? && at.present? && at > duration.ago && at <= Time.current
+    end
+
+    # A short-lived signed assertion of the last re-authentication, for one
+    # audience (and optionally one purpose). Another service verifies it with
+    # Sessions::Reauthentication.verify and the shared key. Raises
+    # Sessions::Reauthentication::NotRecent unless the re-authentication is
+    # within config.reauthentication_window. The row is reloaded under a lock
+    # first, so an assertion never outlives a revocation it could see.
+    def reauthentication_assertion(audience:, purpose: nil, within: Sessions.config.reauthentication_window)
+      with_lock do
+        unless reauthenticated_within?(within)
+          raise Sessions::Reauthentication::NotRecent, "no re-authentication within #{within.inspect}"
+        end
+
+        config = Sessions.config
+        Sessions::Reauthentication.issue(
+          subject: reauthentication_subject, session_id: id, method: reauthentication_method,
+          authenticated_at: reauthenticated_at, audience: audience, purpose: purpose,
+          key: config.resolved_reauthentication_key, expires_in: config.reauthentication_assertion_ttl
+        )
+      end
+    end
+
+    # The owner's canonical subject ("User:42"), with the owner class even
+    # when the owner record is not loaded. A stored polymorphic type is
+    # resolved to its class first, so the subject is the full class name
+    # also when `store_full_class_name` is false; it then matches
+    # Sessions::Reauthentication.subject_for(owner).
+    def reauthentication_subject
+      stored_type = try(:user_type).presence
+      owner_class = if stored_type
+                      sessions_polymorphic_owner_class(stored_type)
+                    else
+                      self.class.reflect_on_association(:user)&.klass
+                    end
+      owner_type = owner_class.respond_to?(:base_class) ? owner_class.base_class.name : stored_type
+      "#{owner_type}:#{user_id}"
+    end
+
+    private
+
+    def reauthenticatable? = !ended? && !sessions_expired?
+
+    def sessions_polymorphic_owner_class(stored_type)
+      self.class.polymorphic_class_for(stored_type)
+    rescue NameError, ArgumentError
+      nil
+    end
+
+    public
+
     # --- Revocation -----------------------------------------------------------
 
     # End this registry row without deleting it. This is the core v0.2

data/lib/sessions/models/event.rb

@@ -179,11 +179,14 @@ module Sessions
                 .count
         return unless count == config[:threshold]
 
+        user = Sessions.user_for_identity(event.identity, scope: event.scope)
+
         Sessions.safely("on_repeated_failed_logins hook") do
-          Sessions.config.on_repeated_failed_logins.call(
+          call_repeated_failed_logins_hook(
             identity: event.identity,
             count: count,
-            event: event
+            event: event,
+            user: user
           )
         end
       end
@@ -199,6 +202,30 @@ module Sessions
         normalized.empty? ? nil : normalized
       end
 
+      def call_repeated_failed_logins_hook(**kwargs)
+        hook = Sessions.config.on_repeated_failed_logins
+        params = hook_keyword_parameters(hook)
+        return hook.call(**kwargs) if params.nil?
+        return hook.call(**kwargs) if params.any? { |type, _name| type == :keyrest }
+
+        accepted = params.select { |type, _name| %i[key keyreq].include?(type) }
+                         .filter_map { |_type, name| name }
+        hook.call(**kwargs.slice(*accepted))
+      end
+
+      # Procs/lambdas/Method objects expose #parameters directly; a plain
+      # callable object (a class with #call) only exposes them through
+      # #method(:call). nil means "cannot introspect" — dispatch everything
+      # and let the hook decide.
+      def hook_keyword_parameters(hook)
+        return hook.parameters if hook.respond_to?(:parameters)
+        return hook.method(:call).parameters if hook.respond_to?(:call)
+
+        nil
+      rescue StandardError
+        nil
+      end
+
       def context_for(request)
         params = request.respond_to?(:path_parameters) ? request.path_parameters : nil
         return nil unless params && params[:controller]
@@ -221,8 +248,9 @@ module Sessions
       authenticatable
     end
 
-    # The live registry row this event points at — nil once it's been
-    # revoked/logged out (that's the point of the trail).
+    # The lifecycle registry row this event points at. In v0.2 an ended row
+    # remains available as explicit revocation state; nil means the host later
+    # hard-deleted it (for example during account erasure).
     def session
       return nil if session_id.nil?
 

data/lib/sessions/reauthentication.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "time"
+require "active_support"
+require "active_support/message_verifier"
+require "active_support/core_ext/time/calculations"
+require "active_support/core_ext/numeric/time" # 5.minutes for max_age: and fresh?(within:)
+require "active_support/security_utils"
+require_relative "errors"
+
+module Sessions
+  # Short-lived, signed proof that a person re-entered their password (or
+  # passed another re-authentication) on a given session a moment ago.
+  #
+  # The host records the re-authentication on the session row and issues an
+  # assertion for one audience; another service that holds the shared key
+  # verifies it without a database, without a session cookie, and without
+  # this app's models:
+  #
+  #   # The host, right after it checked the password:
+  #   session = Sessions.current(request)
+  #   session.reauthenticated!(method: :password)
+  #   token = session.reauthentication_assertion(audience: "billing", purpose: "refund:42")
+  #
+  #   # The other service (only `require "sessions/reauthentication"` is needed):
+  #   assertion = Sessions::Reauthentication.verify(token, audience: "billing", key: ENV["REAUTH_KEY"],
+  #                                                 subject: "User:#{user_id}", purpose: "refund:42")
+  #   assertion&.fresh?(within: 5.minutes)  # => true
+  #
+  # An assertion is a signed statement, not a session: it expires quickly
+  # (`reauthentication_assertion_ttl`), names its audience and purpose, and
+  # carries a unique `jti` so a verifier that must refuse replays can keep a
+  # short list of the ones it accepted.
+  module Reauthentication
+    # The claims of a verified assertion. `subject` is "<owner class>:<id>".
+    Assertion = Data.define(:subject, :session_id, :method, :authenticated_at, :audience, :purpose, :jti, :issued_at,
+                            :expires_at) do
+      # True when the re-authentication happened within the duration.
+      def fresh?(within:) = authenticated_at > Time.now - within
+    end
+
+    DIGEST = "SHA256"
+    CLOCK_SKEW = 30 # seconds of tolerance for the issuer's clock running ahead
+
+    # The session has no re-authentication recent enough to assert.
+    class NotRecent < Sessions::Error; end
+
+    module_function
+
+    # The canonical subject of an owner record ("User:42"), so owners of two
+    # classes with the same id never share a subject. A String passes through.
+    def subject_for(owner)
+      return owner.to_s if owner.is_a?(String) || !owner.respond_to?(:id)
+
+      klass = owner.class.respond_to?(:base_class) ? owner.class.base_class : owner.class
+      "#{klass.name}:#{owner.id}"
+    end
+
+    # A signed assertion. `key` is the shared secret (at least 32 bytes).
+    def issue(subject:, session_id:, method:, authenticated_at:, audience:, key:, purpose: nil, expires_in: 60)
+      now = Time.now.utc
+      claims = { "sub" => subject_for(subject), "sid" => session_id.to_s, "method" => method.to_s,
+                 "auth_at" => authenticated_at.utc.iso8601(6), "aud" => audience.to_s, "purpose" => purpose&.to_s,
+                 "jti" => SecureRandom.uuid, "iat" => now.iso8601(6), "exp" => (now + expires_in).iso8601(6) }
+      verifier(key).generate(claims, expires_in: expires_in, purpose: signing_purpose(audience))
+    end
+
+    # The Assertion of a token, or nil when the token is forged, expired, for
+    # another audience, purpose or subject, dated in the future beyond
+    # CLOCK_SKEW, or (with max_age) of a re-authentication older than max_age.
+    # A verifier that must refuse replays records each accepted `jti` until
+    # its `expires_at` (an atomic check-and-insert).
+    def verify(token, audience:, key:, subject: nil, purpose: nil, max_age: nil)
+      return nil if token.to_s.empty?
+
+      claims = verifier(key).verified(token.to_s, purpose: signing_purpose(audience))
+      return nil unless claims.is_a?(Hash) && claims["aud"] == audience.to_s
+      return nil if subject && !secure_equal?(claims["sub"], subject_for(subject))
+      return nil if purpose && !secure_equal?(claims["purpose"].to_s, purpose.to_s)
+
+      assertion = Assertion.new(subject: claims["sub"], session_id: claims["sid"], method: claims["method"],
+                                authenticated_at: Time.iso8601(claims["auth_at"]), audience: claims["aud"],
+                                purpose: claims["purpose"], jti: claims["jti"], issued_at: Time.iso8601(claims["iat"]),
+                                expires_at: Time.iso8601(claims["exp"]))
+      latest = Time.now + CLOCK_SKEW
+      return nil if assertion.authenticated_at > latest || assertion.issued_at > latest
+      return nil if assertion.authenticated_at > assertion.issued_at
+      return nil if max_age && !assertion.fresh?(within: max_age)
+
+      assertion
+    rescue ArgumentError, TypeError, KeyError
+      nil
+    end
+
+    def verifier(key)
+      raise Sessions::ConfigurationError, "a reauthentication key needs at least 32 bytes" if key.to_s.bytesize < 32
+
+      ActiveSupport::MessageVerifier.new(key.to_s, digest: DIGEST, serializer: JSON)
+    end
+
+    def signing_purpose(audience) = "sessions/reauthentication/#{audience}"
+
+    def secure_equal?(left, right)
+      left.to_s.bytesize == right.to_s.bytesize && ActiveSupport::SecurityUtils.secure_compare(left.to_s, right.to_s)
+    end
+  end
+end

data/lib/sessions/reauthentication_helpers.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Sessions
+  # Controller helpers for re-authentication assertions. Opt in where you
+  # check a password again, and name whose password you checked:
+  #
+  #   class ReauthenticationsController < ApplicationController
+  #     include Sessions::ReauthenticationHelpers
+  #
+  #     def create
+  #       if current_user.valid_password?(params[:password])
+  #         record_sessions_reauthentication!(current_user, method: :password)
+  #         token = sessions_reauthentication_assertion(current_user, audience: "approvals")
+  #       end
+  #     end
+  #   end
+  #
+  # Every helper takes the owner whose credential the controller checked and
+  # acts only on a current session of that owner (in `scope:` when the app
+  # signs in more than one Warden scope).
+  module ReauthenticationHelpers
+    private
+
+    # Records the re-authentication on the owner's current session. Returns the session, or nil.
+    def record_sessions_reauthentication!(owner, method: :password, scope: nil)
+      sessions_reauthentication_session(owner, scope)&.tap { |session| session.reauthenticated!(method: method) }
+    end
+
+    # True when the owner's current session re-authenticated within the window.
+    def sessions_reauthenticated?(owner, within: Sessions.config.reauthentication_window, scope: nil)
+      sessions_reauthentication_session(owner, scope)&.reauthenticated_within?(within) || false
+    end
+
+    # An assertion of the owner's recent re-authentication, or nil.
+    def sessions_reauthentication_assertion(owner, audience:, purpose: nil, scope: nil)
+      sessions_reauthentication_session(owner, scope)&.reauthentication_assertion(audience: audience, purpose: purpose)
+    rescue Sessions::Reauthentication::NotRecent
+      nil
+    end
+
+    def sessions_reauthentication_session(owner, scope)
+      session = Sessions.current(request, scope: scope)
+      return nil unless session && owner
+      return nil unless session.reauthentication_subject == Sessions::Reauthentication.subject_for(owner)
+
+      session
+    end
+  end
+end

data/lib/sessions/version.rb

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

data/lib/sessions.rb

@@ -13,6 +13,8 @@ require "active_support/security_utils"
 require_relative "sessions/version"
 require_relative "sessions/errors"
 require_relative "sessions/configuration"
+require_relative "sessions/reauthentication"
+require_relative "sessions/reauthentication_helpers"
 require_relative "sessions/current"
 require_relative "sessions/end_reason"
 require_relative "sessions/ip_address"
@@ -94,6 +96,27 @@ module Sessions
       config.session_model
     end
 
+    # Resolve a typed login identity to an account for host hooks. Failed
+    # login events still do NOT persist an account link (enumeration safety);
+    # this is only an in-process convenience for notification hooks that are
+    # already allowed to know whether the account exists.
+    def user_for_identity(identity, scope: nil)
+      normalized = Sessions::Event.normalize_identity(identity)
+      return nil if normalized.blank?
+
+      safely("user_for_identity") do
+        model = user_model_for_identity(scope)
+        next nil unless model.respond_to?(:column_names)
+
+        column = %w[email email_address login username phone].find { |name| model.column_names.include?(name) }
+        next nil unless column
+
+        table = model.quoted_table_name
+        quoted_column = model.connection.quote_column_name(column)
+        model.where("LOWER(#{table}.#{quoted_column}) = ?", normalized).first
+      end
+    end
+
     # --- Request-side API -----------------------------------------------------
 
     # Label the login that's about to happen on this request — for flows
@@ -312,6 +335,20 @@ module Sessions
 
     private
 
+    def user_model_for_identity(scope)
+      if scope && defined?(::Devise) && ::Devise.respond_to?(:mappings)
+        mapping = ::Devise.mappings[scope.to_sym] || ::Devise.mappings[scope.to_s]
+        return mapping.to if mapping.respond_to?(:to)
+      end
+
+      reflection = session_model.reflect_on_association(:user)
+      return nil if reflection&.polymorphic?
+
+      reflection&.klass
+    rescue StandardError
+      nil
+    end
+
     def omakase_current(_request)
       return nil unless defined?(::Current) && ::Current.respond_to?(:session)
 
@@ -329,10 +366,22 @@ module Sessions
         next unless key.to_s.match?(pattern) && value.is_a?(Hash)
 
         tracking = Adapters::Warden.parse_tracking_state(value[Adapters::Warden::SESSION_KEY])
-        next unless tracking && tracking[:mode] == "credential"
+        next unless tracking
 
         row = session_model.live.find_by(id: tracking[:id])
-        return row if row.respond_to?(:sessions_token_matches?) && row&.sessions_token_matches?(tracking[:token])
+        next unless row
+
+        case tracking[:mode]
+        when "credential"
+          return row if row.respond_to?(:sessions_token_matches?) && row.sessions_token_matches?(tracking[:token])
+        when "hint"
+          # Tokenless remembered reattach: the tracking state is written
+          # server-side, but corroborate with the signed browser-continuity
+          # cookie before answering "this is the current device" — the same
+          # proof the adapter demands before touching or kicking a hint row.
+          device_id = Adapters::Warden.device_id_from_request(request)
+          return row if device_id.present? && device_id == row.try(:device_id)
+        end
       end
       nil
     rescue StandardError
@@ -362,7 +411,13 @@ module Sessions
 
       count = 0
       expired_sessions_scope.find_each do |session|
-        session.revoke!(reason: :expired)
+        # Expiry is timeout POLICY, not a revocation: end the row (writes the
+        # `expired` audit event; `expired` kicks on resume) but never rotate
+        # the account-wide remember-me credential or fire on_session_revoked.
+        # This matches the adapter's inline expiry and Devise's timeoutable,
+        # where remember-me revival after a timeout is the host's own
+        # rememberable policy — not ours to nuke for every other device.
+        session.end!(reason: :expired)
         count += 1
       end
       count

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sessions
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-06-21 00:00:00.000000000 Z
+date: 2026-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -73,14 +73,14 @@ dependencies:
   name: browser
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '6.0'
 - !ruby/object:Gem::Dependency
@@ -174,6 +174,8 @@ files:
 - lib/generators/sessions/templates/madmin/session_events_controller.rb
 - lib/generators/sessions/templates/madmin/session_resource.rb
 - lib/generators/sessions/templates/madmin/sessions_controller.rb
+- lib/generators/sessions/templates/madmin/user_panel/madmin_user_panel.rb
+- lib/generators/sessions/templates/madmin/user_panel/sessions.html.erb
 - lib/generators/sessions/templates/session.rb.erb
 - lib/generators/sessions/templates/sessions_sweep_job.rb
 - lib/generators/sessions/upgrade_generator.rb
@@ -198,6 +200,8 @@ files:
 - lib/sessions/models/concerns/has_sessions.rb
 - lib/sessions/models/concerns/model.rb
 - lib/sessions/models/event.rb
+- lib/sessions/reauthentication.rb
+- lib/sessions/reauthentication_helpers.rb
 - lib/sessions/version.rb
 homepage: https://github.com/rameerez/sessions
 licenses: