sessions 0.1.0

data/lib/sessions/ip_address.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Sessions
+  # IP capture, normalization and (optional) anonymization.
+  #
+  # Capture goes through `config.ip_resolver` (default `request.remote_ip`,
+  # which honors Rails' trusted_proxies — see the README's "Behind
+  # Cloudflare" section for CDN setups). Every address is IPAddr-normalized
+  # before persistence (canonical form, garbage rejected) and, when
+  # `config.ip_mode = :truncated`, anonymized BEFORE it ever touches disk:
+  # the last IPv4 octet / the last 80 IPv6 bits are zeroed — the Google
+  # Analytics precedent, and the reason the column can be shown to a GDPR
+  # auditor with a straight face.
+  module IpAddress
+    # 45 chars covers the maximum IPv6 textual form including IPv4-mapped
+    # addresses ("::ffff:255.255.255.255") — the portable column size used
+    # across sqlite/mysql/postgres.
+    MAX_LENGTH = 45
+
+    # Anonymization prefix lengths (bits kept): IPv4 /24 zeroes the last
+    # octet; IPv6 /48 zeroes the last 80 bits.
+    IPV4_PREFIX = 24
+    IPV6_PREFIX = 48
+
+    module_function
+
+    # The client IP for this request, resolved + normalized + anonymized per
+    # configuration. Returns nil for unresolvable/garbage input — a nil IP
+    # must never block a login write.
+    def resolve(request)
+      return nil unless request
+
+      raw = Sessions.config.ip_resolver.call(request)
+      normalize(raw)
+    rescue StandardError => e
+      Sessions.warn("ip resolution failed: #{e.class}: #{e.message}")
+      nil
+    end
+
+    def normalize(raw)
+      return nil if raw.to_s.strip.empty?
+
+      address = IPAddr.new(raw.to_s.strip[0, MAX_LENGTH])
+      address = truncate(address) if Sessions.config.ip_mode == :truncated
+      address.to_s
+    rescue ArgumentError # IPAddr::Error included — it subclasses ArgumentError
+      nil
+    end
+
+    def truncate(address)
+      address.mask(address.ipv4? ? IPV4_PREFIX : IPV6_PREFIX)
+    end
+  end
+end

data/lib/sessions/jobs/geolocate_job.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Sessions
+  # Async geo enrichment for the MaxMind path (the Cloudflare path is a free
+  # synchronous header read at request time and never gets here). Enqueued
+  # after commit — only when trackdown is present AND has a database (see
+  # Sessions::Geolocation.async_capable?), so hosts without MaxMind never
+  # see a no-op job.
+  #
+  # The conditional superclass keeps the constant loadable (Zeitwerk eager
+  # loads this file) in the rare host that runs without ActiveJob — where
+  # enqueueing is already guarded off.
+  class GeolocateJob < (defined?(::ActiveJob::Base) ? ::ActiveJob::Base : Object)
+    if defined?(::ActiveJob::Base)
+      discard_on ActiveRecord::RecordNotFound if defined?(::ActiveRecord::RecordNotFound)
+
+      def perform(class_name, id)
+        record = class_name.constantize.find_by(id: id)
+        return unless record.respond_to?(:country_code)
+        return if record.country_code.present?
+
+        ip = record.try(:ip_address)
+        return if ip.blank?
+        return unless defined?(::Trackdown)
+
+        result = ::Trackdown.locate(ip.to_s)
+        updates = Sessions::Geolocation.columns_from(result)
+        return if updates.empty?
+
+        # Events also store precision-reduced coordinates (privacy now,
+        # impossible-travel math later); registry rows don't have the
+        # columns and the filter drops them.
+        updates.merge!(Sessions::Geolocation.coordinates_from(result))
+        updates.select! { |column, _| record.class.column_names.include?(column.to_s) }
+
+        record.update_columns(updates) if updates.any?
+
+        mirror_to_login_event(record, updates)
+      rescue StandardError => e
+        Sessions.warn("geolocate job failed: #{e.class}: #{e.message}")
+      end
+
+      private
+
+      # When the enriched record is a registry row, its login event was
+      # written before geo resolved — keep the trail consistent.
+      def mirror_to_login_event(record, updates)
+        return unless record.respond_to?(:sessions_token_matches?) # a registry row
+        return unless Sessions::Event.table_exists?
+
+        event_updates = updates.select { |column, _| Sessions::Event.column_names.include?(column.to_s) }
+        return if event_updates.empty?
+
+        Sessions::Event.logins.where(session_id: record.id, country_code: nil).update_all(event_updates)
+      end
+    end
+  end
+end

