sessions 0.1.0

data/lib/sessions.rb

@@ -0,0 +1,423 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+require "active_support"
+require "active_support/core_ext/integer/time"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/object/try"
+require "active_support/core_ext/enumerable"
+require "active_support/security_utils"
+
+require_relative "sessions/version"
+require_relative "sessions/errors"
+require_relative "sessions/configuration"
+require_relative "sessions/current"
+require_relative "sessions/ip_address"
+require_relative "sessions/device"
+require_relative "sessions/classifier"
+require_relative "sessions/geolocation"
+require_relative "sessions/middleware"
+require_relative "sessions/macros"
+require_relative "sessions/adapters/omakase"
+require_relative "sessions/adapters/warden"
+require_relative "sessions/adapters/omniauth"
+
+require_relative "sessions/engine" if defined?(::Rails::Engine)
+
+# == Sessions
+#
+# Every session, every device, every login — tracked, revocable, visible.
+# The missing session layer for Rails.
+#
+# The public surface is intentionally tiny:
+#
+#   Sessions.configure { |config| ... }       # one block, in an initializer
+#   has_sessions                              # on your auth model
+#
+#   current_user.sessions.active              # live devices
+#   session.device_name                       # => "Chrome on macOS"
+#   session.revoke!                           # remote logout, effective next request
+#   current_user.revoke_other_sessions!       # GitHub's "sign out everywhere else"
+#   current_user.session_history.failed_logins # the trail, identity-matched failures included
+#
+# Plus a handful of request-side seams for flows that can't self-identify:
+#
+#   Sessions.tag(request, method: :passkey)   # label the upcoming login
+#   Sessions.skip!(request)                   # "neither a login nor a failure" (2FA handoffs)
+#   Sessions.current(request)                 # this request's session row
+#   Sessions.last_login(request)              # how this browser last signed in ("Last used" badge)
+#   Sessions.record_failed_attempt(request, identity: params[:email], reason: :invalid_password)
+#   Sessions.track_login(user, request, method: :sso)
+#
+# Everything else (adapters, the devices page, the sweep) ships with the
+# engine and stays out of your way. One rule above all: tracking NEVER
+# breaks authentication — every recording path in this gem is
+# error-isolated (see Sessions.safely).
+module Sessions
+  # The signed browser-continuity cookie (see Sessions::Model — minted at
+  # login, identifies the browser install so repeat logins replace their
+  # old device row instead of stacking duplicates).
+  DEVICE_COOKIE = :sessions_device_id
+
+  # The rack env flag `Sessions.skip!` sets — every recording seam checks
+  # it before writing anything for the request.
+  SKIP_ENV_KEY = "sessions.skip"
+
+  class << self
+    # --- Configuration --------------------------------------------------------
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    alias configuration config
+
+    def configure
+      yield config if block_given?
+      config.validate!
+      config
+    end
+
+    # Reset all global state. Used by the test suite to keep examples
+    # isolated; also handy in a console when experimenting.
+    def reset!
+      @config = Configuration.new
+      self
+    end
+
+    # The host's session-of-record model (`Session` on both supported
+    # stacks; `config.session_class` is the escape hatch).
+    def session_model
+      config.session_model
+    end
+
+    # --- Request-side API -----------------------------------------------------
+
+    # Label the login that's about to happen on this request — for flows
+    # that can't self-identify at the session-row level (Google One Tap,
+    # passkeys, magic links, custom SSO). Call it BEFORE signing the user
+    # in; the classification pipeline gives explicit tags top priority.
+    #
+    #   Sessions.tag(request, method: :google_one_tap, detail: { select_by: params[:select_by] })
+    #   Sessions.tag(request, method: :passkey, detail: { user_verified: true })
+    def tag(request, method:, provider: nil, detail: {})
+      return unless request
+
+      request.env[Classifier::TAG_ENV_KEY] = { method: method, provider: provider, detail: detail }
+      request
+    end
+
+    # Silence tracking for THIS request — the escape hatch for flows that
+    # intentionally end with neither a session nor a failure. The canonical
+    # case is the password phase of a two-phase 2FA challenge
+    # (authentication-zero's --two-factor, hand-rolled TOTP gates): the
+    # password was RIGHT, the controller redirects to the challenge, and
+    # recording a failed_login there would be a lie:
+    #
+    #   if user.otp_required_for_sign_in?
+    #     Sessions.skip!(request)
+    #     session[:challenge_token] = user.signed_id(...)
+    #     redirect_to new_two_factor_authentication_challenge_totp_path
+    #   end
+    #
+    # Honored by every recording seam (both adapters, the failed-login
+    # heuristics). One request only — the challenge completion records
+    # normally.
+    def skip!(request)
+      return unless request
+
+      request.env[SKIP_ENV_KEY] = true
+      request
+    end
+
+    # The registry row for this request — works on both adapters:
+    # omakase (Current.session / the signed session cookie) and
+    # Devise/Warden (the per-scope token stashed in the warden session).
+    # Returns nil when the request carries no live tracked session.
+    #
+    # Multi-scope Devise apps (user + admin signed in on one rack session)
+    # carry one tracked row per scope; pass `scope:` to pick — without it
+    # you get the first live row found, which is unambiguous for the
+    # single-scope majority:
+    #
+    #   Sessions.current(request, scope: :admin_user)
+    def current(request = Sessions::Current.request, scope: nil)
+      return nil unless request
+
+      safely("current") do
+        if scope
+          # An explicit scope is a Warden concept — answering it from
+          # Current.session (the omakase shortcut) would ignore it.
+          warden_current(request, scope: scope)
+        else
+          omakase_current(request) || warden_current(request) || cookie_current(request)
+        end
+      end
+    end
+
+    # The most recent login EVENT from THIS BROWSER — works on the login
+    # page, signed out, because the browser-continuity cookie (the same one
+    # that deduplicates devices) survives logout by design. This is the
+    # one-lookup answer behind the "Last used" badge next to your sign-in
+    # buttons:
+    #
+    #   <% if (last = Sessions.last_login(request))&.auth_provider == "google" %>
+    #     <span class="badge">Last used</span>
+    #   <% end %>
+    #
+    # The event carries auth_method / auth_provider / auth_method_label /
+    # occurred_at ("last used 2 days ago"). Device-scoped, not
+    # account-scoped: it reflects whoever last signed in from this browser
+    # — exactly what a login page can honestly know. Returns nil for
+    # browsers that never signed in, cleared cookies, or tampered values
+    # (the cookie is signed). Read-only: never mints the cookie.
+    def last_login(request)
+      return nil unless request.respond_to?(:cookie_jar)
+
+      safely("last_login") do
+        device_id = request.cookie_jar.signed[DEVICE_COOKIE]
+        next nil if device_id.blank?
+
+        Sessions::Event.logins.where(device_id: device_id.to_s[0, 36])
+                       .order(occurred_at: :desc).first
+      end
+    end
+
+    # Record a failed login attempt from a custom controller — the manual
+    # seam for flows outside Warden's failure app and the omakase
+    # SessionsController (a native-app sign-in branch, passkey
+    # verification rescues, One Tap token errors…).
+    #
+    #   Sessions.record_failed_attempt(request, scope: :user,
+    #                                  identity: params[:email],
+    #                                  reason: :invalid_password)
+    #
+    # Never raises; returns the Sessions::Event or nil.
+    def record_failed_attempt(request, scope: nil, identity: nil, reason: nil,
+                              method: nil, provider: nil, detail: {}, metadata: {})
+      return nil unless config.track_failed_logins
+
+      safely("record_failed_attempt") do
+        tag(request, method: method, provider: provider, detail: detail) if method
+
+        Sessions::Event.record_failure(
+          request,
+          scope: scope,
+          identity: identity,
+          reason: reason,
+          metadata: metadata
+        )
+      end
+    end
+
+    # Fully manual integration: create (and classify, parse, geolocate) a
+    # registry row + login event for +user+ outside any adapter. The host
+    # owns linking the returned row to its own session mechanism and
+    # enforcing revocation. Never raises; returns the session row or nil.
+    def track_login(user, request, method: nil, provider: nil, detail: {})
+      safely("track_login") do
+        tag(request, method: method, provider: provider, detail: detail) if method
+
+        with_request(request) do
+          session_model.create!(
+            user: user,
+            ip_address: IpAddress.resolve(request),
+            user_agent: request&.user_agent
+          )
+        end
+      end
+    end
+
+    # --- Lifecycle ------------------------------------------------------------
+
+    # The maintenance pass the generated SessionsSweepJob runs on a
+    # schedule: expire idle/over-age sessions (only when timeouts are
+    # configured), evict per-user overflow beyond the session cap, and
+    # purge trail rows past retention. Each part is independently
+    # error-isolated. Returns a Hash of counts.
+    def sweep!
+      {
+        expired: safely("sweep.expired") { sweep_expired_sessions! } || 0,
+        pruned: safely("sweep.pruned") { sweep_session_overflow! } || 0,
+        purged_events: safely("sweep.events") { sweep_stale_events! } || 0
+      }
+    end
+
+    # Right-to-erasure helper: destroy every live session, delete the trail,
+    # and null the typed identity on any retained failure rows that match
+    # +user+'s email — so honoring a GDPR deletion request is one call.
+    def forget(user, identity: nil)
+      safely("forget") do
+        session_model.where(user: user).destroy_all if session_model_table?
+        Sessions::Event.where(authenticatable: user).delete_all
+
+        typed = identity || user.try(:email_address) || user.try(:email)
+        Sessions::Event.where(identity: Sessions::Event.normalize_identity(typed)).update_all(identity: nil) if typed
+
+        true
+      end
+    end
+
+    # --- Internals (used by the adapters; stable but undocumented) -------------
+
+    # The error-isolation chokepoint: this gem sits on the authentication
+    # hot path, where a tracking bug may lose a log row but must NEVER 500 a
+    # sign-in (authtrail's `safely` pattern, ecosystem rule). Everything the
+    # adapters and model callbacks do goes through here.
+    def safely(context = nil)
+      yield
+    rescue StandardError => e
+      warn("#{context}: #{e.class}: #{e.message}")
+      nil
+    end
+
+    def warn(message)
+      logger&.warn("[sessions] #{message}")
+      nil
+    end
+
+    def logger
+      defined?(::Rails) && ::Rails.respond_to?(:logger) ? ::Rails.logger : nil
+    end
+
+    # SHA-256 of a session token. High-entropy random input ⇒ a plain
+    # digest suffices (no pepper KDF theater); the raw token only ever
+    # lives in the user's own Rack session (OWASP: never persist raw
+    # session identifiers).
+    def token_digest(token)
+      OpenSSL::Digest::SHA256.hexdigest(token.to_s)
+    end
+
+    def generate_token
+      SecureRandom.hex(32)
+    end
+
+    # Run a block with Sessions::Current.request temporarily set — lets
+    # explicit APIs reuse the same model-callback pipeline the adapters use.
+    def with_request(request)
+      previous = Sessions::Current.request
+      Sessions::Current.request = request
+      yield
+    ensure
+      Sessions::Current.request = previous
+    end
+
+    # The catch-all `config.events` tee, error-isolated.
+    def notify_event(event)
+      safely("events hook") { config.events.call(event) }
+    end
+
+    private
+
+    def omakase_current(_request)
+      return nil unless defined?(::Current) && ::Current.respond_to?(:session)
+
+      session = ::Current.session
+      session if session.is_a?(session_model)
+    rescue StandardError
+      nil
+    end
+
+    def warden_current(request, scope: nil)
+      return nil unless request.env["warden"]
+
+      pattern = scope ? /\Awarden\.user\.#{Regexp.escape(scope.to_s)}\.session\z/ : /\Awarden\.user\..+\.session\z/
+      request.session.to_hash.each do |key, value|
+        next unless key.to_s.match?(pattern) && value.is_a?(Hash)
+
+        id, token = value[Adapters::Warden::SESSION_KEY]
+        next unless id && token
+
+        row = session_model.find_by(id: id)
+        return row if row.respond_to?(:sessions_token_matches?) && row&.sessions_token_matches?(token)
+      end
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def cookie_current(request)
+      return nil unless request.respond_to?(:cookie_jar)
+
+      id = request.cookie_jar.signed[:session_id]
+      session_model.find_by(id: id) if id
+    rescue StandardError
+      nil
+    end
+
+    def session_model_table?
+      session_model.table_exists?
+    rescue StandardError
+      false
+    end
+
+    # --- Sweep internals --------------------------------------------------------
+
+    def sweep_expired_sessions!
+      return 0 unless config.idle_timeout || config.max_session_lifetime
+      return 0 unless session_model_table?
+
+      count = 0
+      expired_sessions_scope.find_each do |session|
+        session.revoke!(reason: :expired)
+        count += 1
+      end
+      count
+    end
+
+    def expired_sessions_scope
+      scopes = []
+
+      if (idle = config.idle_timeout)
+        threshold = idle.ago
+        # A session's last activity is its throttled touch when present,
+        # else its creation.
+        scopes << session_model.where(last_seen_at: ...threshold)
+        scopes << session_model.where(last_seen_at: nil).where(created_at: ...threshold)
+      end
+
+      if (lifetime = config.max_session_lifetime)
+        scopes << session_model.where(created_at: ...lifetime.ago)
+      end
+
+      # NOTE: reduce(:or), never `none.or(...)` — a NullRelation stays null
+      # through #or and would silently sweep nothing.
+      scopes.empty? ? session_model.none : scopes.reduce(:or)
+    end
+
+    def sweep_session_overflow!
+      cap = config.max_sessions_per_user
+      return 0 unless cap
+      return 0 unless session_model_table?
+
+      # Polymorphic installs (--polymorphic) key the owner by TYPE AND id —
+      # grouping by user_id alone would treat User#42 and Organization#42
+      # as one owner and evict across them.
+      owner_keys = session_model.column_names.include?("user_type") ? %i[user_type user_id] : %i[user_id]
+
+      count = 0
+      session_model.group(*owner_keys).count.each do |owner_key, sessions_count|
+        next if sessions_count <= cap
+
+        session_model.where(owner_keys.zip(Array(owner_key)).to_h)
+                     .order(created_at: :asc)
+                     .limit(sessions_count - cap)
+                     .each do |session|
+          session.revoke!(reason: :pruned)
+          count += 1
+        end
+      end
+      count
+    end
+
+    def sweep_stale_events!
+      retention = config.events_retention
+      return 0 unless retention
+      return 0 unless Sessions::Event.table_exists?
+
+      Sessions::Event.where(occurred_at: ...retention.ago).delete_all
+    end
+  end
+end

