sessions 0.1.0

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

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+Sessions.configure do |config|
+  # ==========================================================================
+  # BEHAVIOR
+  # ==========================================================================
+  #
+  # How often `last_seen_at` may be written per session — ONE conditional
+  # UPDATE, at most once per window (hot-row safe; this is what powers
+  # "Active 3 minutes ago" and the staleness sweep). nil disables touching.
+  #
+  # config.touch_every = 5.minutes
+  #
+  # Per-user live-session cap with oldest-eviction (GitLab keeps 100,
+  # Discourse 60). Evicted sessions land in the trail as revoked (:pruned).
+  # nil = unlimited.
+  #
+  # config.max_sessions_per_user = 100
+  #
+  # Opt-in session expiry — both default to nil because a tracking gem must
+  # never silently shorten anyone's sessions. When set, expiry is enforced
+  # at session resume AND by the SessionsSweepJob. Heads-up for Rails 8 auth
+  # apps: the generated cookie lives 20 years, so this sweep is the only
+  # real expiry your sessions will ever have.
+  #
+  # config.idle_timeout = nil                # e.g. 1.hour
+  # config.max_session_lifetime = nil        # e.g. 24.hours
+  # config.timeout_preset = :nist_aal2       # sugar: sets both (24h / 1h, NIST 800-63B)
+  #
+  # Changing a password revokes the user's other sessions (ASVS 3.3.3 —
+  # Laravel, Phoenix, and Rails 8.1's own password reset all do this).
+  #
+  # config.revoke_on_password_change = true
+  #
+  # Devise mode: revoking a session also rotates the user's remember-me
+  # credentials, so a stolen long-lived remember cookie can't quietly revive
+  # a revoked device (GitLab semantics; user-wide — other live sessions stay
+  # alive but can't auto-revive after they end).
+  #
+  # config.revoke_remember_me = true
+  #
+  # Record failed login attempts (with the typed identity, never the
+  # password) in the trail.
+  #
+  # config.track_failed_logins = true
+  #
+  # Burst detection: fire on_repeated_failed_logins (see HOOKS below) ONCE
+  # when an identity crosses the threshold inside the window — never per
+  # attempt (that would be notification fatigue and an inbox-flooding
+  # vector). Complements :lockable / rate limiting: they stop the attacker,
+  # this tells the user. nil disables.
+  #
+  # config.repeated_failed_logins = { threshold: 5, within: 15.minutes }
+
+  # ==========================================================================
+  # DEVICE INTELLIGENCE
+  # ==========================================================================
+  #
+  # The web UA parser. :browser (bundled, MIT, tiny) covers "Chrome on
+  # macOS"-grade names; :device_detector auto-upgrades device naming if your
+  # app bundles that gem; or bring your own lambda.
+  #
+  # config.ua_parser = :browser              # :device_detector | ->(ua, headers) { {...} }
+  #
+  # Advertise Accept-CH so Chromium browsers send high-entropy client hints
+  # (real platform versions, Android device models) — Safari/Firefox don't
+  # implement client hints and stay UA-only either way.
+  #
+  # config.request_client_hints = false
+  #
+  # Hotwire Native apps are detected automatically; if your native shells
+  # use a legacy UA prefix (like "MyApp Android 1.0.5 (build 6; …)") on
+  # raw HTTP clients, declare the app name so those parse too. (The
+  # documented `AppName/1.2.3 (model; OS ver; build N);` convention from the
+  # README always parses without configuration.)
+  #
+  # config.native_app_names = ["MyApp"]
+
+  # ==========================================================================
+  # IP & GEOLOCATION
+  # ==========================================================================
+  #
+  # How to read the client IP. The default honors Rails' trusted_proxies
+  # (`request.remote_ip`). Behind Cloudflare, prefer the cloudflare-rails
+  # gem (remote_ip just works); reading CF-Connecting-IP directly is only
+  # safe when your origin is unreachable except through Cloudflare:
+  #
+  # config.ip_resolver = ->(request) { request.headers["CF-Connecting-IP"] || request.remote_ip }
+  #
+  # Privacy hardening: :truncated zeroes the last IPv4 octet / 80 IPv6 bits
+  # BEFORE persistence (the Google Analytics precedent) — nothing
+  # un-truncated ever touches disk.
+  #
+  # config.ip_mode = :full                   # | :truncated
+  #
+  # Geolocation through the trackdown gem when it's installed (Cloudflare
+  # headers resolve synchronously for free; MaxMind lookups run async in
+  # Sessions::GeolocateJob). Without trackdown, locations simply stay blank.
+  #
+  # config.geolocate = :auto                 # | :off
+  #
+  # Decimals kept on event coordinates (2 ≈ 1km).
+  #
+  # config.geo_precision = 2
+
+  # ==========================================================================
+  # RETENTION (the trail is personal data — keep it bounded)
+  # ==========================================================================
+  #
+  # How long sessions_events rows live before SessionsSweepJob purges them.
+  # CNIL recommends 6–12 months for security logs. nil keeps them forever
+  # (you own the purge).
+  #
+  # config.events_retention = 12.months
+
+  # ==========================================================================
+  # HOOKS — kwargs, no-op defaults, error-isolated (a broken hook can never
+  # break a login)
+  # ==========================================================================
+  #
+  # A login from a device this user has never used before — wire your
+  # "Was this you?" email here. Not fired on a user's very first login.
+  #
+  # PASS THE EVENT to your mailer, not the session: the event is a
+  # persisted, GlobalID-able record that survives revocation (the session
+  # row may be destroyed before an async job runs) and already carries
+  # everything the email needs — event.user, event.device_name,
+  # event.location, event.country_flag, event.occurred_at.
+  #
+  # config.on_new_device = ->(user:, session:, event:) do
+  #   SecurityMailer.with(event: event).new_device.deliver_later
+  # end
+  #
+  # config.on_session_revoked = ->(session:, by:, reason:) do
+  #   Rails.logger.info("session revoked (#{reason}) by #{by.inspect}")
+  # 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:
+  #
+  # config.on_repeated_failed_logins = ->(identity:, count:, event:) do
+  #   user = User.find_by(email: identity) or next
+  #   SecurityMailer.with(user: user, event: event).repeated_failed_logins.deliver_later
+  # end
+  #
+  # The catch-all tee: EVERY trail event (logins, failures, logouts,
+  # revocations) right after it's recorded. `event.summary` is the
+  # audit-shaped projection (device, identity, reasons, ip, country —
+  # compacted, no raw blobs), so wiring an audit ledger is one line:
+  #
+  # config.events = ->(event) do
+  #   AuditLog.log(event_type: "session.#{event.name}", user: event.user,
+  #                request: event.request, data: event.summary)
+  # end
+
+  # ==========================================================================
+  # INTEGRATION
+  # ==========================================================================
+  #
+  # The controller the devices page inherits from — your layout, helpers,
+  # auth filters and locale apply automatically (the Devise/api_keys/chats
+  # pattern).
+  #
+  # config.parent_controller = "::ApplicationController"
+  #
+  # How the page finds the signed-in user. The resolver chain tries: this
+  # method → :current_user → ::Current.session&.user — so Devise AND Rails 8
+  # auth work with zero configuration. Override for custom stacks:
+  #
+  # config.current_user_method = :current_user
+  # 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"):
+  #
+  # config.layout = nil
+  #
+  # Optional sudo gate before destructive actions on the devices page (ASVS
+  # 3.3.4's "having re-entered login credentials"). The action runs only
+  # when the gate returns TRUTHY without rendering — render/redirect to
+  # take over with your password-confirm flow, or return false/nil to
+  # block (a bare falsy answers 403; the gate fails closed):
+  #
+  # config.require_reauthentication = ->(controller) do
+  #   controller.session[:sudo_until]&.future? ||
+  #     controller.redirect_to(controller.main_app.confirm_password_path)
+  # end
+  #
+  # The session-of-record model (escape hatch for apps that installed with
+  # --model because a legacy Session class was in the way):
+  #
+  # config.session_class = "Session"
+  #
+  # Classify custom Warden strategies (substring of the strategy class name
+  # → auth method). DatabaseAuthenticatable/Rememberable/
+  # MagicLinkAuthenticatable are built in.
+  #
+  # config.strategy_methods = { "OtpAuthenticatable" => :otp }
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# The login trail (sessions gem): append-only record of every login attempt
+# — successful AND failed, with the identity AS TYPED even when no such
+# account exists — plus logouts, revocations and expiries. This is the
+# brute-force / credential-stuffing / account-takeover triage surface:
+#
+#   filter "Failed logins" + sort by occurred_at  → tonight's attack
+#   search an email                               → everything typed against it
+#   search an IP                                  → everything from that address
+#
+# Events are immutable history; there are no destructive actions here. The
+# kill switch lives on the live session (SessionResource).
+class Sessions::EventResource < Madmin::Resource
+  model Sessions::Event
+
+  attribute :id, index: false, form: false
+  attribute :event, index: true, form: false, label: "Event"
+  attribute :identity, index: true, form: false, label: "Identity (as typed)"
+  # Virtual: Event#user is the resolved account (nil for unknown-identity
+  # failures — that's the point of the identity column above).
+  attribute :user, :string, index: true, form: false, label: "User"
+  # Virtual (gem-computed): "Chrome 137 on macOS".
+  attribute :device_name, :string, index: true, form: false, label: "Device"
+  attribute :failure_reason, index: true, form: false
+  attribute :revoked_reason, index: false, form: false
+  attribute :auth_method, index: false, form: false
+  attribute :auth_provider, index: false, form: false
+  attribute :ip_address, index: true, form: false, label: "IP"
+  attribute :country_code, index: true, form: false, label: "Country"
+  attribute :city, index: false, form: false
+  attribute :region, index: false, form: false
+  attribute :scope, index: false, form: false
+  attribute :session_id, index: false, form: false, label: "Session"
+  attribute :user_agent, index: false, form: false
+  attribute :browser_name, index: false, form: false
+  attribute :os_name, index: false, form: false
+  attribute :device_type, index: false, form: false
+  attribute :device_model, index: false, form: false
+  attribute :app_name, index: false, form: false
+  attribute :app_version, index: false, form: false
+  attribute :request_id, index: false, form: false
+  attribute :context, index: false, form: false
+  attribute :metadata, index: false, form: false
+  attribute :occurred_at, index: true, form: false, label: "When"
+
+  # Hidden: raw blobs / geo internals that only add noise next to the
+  # parsed columns.
+  attribute :auth_detail, show: false, form: false
+  attribute :client_hints, show: false, form: false
+  attribute :latitude, show: false, form: false
+  attribute :longitude, show: false, form: false
+  attribute :country_name, show: false, form: false
+  attribute :browser_version, show: false, form: false
+  attribute :os_version, show: false, form: false
+  attribute :app_build, show: false, form: false
+  attribute :authenticatable_type, show: false, form: false
+  attribute :authenticatable_id, show: false, form: false
+
+  # Gem scopes — the triage filters.
+  scope :logins
+  scope :failed_logins
+  scope :logouts
+  scope :revocations
+  scope :expirations
+  scope :new_devices
+  scope :last_24_hours
+
+  menu label: "Login activity", parent: "Security"
+
+  def self.display_name(record)
+    "#{record.event} · #{record.identity || record.user.try(:email) || "unknown"}"
+  end
+
+  def self.default_sort_column = "occurred_at"
+  def self.default_sort_direction = "desc"
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Madmin
+  # The login trail — read-only by design (append-only history; the
+  # destructive verbs live on live sessions, not on their records).
+  class SessionEventsController < Madmin::ResourceController
+    private
+
+    # Stock Madmin derives the resource from the controller path
+    # ("madmin/session_events" → ::SessionEventResource); ours is namespaced
+    # under Sessions::. Overriding resource_name keeps this self-contained
+    # on stock Madmin — no host patches required.
+    def resource_name
+      "Sessions::EventResource"
+    end
+
+    def scoped_resources
+      super.includes(:authenticatable)
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Live device registry (sessions gem): one row = one signed-in device,
+# destroyed on logout/revocation — so this index IS the set of sessions that
+# can act on your app right now. The append-only history lives in
+# Sessions::Event (see Sessions::EventResource).
+class SessionResource < Madmin::Resource
+  model <%= session_class %>
+
+  attribute :id, index: true, form: false, label: "ID"
+  attribute :user, index: true, form: false, label: "User"
+  # Virtual (gem-computed): "Chrome 137 on macOS",
+  # "MyApp 2.4.1 on Pixel 8 (Android 16)".
+  attribute :device_name, :string, index: true, form: false, label: "Device"
+  attribute :auth_method, index: true, form: false, label: "Via"
+  attribute :auth_provider, index: false, form: false
+  attribute :ip_address, index: true, form: false, label: "IP (login)"
+  attribute :last_seen_ip, index: false, form: false, label: "IP (last seen)"
+  attribute :country_code, index: true, form: false, label: "Country"
+  attribute :city, index: false, form: false
+  attribute :scope, index: false, form: false
+  attribute :device_type, index: false, form: false
+  attribute :browser_name, index: false, form: false
+  attribute :browser_version, index: false, form: false
+  attribute :os_name, index: false, form: false
+  attribute :os_version, index: false, form: false
+  attribute :device_model, index: false, form: false
+  attribute :app_name, index: false, form: false
+  attribute :app_version, index: false, form: false
+  attribute :app_build, index: false, form: false
+  attribute :user_agent, index: false, form: false
+  attribute :last_seen_at, index: true, form: false, label: "Last seen"
+  attribute :created_at, index: true, form: false, label: "Signed in"
+  attribute :updated_at, show: false, form: false
+
+  # 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 :auth_detail, show: false, form: false
+  attribute :client_hints, show: false, form: false
+
+  # Gem scopes: active = last activity within 30 days.
+  scope :active
+  scope :inactive
+
+  menu label: "Sessions", parent: "Security"
+
+  def self.display_name(record)
+    "#{record.device_name} — #{record.user.try(:email) || record.user_id}"
+  end
+
+  def self.default_sort_column = "created_at"
+  def self.default_sort_direction = "desc"
+
+  # Remote logout: destroys the row (the device is signed out on its next
+  # request), writes the `revoked` trail event attributed to the admin, and
+  # rotates the user's remember-me credentials in Devise mode.
+  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." }
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Madmin
+  class SessionsController < Madmin::ResourceController
+    # Admin remote logout. `revoke!` destroys the row (the device is kicked
+    # on its next request — the cookie session and, in Devise mode, any
+    # remember-me revival), and writes the immutable `revoked` trail event
+    # with `by:` attribution.
+    def revoke
+      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."
+
+      redirect_back fallback_location: main_app.madmin_sessions_path
+    rescue ActiveRecord::RecordNotFound
+      flash[:alert] = "That session no longer exists (probably already revoked)."
+      redirect_back fallback_location: main_app.madmin_sessions_path
+    end
+
+    private
+
+    # The index is a triage surface — always show who owns each row without
+    # N+1ing the user column.
+    def scoped_resources
+      super.includes(:user)
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Your session-of-record model — deliberately a 3-line shell: ALL the gem's
+# behavior (device names, revocation, scopes, the trail) lives in the
+# Sessions::Model concern, so this file never goes stale across gem updates.
+# It's also exactly the model `rails generate authentication` would create,
+# which keeps a future move to Rails' built-in auth a no-op for this table.
+class <%= model_name %> < ApplicationRecord
+<% if model_name.underscore.pluralize != table_name -%>
+  self.table_name = "<%= table_name %>"
+
+<% end -%>
+  include Sessions::Model
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# The sessions maintenance pass — schedule it daily (see config/recurring.yml
+# below if you're on Solid Queue). It purges trail rows past
+# `config.events_retention`, evicts per-user overflow beyond
+# `config.max_sessions_per_user`, and (only if you opted into timeouts)
+# expires idle/over-age sessions.
+#
+#   # config/recurring.yml
+#   production:
+#     sessions_sweep:
+#       class: SessionsSweepJob
+#       schedule: every day at 4am
+class SessionsSweepJob < ApplicationJob
+  queue_as :default
+
+  def perform
+    Sessions.sweep!
+  end
+end