data/lib/sessions/macros.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Sessions
+  # The host-facing macro. The engine extends `ActiveRecord::Base` with this
+  # module (via `ActiveSupport.on_load(:active_record)`), so the auth model
+  # can declare:
+  #
+  #   class User < ApplicationRecord
+  #     has_sessions
+  #   end
+  #
+  # On a Rails 8 omakase app this ENRICHES the `has_many :sessions` the
+  # authentication generator already wrote (revocation verbs, the events
+  # association, password-change auto-revocation); on a Devise app it also
+  # declares the association itself. Same grammar as the rest of the
+  # ecosystem: `has_credits`, `has_api_keys`, `has_wallets`.
+  #
+  # The macro is a thin forwarder — all behavior lives in
+  # Sessions::HasSessions so it's discoverable, testable, and `include`-able
+  # directly when a host prefers that style.
+  module Macros
+    def has_sessions
+      include Sessions::HasSessions
+    end
+  end
+end

data/lib/sessions/middleware.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Sessions
+  # A tiny rack middleware with two jobs:
+  #
+  #   1. Stash the current request in Sessions::Current so MODEL-level
+  #      callbacks (the omakase adapter's whole login pipeline) can see
+  #      request context. The engine inserts this after
+  #      ActionDispatch::Executor, so the executor's CurrentAttributes
+  #      reset cleans up after every request — no leaks across requests or
+  #      between jobs and web.
+  #
+  #   2. When `config.request_client_hints` is on, advertise `Accept-CH` so
+  #      Chromium browsers attach high-entropy client hints (real platform
+  #      versions, Android device models) to subsequent requests — login
+  #      POSTs are rarely first-navigations, so the hints are reliably
+  #      there exactly when sessions get created.
+  class Middleware
+    # The high-entropy hints the device pipeline consumes (low-entropy ones
+    # are sent by default on every secure request).
+    ACCEPT_CH = "Sec-CH-UA-Platform-Version, Sec-CH-UA-Model, Sec-CH-UA-Full-Version-List"
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      Sessions::Current.request = ActionDispatch::Request.new(env)
+
+      status, headers, body = @app.call(env)
+
+      if Sessions.config.request_client_hints && !(headers["accept-ch"] || headers["Accept-CH"])
+        # Lowercase per the Rack 3 spec; Rack 2 hashes pass it through
+        # verbatim and HTTP header names are case-insensitive on the wire.
+        headers["accept-ch"] = ACCEPT_CH
+      end
+
+      [status, headers, body]
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Sessions
+  # Human, honest device presentation — shared by the registry rows
+  # (Sessions::Model) and the trail (Sessions::Event), which carry the same
+  # parsed device columns:
+  #
+  #   "Chrome 137 on macOS"
+  #   "MyApp 2.4.1 on Pixel 8 (Android 16)"
+  #   "iPhone (iOS 19.5)"
+  #
+  # Frozen-UA tokens are never rendered as facts — versions appear only
+  # where they're real (see Sessions::Device).
+  module DeviceDisplay
+    extend ActiveSupport::Concern
+
+    def device_name
+      return sessions_t("bot", default: "Bot (%{name})", name: try(:browser_name) || "unknown") if bot?
+      return sessions_native_device_name if hotwire_native?
+
+      client = [try(:browser_name), try(:browser_version)].compact.join(" ").presence
+      platform = sessions_os_label
+
+      if client && platform
+        sessions_t("composite", default: "%{client} on %{platform}", client: client, platform: platform)
+      else
+        client || platform || sessions_t("unknown", default: "Unknown device")
+      end
+    end
+
+    # "Madrid, Spain" — or nil when geolocation is unavailable (the UI
+    # omits location cleanly).
+    def location
+      [try(:city), try(:country_name)].compact_blank.join(", ").presence
+    end
+
+    # "🇪🇸" — derived from country_code at render time; no column needed.
+    def country_flag
+      code = try(:country_code).to_s
+      return nil unless code.match?(/\A[A-Za-z]{2}\z/)
+
+      code.upcase.each_codepoint.map { |codepoint| (codepoint + 0x1F1A5).chr(Encoding::UTF_8) }.join
+    end
+
+    # "🇪🇸 Madrid, Spain · IP 83.45.112.7 · Firefox 139 on Windows" — the
+    # one-line WHERE-then-WHAT of a login, ready for security emails,
+    # notification bodies, and admin lists. Location leads (people
+    # recognize places; browser version numbers mean nothing to them), the
+    # IP is the verifiable fact, the device closes. Each part drops out
+    # cleanly when the record lacks it (no geo in dev, no UA on odd
+    # clients). `ip: false` for compact UI like notification feed rows;
+    # `separator:` for plain-text contexts.
+    def source_line(ip: true, separator: " · ")
+      located = [country_flag, location].compact.join(" ").presence
+      address = ip ? (try(:ip_address) || try(:last_seen_ip)).presence : nil
+
+      [located, address && "IP #{address}", device_name].compact.join(separator).presence
+    end
+
+    def hotwire_native?
+      try(:device_type).to_s.start_with?("native_")
+    end
+
+    def native_ios?
+      try(:device_type) == "native_ios"
+    end
+
+    def native_android?
+      try(:device_type) == "native_android"
+    end
+
+    def bot?
+      try(:device_type) == "bot"
+    end
+
+    def web?
+      !hotwire_native? && !bot?
+    end
+
+    def via_oauth?
+      try(:auth_method) == "oauth"
+    end
+
+    def via_password?
+      try(:auth_method) == "password"
+    end
+
+    # The second factor that protected this login, when one did: "totp"
+    # (authenticator apps via devise-two-factor — detected automatically),
+    # "backup_code", or whatever the host tagged ("webauthn" for security
+    # keys / Touch ID as a second factor — see the README's two-factor
+    # recipes). nil for single-factor logins.
+    def second_factor
+      detail = try(:auth_detail)
+      detail.is_a?(Hash) ? detail["second_factor"].presence : nil
+    end
+
+    def second_factor?
+      second_factor.present?
+    end
+
+    # "Google", "GitHub", "password", "passkey"… for "Signed in via %{method}"
+    # copy. nil when the method is unknown (the UI omits the clause).
+    def auth_method_label
+      method = try(:auth_method)
+      return nil if method.blank? || method == "unknown"
+      return try(:auth_provider).to_s.titleize if via_oauth? && try(:auth_provider).present?
+
+      I18n.t("sessions.auth_methods.#{method}", default: method.humanize.downcase)
+    end
+
+    private
+
+    def sessions_native_device_name
+      hardware = [try(:device_model).presence, sessions_os_label && "(#{sessions_os_label})"].compact.join(" ")
+      hardware = sessions_os_label if hardware.blank?
+
+      if try(:app_name).present?
+        client = [try(:app_name), try(:app_version)].compact_blank.join(" ")
+        sessions_t("composite", default: "%{client} on %{platform}", client: client, platform: hardware)
+      else
+        hardware || sessions_t("unknown", default: "Unknown device")
+      end
+    end
+
+    def sessions_os_label
+      [try(:os_name), try(:os_version)].compact_blank.join(" ").presence
+    end
+
+    def sessions_t(key, **options)
+      I18n.t("sessions.device_name.#{key}", **options)
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Sessions
+  # What `has_sessions` includes into the auth model. On Rails 8 omakase
+  # apps the generated `has_many :sessions, dependent: :destroy` already
+  # exists and is left alone; on Devise apps the association is declared
+  # here. Either way the model gains the events trail and the revocation
+  # verbs:
+  #
+  #   current_user.sessions.active
+  #   current_user.session_events.failed_logins.last_24_hours
+  #   current_user.revoke_other_sessions!     # "sign out everywhere else"
+  #   current_user.revoke_all_sessions!       # the account-takeover hammer
+  #
+  # Plus the ASVS 3.3.3 default: changing the password revokes every other
+  # session (`config.revoke_on_password_change`), detected on whichever
+  # digest column the auth stack uses (password_digest / encrypted_password).
+  module HasSessions
+    extend ActiveSupport::Concern
+
+    PASSWORD_COLUMNS = %w[password_digest encrypted_password].freeze
+
+    included do
+      unless reflect_on_association(:sessions)
+        if Sessions::HasSessions.polymorphic_sessions?
+          has_many :sessions, class_name: Sessions.config.session_class, as: :user, dependent: :destroy
+        else
+          has_many :sessions,
+                   class_name: Sessions.config.session_class,
+                   foreign_key: :user_id,
+                   inverse_of: :user,
+                   dependent: :destroy
+        end
+      end
+
+      # delete_all (not destroy) — the trail is append-only data with no
+      # callbacks worth running, and erasing it with the account is the
+      # GDPR-correct default. `Sessions.forget(user)` does the full
+      # right-to-erasure pass including typed identities.
+      has_many :session_events,
+               class_name: "Sessions::Event",
+               as: :authenticatable,
+               dependent: :delete_all
+
+      after_update :sessions_revoke_others_on_password_change, if: :sessions_password_changed?
+    end
+
+    def self.polymorphic_sessions?
+      Sessions.session_model.column_names.include?("user_type")
+    rescue StandardError
+      false
+    end
+
+    # The user's COMPLETE trail slice — owned events PLUS the failed
+    # attempts typed against their email. Failures deliberately never link
+    # to accounts (`session_events` alone can't see them — recording a
+    # failure must not confirm an account exists); matching the resolved
+    # user's own identity here is the safe read side. This is what the
+    # engine's history page renders:
+    #
+    #   user.session_history.recent          # everything, newest first
+    #   user.session_history.failed_logins  # including identity-matched ones
+    def session_history
+      scope = Sessions::Event.where(authenticatable: self)
+
+      identity = Sessions::Event.normalize_identity(try(:email_address) || try(:email))
+      scope = scope.or(Sessions::Event.where(identity: identity)) if identity
+
+      scope
+    end
+
+    # GitHub's "sign out everywhere else": revoke every session except
+    # +current+ (defaulting to the one serving this request, so a controller
+    # can call it bare). Each revocation writes its event and fires hooks.
+    def revoke_other_sessions!(current: nil, by: nil, reason: :logout_everywhere)
+      current = Sessions.current if current.nil?
+
+      scope = sessions
+      scope = scope.where.not(id: current.id) if current.respond_to?(:id)
+      scope.each { |session| session.revoke!(reason: reason, by: by || self) }
+      true
+    end
+
+    # The admin hammer — the account-takeover response. Revokes EVERYTHING,
+    # including the session serving this request if it belongs to this user.
+    def revoke_all_sessions!(by: nil, reason: :admin_revoked)
+      sessions.each { |session| session.revoke!(reason: reason, by: by) }
+      true
+    end
+
+    private
+
+    def sessions_password_changed?
+      return false unless Sessions.config.revoke_on_password_change
+
+      PASSWORD_COLUMNS.any? do |column|
+        respond_to?(:"saved_change_to_#{column}?") && public_send(:"saved_change_to_#{column}?")
+      end
+    end
+
+    # ASVS 3.3.3 / 7.4.3: terminate other sessions on password change. The
+    # session performing the change survives — but only when it belongs to
+    # THIS user (an admin resetting someone's password keeps their own
+    # session, and the target loses all of theirs; a password reset by an
+    # anonymous visitor revokes everything — exactly Rails 8.1's own
+    # behavior, with events).
+    def sessions_revoke_others_on_password_change
+      Sessions.safely("revoke_on_password_change") do
+        current = Sessions.current
+        current = nil unless current && current.try(:user) == self
+
+        revoke_other_sessions!(current: current, by: self, reason: :password_change)
+      end
+    end
+  end
+end