metadata

@@ -0,0 +1,225 @@
+--- !ruby/object:Gem::Specification
+name: sessions
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- rameerez
+bindir: exe
+cert_chain: []
+date: 2026-06-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  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
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: 'sessions gives any Rails 8+ app a GitHub-style "your devices" page (list
+  every active session, log out of one device, sign out everywhere else) plus an admin-grade,
+  append-only trail of every login attempt — successful and failed — with parsed device
+  intelligence ("Chrome on macOS", "MyApp 2.4.1 on Pixel 8 (Android 16)"), IP geolocation
+  (via the trackdown gem, soft dependency), and the auth method that started each
+  session (password, OAuth provider, passkey, magic link…). It decorates the session
+  storage your app already has instead of replacing it: on Rails 8 omakase auth (`rails
+  generate authentication`) it enriches the generated sessions table with zero app-code
+  changes, and on Devise it generalizes the proven session_limitable mechanism into
+  true per-device remote revocation via Warden hooks. It detects Hotwire Native apps
+  (platform, OS version, app version, device model), never breaks login (every tracking
+  path is error-isolated), ships privacy-first defaults (bounded retention with a
+  sweep job, optional IP truncation, no browser fingerprinting or invasive client-side
+  probing — device continuity is one signed first-party cookie, minted only at login),
+  and includes a mountable, i18n''d devices page you can restyle or eject view-by-view
+  like Devise.'
+email:
+- rubygems@rameerez.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- ".simplecov"
+- AGENTS.md
+- Appraisals
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/assets/stylesheets/sessions.css
+- app/controllers/sessions/application_controller.rb
+- app/controllers/sessions/devices_controller.rb
+- app/helpers/sessions/engine_helper.rb
+- app/views/sessions/_device.html.erb
+- app/views/sessions/_devices.html.erb
+- app/views/sessions/_event.html.erb
+- app/views/sessions/_history.html.erb
+- app/views/sessions/devices/history.html.erb
+- app/views/sessions/devices/index.html.erb
+- config/locales/en.yml
+- config/locales/es.yml
+- config/routes.rb
+- docs/PRD.md
+- docs/research/01-carhey.md
+- docs/research/02-ecosystem.md
+- docs/research/03-rails-core.md
+- docs/research/04-devise-warden.md
+- docs/research/05-oauth.md
+- docs/research/06-prior-art.md
+- docs/research/07-device-detection.md
+- docs/research/08-rails8-landscape.md
+- docs/research/09-market-security.md
+- gemfiles/rails_7.1.gemfile
+- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.0.gemfile
+- gemfiles/rails_8.1.gemfile
+- lib/generators/sessions/install_generator.rb
+- lib/generators/sessions/madmin_generator.rb
+- lib/generators/sessions/templates/add_sessions_columns.rb.erb
+- lib/generators/sessions/templates/create_sessions.rb.erb
+- lib/generators/sessions/templates/create_sessions_events.rb.erb
+- lib/generators/sessions/templates/initializer.rb
+- lib/generators/sessions/templates/madmin/event_resource.rb
+- 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/session.rb.erb
+- lib/generators/sessions/templates/sessions_sweep_job.rb
+- lib/generators/sessions/views_generator.rb
+- lib/sessions.rb
+- lib/sessions/adapters/omakase.rb
+- lib/sessions/adapters/omniauth.rb
+- lib/sessions/adapters/warden.rb
+- lib/sessions/classifier.rb
+- lib/sessions/configuration.rb
+- lib/sessions/current.rb
+- lib/sessions/device.rb
+- lib/sessions/engine.rb
+- lib/sessions/errors.rb
+- lib/sessions/geolocation.rb
+- lib/sessions/ip_address.rb
+- lib/sessions/jobs/geolocate_job.rb
+- lib/sessions/macros.rb
+- lib/sessions/middleware.rb
+- lib/sessions/models/concerns/device_display.rb
+- lib/sessions/models/concerns/has_sessions.rb
+- lib/sessions/models/concerns/model.rb
+- lib/sessions/models/event.rb
+- lib/sessions/version.rb
+homepage: https://github.com/rameerez/sessions
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/rameerez/sessions
+  changelog_uri: https://github.com/rameerez/sessions/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/rameerez/sessions/issues
+  documentation_uri: https://github.com/rameerez/sessions#readme
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Session & login-activity tracking, device management, and remote revocation
+  for Rails
+test_files: []