data/lib/generators/sessions/views_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Sessions
+  module Generators
+    # `rails generate sessions:views` — eject the engine's overridable
+    # templates into the HOST app so they can be restyled. This is the
+    # Devise move (`rails g devise:views`), and it works for the same boring
+    # Rails reason: the host app's `app/views` sits AHEAD of any engine's
+    # view paths in the lookup chain, so a file copied to e.g.
+    # `app/views/sessions/_device.html.erb` SHADOWS the gem's bundled
+    # default automatically — no config, no registration. Delete your copy
+    # and the gem's default comes back. Upgrade the gem and your ejected
+    # copies are untouched (re-run only if you WANT the new defaults).
+    class ViewsGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../app/views/sessions", __dir__)
+
+      desc "Copy sessions' overridable views into your app so you can restyle them."
+
+      def copy_views
+        directory ".", "app/views/sessions"
+      end
+
+      def show_styling_tip
+        say "\n🎨 Views copied to app/views/sessions/. They render with the gem's"
+        say "   bundled sessions.css by default; restyle freely — if your app uses"
+        say "   Tailwind, classes you add here are picked up by your build"
+        say "   automatically (the files now live in app/views)."
+      end
+    end
+  end
+end

data/lib/sessions/adapters/omakase.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module Sessions
+  module Adapters
+    # The Rails 8 omakase auth adapter — zero app-code changes.
+    #
+    # Installed from `config.to_prepare` (so it re-applies to freshly
+    # reloaded constants in development) and entirely capability-detected:
+    # nothing happens unless the app actually has the generated
+    # authentication code. Three attachment points, each name-stable since
+    # Rails 8.0 (the Authentication concern is byte-identical from 8.0.5
+    # through 8.1.3 to main — → docs/research/03-rails-core.md):
+    #
+    #   1. The Session MODEL gets Sessions::Model included. Its callbacks
+    #      observe 100% of the generated lifecycle: `start_new_session_for`
+    #      uses create!, `terminate_session` uses destroy, and 8.1's
+    #      password reset uses destroy_all (which instantiates and runs
+    #      callbacks) — so logins and revocations are captured with zero
+    #      controller coupling.
+    #
+    #   2. ApplicationController gets ControllerHooks PREPENDED — the
+    #      prepend sits in front of the included Authentication concern in
+    #      the ancestor chain, so `super`-wrapping `resume_session`
+    #      (throttled touch + opt-in expiry) and `terminate_session`
+    #      (labeling the destroy as a logout) is clean.
+    #
+    #   3. The generated SessionsController#create gets FailedLoginHooks
+    #      prepended: `authenticate_by` is deliberately silent on failure
+    #      (no hook, no notification), so we observe the controller seam —
+    #      after `super`, no session + a credentials POST = a failed login.
+    #      Rails 8.1's `rate_limit.action_controller` notification adds the
+    #      brute-force-threshold signal for free.
+    module Omakase
+      module_function
+
+      def install!
+        Sessions.safely("omakase.install") do
+          decorate_session_model!
+          prepend_controller_hooks!
+          prepend_failed_login_hooks!
+        end
+      end
+
+      # `Session.include Sessions::Model` when the host has a Rails-8-shaped
+      # session model (the Devise-mode shell model includes it explicitly;
+      # this is a no-op there).
+      def decorate_session_model!
+        klass = session_class
+        return unless klass
+        return if klass.include?(Sessions::Model)
+
+        klass.include(Sessions::Model)
+      end
+
+      def prepend_controller_hooks!
+        return unless omakase_controller?
+
+        ::ApplicationController.prepend(ControllerHooks)
+      end
+
+      def prepend_failed_login_hooks!
+        return unless omakase_controller?
+        return unless defined?(::SessionsController)
+        return unless ::SessionsController.method_defined?(:create)
+
+        ::SessionsController.prepend(FailedLoginHooks)
+      end
+
+      # The duck test: the generated Authentication concern defines these
+      # private methods on ApplicationController. Capability-based, so a
+      # host that renamed or removed its auth code simply isn't touched.
+      def omakase_controller?
+        defined?(::ApplicationController) &&
+          ::ApplicationController.private_method_defined?(:start_new_session_for) &&
+          ::ApplicationController.private_method_defined?(:resume_session)
+      end
+
+      def session_class
+        klass = Sessions.config.session_class.safe_constantize
+        return nil unless klass.is_a?(Class)
+        return nil unless defined?(::ActiveRecord::Base) && klass < ::ActiveRecord::Base
+        # The Rails 8 base columns prove the shape; last_seen_at proves the
+        # install migration ran (decorating a half-migrated table would give
+        # candy methods nothing to stand on).
+        return nil unless klass.table_exists? &&
+                          (%w[ip_address user_agent last_seen_at] - klass.column_names).empty?
+
+        klass
+      rescue StandardError
+        nil
+      end
+
+      # Rails 8.1+ instruments rate-limit hits with a payload carrying the
+      # request — a free brute-force signal. Subscribed once per process
+      # (from the engine initializer, not to_prepare); on Rails ≤ 8.0 the
+      # notification never fires and this is inert.
+      def subscribe_rate_limit_notifications!
+        return if @rate_limit_subscribed
+
+        @rate_limit_subscribed = true
+        ActiveSupport::Notifications.subscribe("rate_limit.action_controller") do |*_args, payload|
+          record_rate_limited(payload)
+        end
+      end
+
+      def record_rate_limited(payload)
+        Sessions.safely("omakase.rate_limit") do
+          next unless Sessions.config.track_failed_logins
+
+          request = payload[:request]
+          next unless request
+
+          # Only the sessions controller: a rate-limited LOGIN burst is
+          # failed-login activity; throttles elsewhere (password resets,
+          # API endpoints) are not — recording them here would put
+          # non-logins in the failed_login vocabulary.
+          controller = request.path_parameters[:controller].to_s.split("/").last
+          next unless controller == "sessions"
+
+          Sessions::Event.record_failure(
+            request,
+            reason: :rate_limited,
+            metadata: { count: payload[:count], limit: payload[:to] }.compact
+          )
+        end
+      end
+
+      # Prepended in front of the generated Authentication concern.
+      module ControllerHooks
+        private
+
+        # After the host resolves the session row, enforce opt-in expiry and
+        # apply the throttled last_seen_at touch. Both are error-isolated;
+        # an expired session is destroyed (instant revocation semantics) and
+        # the request proceeds unauthenticated.
+        def resume_session
+          session = super
+          return session unless session.respond_to?(:sessions_expired?)
+
+          if session.sessions_expired?
+            Sessions.safely("omakase.expire") { session.revoke!(reason: :expired) }
+            ::Current.session = nil if defined?(::Current) && ::Current.respond_to?(:session=)
+            nil
+          else
+            Sessions.safely("omakase.touch") { session.touch_last_seen!(request) }
+            session
+          end
+        end
+
+        # Label the upcoming destroy as a user sign-out so the trail says
+        # "logout", not "revoked".
+        def terminate_session
+          Sessions.safely("omakase.terminate") do
+            session = defined?(::Current) ? ::Current.try(:session) : nil
+            session.revocation_reason = :logout if session.respond_to?(:revocation_reason=)
+          end
+          super
+        end
+      end
+
+      # Prepended onto the generated SessionsController.
+      module FailedLoginHooks
+        # The generated create either calls start_new_session_for (success —
+        # Current.session is set) or redirects with an alert (failure —
+        # nothing recorded anywhere). We add the missing failure record.
+        def create
+          super
+          Sessions.safely("omakase.failed_login") do
+            next unless Sessions.config.track_failed_logins
+            next if defined?(::Current) && ::Current.try(:session)
+            next unless request.post?
+            # Two-phase 2FA controllers redirect to their challenge with the
+            # password VALIDATED and no session yet — `Sessions.skip!` is
+            # their one-line way to say "not a failure" (see lib/sessions.rb).
+            next if request.env[Sessions::SKIP_ENV_KEY]
+
+            identity = sessions_attempted_identity
+            next unless identity || params[:password].present?
+
+            Sessions::Event.record_failure(request, identity: identity, reason: :invalid_credentials)
+          end
+        end
+
+        private
+
+        # The generated form posts `email_address`; common hand-rolled
+        # variants are accepted too. The password itself is NEVER read
+        # beyond presence.
+        def sessions_attempted_identity
+          %i[email_address email username login].lazy.map { |key| params[key] }.find(&:present?)
+        end
+      end
+    end
+  end
+end