sessions 0.1.0

data/lib/generators/sessions/install_generator.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module Sessions
+  module Generators
+    # `rails generate sessions:install` — detects the app's auth stack and
+    # writes the right pieces:
+    #
+    #   Rails 8 omakase auth → ONE migration extending the existing
+    #     `sessions` table (the Devise-extends-`users` precedent) + the
+    #     events table. The generated Session model stays untouched.
+    #
+    #   Devise → the Rails-8-shaped `sessions` table (plus our columns,
+    #     with token_digest populated by the Warden adapter) + the events
+    #     table + a 3-line app-owned Session shell model. The app converges
+    #     on the omakase shape: a future Devise→Rails-auth migration finds
+    #     its table already waiting.
+    #
+    #   Neither → aborts with guidance. The gem decorates a session of
+    #     record; it never creates one.
+    #
+    # Plus, in every mode: the annotated initializer, the SessionsSweepJob
+    # (host-scheduled — the trackdown/nondisposable pattern), and the
+    # post-install steps.
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Install sessions: adaptive migrations, initializer, and sweep job"
+
+      class_option :polymorphic, type: :boolean, default: false,
+                                 desc: "Track multiple Devise scopes/models (polymorphic session owner)"
+      class_option :model, type: :string, default: "Session",
+                           desc: "Session model name (escape hatch for apps with a conflicting Session class)"
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def detect_auth_stack!
+        # Detection is MEMOIZED here, before anything is generated:
+        # create_session_model writes app/models/session.rb a few steps
+        # below, which would otherwise flip omakase_detected? mid-run and
+        # make the post-install message claim the wrong stack.
+        adopt_existing_table?
+        detected_stack
+
+        return if omakase_detected? || devise_detected?
+
+        raise Thor::Error, <<~MSG
+          ❌ sessions couldn't detect an authentication system to decorate.
+
+          The gem tracks the session of record your app already has — it never
+          creates one. Set one up first:
+
+            • Rails 8+ omakase auth:  bin/rails generate authentication
+            • or Devise:              https://github.com/heartcombo/devise
+
+          …then run `rails generate sessions:install` again.
+        MSG
+      end
+
+      def check_for_conflicting_sessions_table!
+        return unless conflicting_sessions_table?
+
+        raise Thor::Error, <<~MSG
+          ❌ A `#{table_name}` table exists but doesn't look like the Rails 8 auth
+          shape (no user reference + ip_address + user_agent columns) — most
+          likely a legacy table (activerecord-session_store?).
+
+          Two ways forward:
+
+            1. Re-run with a different model: rails g sessions:install --model=SessionRecord
+               (and set `config.session_class = "SessionRecord"` in the initializer)
+            2. Migrate/rename the legacy table first, then re-run.
+        MSG
+      end
+
+      def create_migration_files
+        if adopt_existing_table?
+          migration_template "add_sessions_columns.rb.erb",
+                             File.join(db_migrate_path, "add_sessions_columns_to_#{table_name}.rb")
+        else
+          migration_template "create_sessions.rb.erb",
+                             File.join(db_migrate_path, "create_#{table_name}.rb")
+        end
+
+        migration_template "create_sessions_events.rb.erb",
+                           File.join(db_migrate_path, "create_sessions_events.rb")
+      end
+
+      # Devise mode only: the app-owned 3-line shell. All gem logic lives in
+      # the Sessions::Model concern, so this file never goes stale.
+      def create_session_model
+        return if adopt_existing_table? || session_model_file?
+
+        template "session.rb.erb", "app/models/#{model_name.underscore}.rb"
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/sessions.rb"
+      end
+
+      def create_sweep_job
+        template "sessions_sweep_job.rb", "app/jobs/sessions_sweep_job.rb"
+      end
+
+      def display_post_install_message
+        say "\n🔐 The `sessions` gem has been installed#{" (#{detected_stack} detected)" if detected_stack}.",
+            :green
+        say "\nTo complete the setup:"
+
+        migrate_verb = adopt_existing_table? ? "enrich your sessions table" : "create the sessions tables"
+        say "  1. Run 'rails db:migrate' to #{migrate_verb}."
+        say "     ⚠️  You must run migrations before starting your app!", :yellow
+
+        say "  2. Add the macro to your auth model:"
+        say "       class User < ApplicationRecord"
+        say "         has_sessions"
+        say "       end"
+
+        say "  3. Mount the \"Your devices\" page wherever you want it to live:"
+        say "       # config/routes.rb"
+        if devise_detected? && !omakase_detected?
+          say "       authenticate :user do"
+          say "         mount Sessions::Engine => \"/settings/sessions\""
+          say "       end"
+        else
+          say "       mount Sessions::Engine => \"/settings/sessions\""
+        end
+
+        say "  4. Schedule the sweep (retention purge + cap + opt-in expiry):"
+        say "       # config/recurring.yml (Solid Queue)"
+        say "       production:"
+        say "         sessions_sweep:"
+        say "           class: SessionsSweepJob"
+        say "           schedule: every day at 4am"
+
+        say "\nEvery login now lands on the devices page and in the trail:"
+        say "  current_user.sessions.active     # live devices, revocable"
+        say "  current_user.session_history     # the trail — logins, failures, revocations"
+        say "\nEvery session, every device, every login — tracked. 🔐✨\n", :green
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+
+      def model_name
+        options[:model].presence || "Session"
+      end
+
+      def table_name
+        model_name.underscore.pluralize.tr("/", "_")
+      end
+
+      def polymorphic?
+        options[:polymorphic]
+      end
+
+      # --- Detection (each predicate is a test seam) ---------------------------
+
+      def detected_stack
+        @detected_stack ||= if adopt_existing_table? then "Rails authentication"
+                            elsif devise_detected? then "Devise"
+                            end
+      end
+
+      # The Rails-8-shaped table, or the generated Authentication concern's
+      # methods on ApplicationController (the same duck test the runtime
+      # adapter uses — generators run with the app booted). Deliberately NOT
+      # "a session.rb model file exists": in Devise mode this generator
+      # writes that file itself, and a leftover copy must not flip a re-run
+      # into adopt mode against a table that isn't there.
+      def omakase_detected?
+        rails8_shaped_table? || omakase_controller_shape?
+      end
+
+      def omakase_controller_shape?
+        defined?(::ApplicationController) &&
+          ::ApplicationController.private_method_defined?(:start_new_session_for)
+      rescue StandardError
+        false
+      end
+
+      def devise_detected?
+        defined?(::Devise) ? true : false
+      end
+
+      def adopt_existing_table?
+        return @adopt_existing_table if defined?(@adopt_existing_table)
+
+        # Adoption means "enrich the table that's already there", so it
+        # requires that table. An omakase-shaped app installing with
+        # `--model SessionRecord` (because a legacy Session class is in the
+        # way) has NO session_records table yet — that's the create-table
+        # path, not an add-columns migration against nothing.
+        @adopt_existing_table = omakase_detected? && sessions_table_exists?
+      end
+
+      def session_model_file?
+        File.exist?(File.expand_path("app/models/#{model_name.underscore}.rb", destination_root)) ||
+          (defined?(Rails.root) && Rails.root && File.exist?(Rails.root.join("app/models/#{model_name.underscore}.rb")))
+      end
+
+      def sessions_table_exists?
+        ActiveRecord::Base.connection.table_exists?(table_name)
+      rescue StandardError
+        false
+      end
+
+      def rails8_shaped_table?
+        return false unless sessions_table_exists?
+
+        columns = ActiveRecord::Base.connection.columns(table_name).map(&:name)
+        (%w[ip_address user_agent] - columns).empty? && columns.any? { |name| name.end_with?("user_id") }
+      rescue StandardError
+        false
+      end
+
+      def conflicting_sessions_table?
+        sessions_table_exists? && !rails8_shaped_table?
+      end
+    end
+  end
+end

data/lib/generators/sessions/madmin_generator.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Sessions
+  module Generators
+    # `rails generate sessions:madmin` — drop-in admin surfaces for
+    # https://github.com/excid3/madmin: the live session registry (with a
+    # per-row Revoke action) and the login trail with its triage scopes.
+    #
+    # The generated files use only STOCK Madmin APIs, so they work on any
+    # Madmin install and are yours to restyle (swap in your custom fields,
+    # add member actions). Two Madmin footguns are pre-solved in the
+    # generated code: the trail's namespaced model needs an explicit
+    # `resource_class_name` on its flat controller, and the events routes
+    # must be drawn BEFORE `resources :sessions` (or /sessions/events gets
+    # captured as a session id).
+    class MadminGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates/madmin", __dir__)
+
+      desc "Generate Madmin resources + controllers for sessions and the login trail"
+
+      def check_for_madmin!
+        return if madmin_available?
+
+        raise Thor::Error, <<~MSG
+          ❌ Madmin isn't loaded in this app (gem "madmin").
+
+          This generator produces Madmin resources for the session registry and
+          the login trail. For other admin frameworks, build on the same
+          primitives it uses: Session.active / session.revoke! /
+          Sessions::Event scopes (failed_logins, last_24_hours, …).
+        MSG
+      end
+
+      def create_resources
+        template "session_resource.rb", "app/madmin/resources/session_resource.rb"
+        template "event_resource.rb", "app/madmin/resources/sessions/event_resource.rb"
+      end
+
+      def create_controllers
+        template "sessions_controller.rb", "app/controllers/madmin/sessions_controller.rb"
+        template "session_events_controller.rb", "app/controllers/madmin/session_events_controller.rb"
+      end
+
+      def display_post_install_message
+        say "\n🔐 Madmin resources for sessions installed.", :green
+        say "\nTo complete the setup:"
+
+        say "  1. Add the routes where you draw your Madmin routes"
+        say "     (config/routes/madmin.rb in most apps):"
+        say ""
+        say "       # Login trail — drawn BEFORE `resources :sessions`, or"
+        say "       # /sessions/events would match as a session id."
+        say "       namespace :sessions do"
+        say "         resources :events, only: [ :index, :show ], controller: \"/madmin/session_events\""
+        say "       end"
+        say ""
+        say "       resources :sessions, only: [ :index, :show ] do"
+        say "         member do"
+        say "           post :revoke"
+        say "         end"
+        say "       end"
+
+        say "\n  2. (Optional) Group them in the sidebar — both resources declare"
+        say "     `parent: \"Security\"`; pre-seed its position in an initializer:"
+        say ""
+        say "       Madmin.menu.before_render do"
+        say "         add label: \"Security\", position: 91"
+        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.by_recency` and `user.session_history.recent`"
+        say "     — the README's Admin section has the full recipe."
+
+        say "\nRevoking from the index destroys the row: that device is signed out"
+        say "on its very next request, and the revocation lands in the trail with"
+        say "admin attribution. 🔐\n", :green
+      end
+
+      private
+
+      def madmin_available?
+        defined?(::Madmin) ? true : false
+      end
+
+      def session_class
+        Sessions.config.session_class
+      rescue StandardError
+        "Session"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Enriches the `<%= table_name %>` table that `rails generate authentication`
+# created (precedent: Devise's add_devise_to_users extends your users table).
+# Your existing columns and rows are untouched: ip_address/user_agent keep
+# holding their login-time values; everything below is filled by the sessions
+# gem from the next sign-in on.
+class AddSessionsColumnsTo<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    change_table :<%= table_name %>, bulk: true do |t|
+      # Devise/Warden mode only: SHA-256 of a random token whose raw value
+      # lives ONLY in the user's own session (OWASP: never persist raw
+      # session identifiers). Stays NULL on Rails-8-auth rows — there the
+      # signed cookie is the credential and nothing secret needs storing.
+      t.string :token_digest
+
+      # The Warden scope ("user") — multi-scope Devise apps.
+      t.string :scope
+
+      # How this session started: password / oauth / google_one_tap /
+      # passkey / magic_link / otp / sso / token / unknown — plus the
+      # provider ("google", "apple", "github") and per-method extras
+      # (One Tap's select_by, passkey UV/BS flags, OAuth scopes…).
+      t.string :auth_method
+      t.string :auth_provider
+      t.send(json_column_type, :auth_detail)
+
+      # Parsed device intelligence — projections of the raw user_agent
+      # ("Chrome 137 on macOS", "MyApp 2.4.1 on Pixel 8 (Android 16)").
+      t.string :browser_name
+      t.string :browser_version
+      t.string :os_name
+      t.string :os_version
+      t.string :device_type   # desktop / smartphone / tablet / native_ios / native_android / bot / unknown
+      t.string :device_model  # "iPhone15,2", "Pixel 8" — when knowable
+      t.string :app_name      # Hotwire Native apps
+      t.string :app_version
+      t.string :app_build
+      t.send(json_column_type, :client_hints) # raw Sec-CH-UA* + X-Client-* headers, for re-parsing
+
+      # Approximate location via the trackdown gem (soft dependency) —
+      # stays NULL without it and the UI omits location cleanly.
+      t.string :country_code, limit: 2
+      t.string :country_name
+      t.string :city
+      t.string :region
+
+      # Browser continuity: a random id minted at login into a signed,
+      # long-lived cookie identifying the BROWSER INSTALL (never the user;
+      # worthless as a credential). Lets a repeat login from the same
+      # browser supersede its old row instead of stacking duplicate
+      # devices — robust to browser updates, since identity is the cookie,
+      # not the user agent.
+      t.string :device_id, limit: 36
+
+      # The throttled activity touch (at most one write per
+      # config.touch_every) — the column the Rails security guide's own
+      # Session.sweep recommendation always needed.
+      t.datetime :last_seen_at
+      t.string :last_seen_ip, limit: 45 # refreshed with the touch (roaming devices)
+    end
+
+    add_index :<%= table_name %>, :device_id
+    add_index :<%= table_name %>, :token_digest, unique: true
+    add_index :<%= table_name %>, :auth_method
+    add_index :<%= table_name %>, :auth_provider
+    add_index :<%= table_name %>, :country_code
+    add_index :<%= table_name %>, :last_seen_at
+  end
+
+  private
+
+  # :jsonb on PostgreSQL, :json elsewhere — same adaptive pattern as the
+  # rest of the gem ecosystem (chats, api_keys, …). match? (not equality):
+  # PostGIS apps report adapter_name "PostGIS" and are PostgreSQL too.
+  def json_column_type
+    return :jsonb if connection.adapter_name.match?(/postg/i)
+
+    :json
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+# The Rails-8-shaped sessions table for a Devise app: one row = one
+# signed-in device, destroyed on logout/revocation (rows = active sessions;
+# history lives in sessions_events). Deliberately the SAME base shape
+# `rails generate authentication` creates — so if you ever migrate from
+# Devise to Rails auth, your sessions table is already waiting.
+class Create<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    create_table :<%= table_name %>, id: primary_key_type do |t|
+      # The Rails 8 authentication-generator base…
+<% if polymorphic? -%>
+      # …with a polymorphic owner (--polymorphic): every Devise scope/model
+      # gets tracked, each row remembering whose it is.
+      t.references :user, polymorphic: true, null: false, type: foreign_key_type, index: true
+<% else -%>
+      t.references :user, null: false, foreign_key: true, type: foreign_key_type
+<% end -%>
+      t.string :ip_address, limit: 45
+      t.text :user_agent # text, not string: native UAs overflow MySQL's varchar(255)
+
+      # Devise/Warden mode: SHA-256 of a random token whose raw value lives
+      # ONLY in the user's own session (OWASP: never persist raw session
+      # identifiers). The Warden adapter validates it on every request —
+      # destroy the row and that device is signed out on its next request.
+      t.string :token_digest
+
+      # The Warden scope ("user") — multi-scope Devise apps.
+      t.string :scope
+
+      # How this session started: password / oauth / google_one_tap /
+      # passkey / magic_link / otp / sso / token / unknown — plus the
+      # provider and per-method extras.
+      t.string :auth_method
+      t.string :auth_provider
+      t.send(json_column_type, :auth_detail)
+
+      # Parsed device intelligence — projections of the raw user_agent
+      # ("Chrome 137 on macOS", "MyApp 2.4.1 on Pixel 8 (Android 16)").
+      t.string :browser_name
+      t.string :browser_version
+      t.string :os_name
+      t.string :os_version
+      t.string :device_type   # desktop / smartphone / tablet / native_ios / native_android / bot / unknown
+      t.string :device_model  # "iPhone15,2", "Pixel 8" — when knowable
+      t.string :app_name      # Hotwire Native apps
+      t.string :app_version
+      t.string :app_build
+      t.send(json_column_type, :client_hints) # raw Sec-CH-UA* + X-Client-* headers, for re-parsing
+
+      # Approximate location via the trackdown gem (soft dependency).
+      t.string :country_code, limit: 2
+      t.string :country_name
+      t.string :city
+      t.string :region
+
+      # Browser continuity: a random id minted at login into a signed,
+      # long-lived cookie identifying the BROWSER INSTALL (never the user).
+      # Lets a repeat login from the same browser supersede its old row
+      # instead of stacking duplicate devices.
+      t.string :device_id, limit: 36
+
+      # The throttled activity touch (at most one write per config.touch_every).
+      t.datetime :last_seen_at
+      t.string :last_seen_ip, limit: 45
+
+      t.timestamps
+    end
+
+    add_index :<%= table_name %>, :device_id
+    add_index :<%= table_name %>, :token_digest, unique: true
+    add_index :<%= table_name %>, :auth_method
+    add_index :<%= table_name %>, :auth_provider
+    add_index :<%= table_name %>, :country_code
+    add_index :<%= table_name %>, :last_seen_at
+  end
+
+  private
+
+  # Honor the host's configured primary key type (uuid vs bigint). Reads the
+  # same setting `rails g model` uses, so an app generated with
+  # `config.generators { |g| g.orm :active_record, primary_key_type: :uuid }`
+  # gets uuid sessions tables and uuid foreign keys, automatically.
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [ primary_key_type, foreign_key_type ]
+  end
+
+  # match? (not equality): PostGIS apps report adapter_name "PostGIS" and
+  # are PostgreSQL too.
+  def json_column_type
+    return :jsonb if connection.adapter_name.match?(/postg/i)
+
+    :json
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# The append-only login-activity trail: every successful AND failed login,
+# logout, revocation, and expiry — with attempted identity, device, geo, and
+# the trail ↔ registry linkage (`session_id`). Trail rows survive their
+# session row (that's the point); the SessionsSweepJob purges them past
+# config.events_retention (12 months by default — CNIL's recommendation for
+# security logs).
+class CreateSessionsEvents < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    # The trail mirrors the host's primary-key choice. This matters beyond
+    # consistency: uuid apps put events into uuid polymorphic associations
+    # (a Noticed notification's record, an audit ledger's subject…) and a
+    # bigint id assigned to a uuid column type-casts to NULL — silently.
+    create_table :sessions_events, id: primary_key_type do |t|
+      t.string :event, null: false # login / failed_login / logout / revoked / expired
+
+      # Polymorphic and NULLABLE: failed attempts against unknown identities
+      # have no account to point at — the typed `identity` column below is
+      # what correlates them.
+      t.references :authenticatable, polymorphic: true, type: foreign_key_type, index: false
+      t.string :scope
+
+      # The trail ↔ registry linkage. A plain column, NO foreign key: the
+      # registry row it points at gets destroyed on revoke; history must
+      # survive. A suspicious login here is one lookup away from revoking
+      # the live session it created.
+      t.send(session_id_column_type, :session_id)
+
+      t.string :identity # email-as-typed (normalized), even for unknown accounts
+      # The browser-continuity id (same value as the registry row's) — lets
+      # `Sessions.last_login(request)` answer "how did this browser last
+      # sign in" after logout, powering the "Last used" login-page badge.
+      t.string :device_id, limit: 36
+      t.string :auth_method
+      t.string :auth_provider
+      t.send(json_column_type, :auth_detail)
+      t.string :failure_reason # devise message symbol / omniauth error type, verbatim
+      t.string :revoked_reason # user_revoked / admin_revoked / password_change /
+      #                          logout_everywhere / pruned / unknown
+
+      t.string :ip_address, limit: 45
+      t.text :user_agent
+      t.send(json_column_type, :client_hints)
+      t.string :browser_name
+      t.string :browser_version
+      t.string :os_name
+      t.string :os_version
+      t.string :device_type
+      t.string :device_model
+      t.string :app_name
+      t.string :app_version
+
+      # Geo via trackdown (soft dependency). lat/lng precision-reduced per
+      # config.geo_precision (2 decimals ≈ 1km) — privacy now,
+      # impossible-travel math later.
+      t.string :country_code, limit: 2
+      t.string :country_name
+      t.string :city
+      t.string :region
+      t.decimal :latitude, precision: 10, scale: 7
+      t.decimal :longitude, precision: 10, scale: 7
+
+      t.string :request_id
+      t.string :context # "controller#action"
+      t.send(json_column_type, :metadata)
+
+      t.datetime :occurred_at, null: false # append-only: no updated_at
+    end
+
+    add_index :sessions_events, %i[authenticatable_type authenticatable_id occurred_at],
+              name: "index_sessions_events_on_authenticatable_and_occurred_at"
+    add_index :sessions_events, %i[event occurred_at]
+    add_index :sessions_events, %i[device_id occurred_at]
+    add_index :sessions_events, :identity
+    add_index :sessions_events, :ip_address
+    add_index :sessions_events, :session_id
+    add_index :sessions_events, :occurred_at
+  end
+
+  private
+
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [ primary_key_type, foreign_key_type ]
+  end
+
+  # session_id must match the sessions table's PRIMARY KEY type (uuid hosts
+  # store uuid linkage; bigint hosts store bigint).
+  def session_id_column_type
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    setting == :uuid ? :uuid : :bigint
+  end
+
+  # match? (not equality): PostGIS apps report adapter_name "PostGIS" and
+  # are PostgreSQL too.
+  def json_column_type
+    return :jsonb if connection.adapter_name.match?(/postg/i)
+
+    :json
+  end
+end