sessions 0.1.3 → 0.2.0

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

@@ -8,10 +8,12 @@ module Sessions
   # explicitly. Either way, ALL gem logic lives here, so the host's model
   # file never goes stale.
   #
-  # One mental model: **rows = active sessions; events = history.** A row is
-  # destroyed on logout/revocation/expiry (instant remote revocation — the
-  # same omakase semantics as Rails 8.1's own password-reset destroy_all),
-  # and its tombstone lives in the `sessions_events` trail.
+  # One mental model: **rows = session lifecycle state; events = audit
+  # history.** `ended_at: nil` means the device is live. Ending a row is an
+  # explicit state transition (`ended_reason`) and never relies on deleting a
+  # row plus later interpreting the absence. That distinction matters in
+  # Devise/Warden mode, where the gem decorates the host session and must
+  # never kick a user unless a durable explicit ending says so.
   #
   # The three lifecycle callbacks observe 100% of both adapters' flows:
   #
@@ -20,7 +22,8 @@ module Sessions
   #                          method, geolocate (when free).
   #   after_create_commit  — write the `login` event, detect new devices,
   #                          enforce the per-user cap, enqueue async geo.
-  #   after_destroy_commit — write the `logout`/`revoked`/`expired` event.
+  #   after_destroy_commit — best-effort compatibility for host-side deletes
+  #                          (account erasure, Rails generator destroy_all).
   #
   # Every callback body is error-isolated: a parsing/geo/event failure may
   # lose a log row; it may NEVER break a sign-in.
@@ -50,9 +53,9 @@ module Sessions
         end
       end
 
-      # Transient revocation context: set by `revoke!` (and the adapters'
-      # logout labeling) before the row is destroyed, read by the
-      # after_destroy_commit event writer.
+      # Transient direct-delete context: legacy/host destroy paths can still
+      # label their compatibility event. Normal gem APIs call `end!` and keep
+      # the row as durable lifecycle state.
       attr_accessor :revocation_reason, :revoked_by
 
       # Set on adopted rows (sessions that predate the gem) so adoption
@@ -61,24 +64,30 @@ module Sessions
 
       before_create :sessions_enrich
       after_create_commit :sessions_record_login
-      after_destroy_commit :sessions_record_end
+      after_destroy_commit :sessions_record_destroyed_end
 
       scope :by_recency, lambda {
         # COALESCE keeps never-touched sessions ordered by creation time,
         # portably across sqlite/postgres/mysql.
         order(Arel.sql("COALESCE(#{table_name}.last_seen_at, #{table_name}.created_at) DESC"))
       }
+      scope :live, lambda {
+        column_names.include?("ended_at") ? where(ended_at: nil) : all
+      }
+      scope :ended, lambda {
+        column_names.include?("ended_at") ? where.not(ended_at: nil) : none
+      }
       scope :active, lambda {
-        where("COALESCE(#{table_name}.last_seen_at, #{table_name}.created_at) >= ?", INACTIVE_AFTER.ago)
+        live.where("COALESCE(#{table_name}.last_seen_at, #{table_name}.created_at) >= ?", INACTIVE_AFTER.ago)
       }
       scope :inactive, lambda {
-        where("COALESCE(#{table_name}.last_seen_at, #{table_name}.created_at) < ?", INACTIVE_AFTER.ago)
+        live.where("COALESCE(#{table_name}.last_seen_at, #{table_name}.created_at) < ?", INACTIVE_AFTER.ago)
       }
     end
 
     class_methods do
       # The user-facing trail rows linked to this registry (`session_id` is
-      # a plain column, no FK — history must survive row destruction).
+      # a plain column, no FK — history must survive lifecycle-row cleanup).
       def sessions_events_for(session_id)
         Sessions::Event.where(session_id: session_id)
       end
@@ -137,15 +146,35 @@ module Sessions
 
     # --- Revocation -----------------------------------------------------------
 
-    # Destroy this session — remote logout, effective on that device's very
-    # next request (both adapters validate liveness per request). Writes a
-    # `revoked` (or `expired`) event with the reason and actor, rotates the
-    # user's remember-me credentials in Devise mode (config.revoke_remember_me),
-    # and fires the on_session_revoked hook.
+    # End this registry row without deleting it. This is the core v0.2
+    # invariant: the row itself is the durable liveness state, and
+    # `sessions_events` remains a read-only audit trail.
+    def end!(reason:, by: nil, at: Time.current, metadata: nil, notify: true)
+      reason = Sessions::EndReason.normalize(reason)
+      event = nil
+      ended_now = false
+
+      with_lock do
+        unless ended?
+          sessions_assign_end_state(reason: reason, by: by, at: at, metadata: metadata)
+          save!
+          ended_now = true
+          event = sessions_record_end_event!(reason: reason, by: by, notify: false)
+        end
+      end
+
+      Sessions.notify_event(event) if notify && event
+      @sessions_ended_now = ended_now
+      self
+    end
+
+    # End this session as an explicit revocation/expiry action. In Devise mode
+    # the next request still proves possession of the per-row token before the
+    # adapter kicks; in Rails-8 auth mode the row id in the signed cookie now
+    # resolves to an ended row and the controller hook refuses it.
     def revoke!(reason: :user_revoked, by: nil)
-      self.revocation_reason = reason
-      self.revoked_by = by
-      destroy!
+      end!(reason: reason, by: by)
+      return self unless @sessions_ended_now
 
       Sessions.safely("revoke_remember_me") { sessions_forget_remember_me! } if Sessions.config.revoke_remember_me
       Sessions.safely("on_session_revoked hook") do
@@ -159,6 +188,8 @@ module Sessions
 
     # Opt-in expiry — false unless the host configured timeouts.
     def sessions_expired?(now = Time.current)
+      return false if ended?
+
       config = Sessions.config
       activity = last_active_at
       return true if config.idle_timeout && activity && activity < now - config.idle_timeout
@@ -167,6 +198,18 @@ module Sessions
       false
     end
 
+    def live?
+      !sessions_column?("ended_at") || try(:ended_at).blank?
+    end
+
+    def ended?
+      !live?
+    end
+
+    def sessions_kicks_on_resume?
+      ended? && Sessions::EndReason.kicks_on_resume?(try(:ended_reason))
+    end
+
     # The throttled last-seen touch: at most one write per
     # config.touch_every per session, issued as a single conditional UPDATE
     # (hot-row-safe under concurrent requests, callback-free, and it also
@@ -176,6 +219,7 @@ module Sessions
       every = Sessions.config.touch_every
       return false unless every
       return false unless sessions_column?("last_seen_at")
+      return false if ended?
 
       now = Time.current
       threshold = now - every
@@ -331,6 +375,24 @@ module Sessions
       false
     end
 
+    def sessions_assign_end_state(reason:, by:, at:, metadata:)
+      sessions_assign_force(ended_at: at, ended_reason: reason)
+      sessions_assign_force(ended_by_type: by.class.name) if by && sessions_column?("ended_by_type")
+      sessions_assign_force(ended_by_id: by.id) if by.respond_to?(:id) && sessions_column?("ended_by_id")
+
+      payload = metadata.presence || sessions_revoked_by_metadata(by)
+      sessions_assign_force(ended_metadata: payload) if payload && sessions_column?("ended_metadata")
+    end
+
+    def sessions_assign_force(attributes)
+      attributes.each do |column, value|
+        name = column.to_s
+        next unless sessions_column?(name)
+
+        self[name] = value
+      end
+    end
+
     # --- after_create_commit: the login event ------------------------------------
 
     def sessions_record_login
@@ -361,8 +423,8 @@ module Sessions
             auth_provider: try(:auth_provider),
             auth_detail: try(:auth_detail).presence,
             # The browser-continuity id rides the trail too: it's what lets
-            # Sessions.last_login answer "how did this browser last sign
-            # in" AFTER logout destroys the row (the "Last used" badge).
+            # Sessions.last_login answer "how did this browser last sign in"
+            # after logout ends the row (the "Last used" badge).
             device_id: try(:device_id).presence,
             metadata: new_device ? { "new_device" => true } : nil
           )
@@ -399,17 +461,16 @@ module Sessions
     end
 
     # The dedup half of browser continuity: prior live rows for the SAME
-    # user on the SAME browser install are superseded by this login. A
-    # quiet destroy on purpose — no on_session_revoked hook, no
-    # remember-me rotation, no trail event (this is housekeeping, not a
-    # security event). Scoped to the user: a shared computer with two
-    # accounts keeps both rows.
+    # user on the SAME browser install are superseded by this login. This is
+    # a quiet lifecycle end on purpose — no on_session_revoked hook, no
+    # remember-me rotation, no trail event (housekeeping, not a security
+    # event). Scoped to the user: a shared computer with two accounts keeps
+    # both rows.
     def sessions_supersede_previous_rows!
       return if try(:device_id).blank?
 
-      self.class.where(user: user, device_id: device_id).where.not(id: id).each do |row|
-        row.revocation_reason = :superseded
-        row.destroy
+      self.class.live.where(user: user, device_id: device_id).where.not(id: id).each do |row|
+        row.end!(reason: :superseded, notify: false)
       end
     end
 
@@ -420,7 +481,7 @@ module Sessions
       cap = Sessions.config.max_sessions_per_user
       return unless cap
 
-      siblings = self.class.where(user: user)
+      siblings = self.class.live.where(user: user)
       overflow = siblings.count - cap
       return unless overflow.positive?
 
@@ -429,46 +490,50 @@ module Sessions
       end
     end
 
-    # --- after_destroy_commit: the end-of-session event ---------------------------
+    # --- after_destroy_commit: legacy/direct-delete compatibility -----------------
 
-    def sessions_record_end
-      Sessions.safely("record_end") do
-        # Account deletion: dependent-destroyed rows of a destroyed owner
-        # write no events (their trail is erased with them — GDPR default).
-        next if user.nil? || user.destroyed?
+    def sessions_record_destroyed_end
+      return if ended?
 
-        reason = revocation_reason&.to_sym
-        next if reason == :superseded
-
-        event_name = case reason
-                     when :logout then "logout"
-                     when :expired then "expired"
-                     else "revoked"
-                     end
-
-        Sessions::Event.record!(
-          sessions_event_identity_attributes.merge(
-            event: event_name,
-            revoked_reason: (event_name == "revoked" ? (reason || :unknown) : nil),
-            metadata: sessions_revoked_by_metadata
-          )
-        )
+      Sessions.safely("record_end") do
+        # Account deletion: dependent-destroyed rows of a destroyed owner write
+        # no events (their trail is erased with them — GDPR default). Direct
+        # host deletes are otherwise treated as legacy explicit ends; v0.2's
+        # public APIs call `end!`/`revoke!` and preserve the row.
+        sessions_record_end_event!(reason: revocation_reason || :unknown, by: revoked_by)
       end
     end
 
-    def sessions_revoked_by_metadata
-      return nil unless revoked_by
+    def sessions_record_end_event!(reason: nil, by: nil, notify: true)
+      return if user.nil? || user.destroyed?
+
+      reason = Sessions::EndReason.normalize(reason || revocation_reason)
+      event_name = Sessions::EndReason.event_for(reason)
+      return unless event_name
+
+      Sessions::Event.record_strict!(
+        sessions_event_identity_attributes.merge(
+          event: event_name,
+          revoked_reason: Sessions::EndReason.revoked_reason_for(reason),
+          metadata: sessions_revoked_by_metadata(by || revoked_by)
+        ),
+        notify: notify
+      )
+    end
+
+    def sessions_revoked_by_metadata(actor = revoked_by)
+      return nil unless actor
 
-      label = if revoked_by.respond_to?(:id) && revoked_by.class.respond_to?(:name)
-                "#{revoked_by.class.name}##{revoked_by.id}"
+      label = if actor.respond_to?(:id) && actor.class.respond_to?(:name)
+                "#{actor.class.name}##{actor.id}"
               else
-                revoked_by.to_s
+                actor.to_s
               end
       { "revoked_by" => label }
     end
 
     # The row's identity, copied onto every event it produces — the trail
-    # must describe the device even after the row is gone.
+    # must describe the device even after the row is ended or later erased.
     def sessions_event_identity_attributes
       {
         session_id: id,

data/lib/sessions/models/event.rb

@@ -3,13 +3,14 @@
 module Sessions
   # The append-only login-activity trail: every successful AND failed login,
   # logout, revocation and expiry — with attempted identity, device, geo,
-  # and the linkage no prior art has: `session_id` points at the live
+  # and the linkage no prior art has: `session_id` points at the lifecycle
   # registry row the event created (or ended), so a suspicious login in the
   # trail is one click away from revoking the session it started.
   #
-  # `session_id` is a plain column with NO foreign key on purpose: registry
-  # rows get destroyed on revoke/logout (rows = active sessions); history
-  # must survive them.
+  # `session_id` is a plain column with NO foreign key on purpose: hosts may
+  # still hard-delete rows for account erasure or legacy Rails destroy_all
+  # flows, and history must survive that. Normal v0.2 logout/revocation ends
+  # the row in place and records an event as audit, not liveness state.
   #
   # Rows are written through one tolerant pipeline (`.record!`): unknown
   # attributes are dropped instead of raising, so hosts can add or remove
@@ -85,20 +86,26 @@ module Sessions
       # tees the event into `config.events`. Returns the Event or nil —
       # never raises into a login.
       def record!(attributes)
-        Sessions.safely("event") do
-          event = new
-          attributes.each do |name, value|
-            next if value.nil?
-
-            event.try(:"#{name}=", value)
-          end
-          event.identity = normalize_identity(event.try(:identity))
-          clamp_string_columns!(event)
-          event.save!
-
-          Sessions.notify_event(event)
-          event
+        Sessions.safely("event") { record_strict!(attributes) }
+      end
+
+      # Same tolerant attribute pipeline as `record!`, but persistence errors
+      # bubble. `Session#end!` writes lifecycle state and its matching audit
+      # event in one transaction; if the event cannot be written, the row must
+      # stay live rather than silently losing the audit trail.
+      def record_strict!(attributes, notify: true)
+        event = new
+        attributes.each do |name, value|
+          next if value.nil?
+
+          event.try(:"#{name}=", value)
         end
+        event.identity = normalize_identity(event.try(:identity))
+        clamp_string_columns!(event)
+        event.save!
+
+        Sessions.notify_event(event) if notify
+        event
       end
 
       # Clamp string columns to their limits BEFORE the insert: the

data/lib/sessions/version.rb

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

data/lib/sessions.rb

@@ -14,6 +14,7 @@ require_relative "sessions/version"
 require_relative "sessions/errors"
 require_relative "sessions/configuration"
 require_relative "sessions/current"
+require_relative "sessions/end_reason"
 require_relative "sessions/ip_address"
 require_relative "sessions/device"
 require_relative "sessions/classifier"
@@ -36,7 +37,7 @@ require_relative "sessions/engine" if defined?(::Rails::Engine)
 #   Sessions.configure { |config| ... }       # one block, in an initializer
 #   has_sessions                              # on your auth model
 #
-#   current_user.sessions.active              # live devices
+#   current_user.sessions.live                # 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"
@@ -245,7 +246,7 @@ module Sessions
       }
     end
 
-    # Right-to-erasure helper: destroy every live session, delete the trail,
+    # Right-to-erasure helper: destroy every session row, 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)
@@ -327,11 +328,11 @@ module Sessions
       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
+        tracking = Adapters::Warden.parse_tracking_state(value[Adapters::Warden::SESSION_KEY])
+        next unless tracking && tracking[:mode] == "credential"
 
-        row = session_model.find_by(id: id)
-        return row if row.respond_to?(:sessions_token_matches?) && row&.sessions_token_matches?(token)
+        row = session_model.live.find_by(id: tracking[:id])
+        return row if row.respond_to?(:sessions_token_matches?) && row&.sessions_token_matches?(tracking[:token])
       end
       nil
     rescue StandardError
@@ -342,7 +343,7 @@ module Sessions
       return nil unless request.respond_to?(:cookie_jar)
 
       id = request.cookie_jar.signed[:session_id]
-      session_model.find_by(id: id) if id
+      session_model.live.find_by(id: id) if id
     rescue StandardError
       nil
     end
@@ -374,12 +375,12 @@ module Sessions
         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)
+        scopes << session_model.live.where(last_seen_at: ...threshold)
+        scopes << session_model.live.where(last_seen_at: nil).where(created_at: ...threshold)
       end
 
       if (lifetime = config.max_session_lifetime)
-        scopes << session_model.where(created_at: ...lifetime.ago)
+        scopes << session_model.live.where(created_at: ...lifetime.ago)
       end
 
       # NOTE: reduce(:or), never `none.or(...)` — a NullRelation stays null
@@ -398,10 +399,10 @@ module Sessions
       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|
+      session_model.live.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)
+        session_model.live.where(owner_keys.zip(Array(owner_key)).to_h)
                      .order(created_at: :asc)
                      .limit(sessions_count - cap)
                      .each do |session|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sessions
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - rameerez
@@ -148,7 +148,7 @@ files:
 - config/locales/es.yml
 - config/routes.rb
 - docs/PRD.md
-- docs/research/01-carhey.md
+- docs/research/01-host-app.md
 - docs/research/02-ecosystem.md
 - docs/research/03-rails-core.md
 - docs/research/04-devise-warden.md
@@ -165,6 +165,7 @@ files:
 - lib/generators/sessions/madmin_generator.rb
 - lib/generators/sessions/templates/add_adoption_key_to_sessions.rb.erb
 - lib/generators/sessions/templates/add_app_build_to_sessions_events.rb.erb
+- lib/generators/sessions/templates/add_lifecycle_to_sessions.rb.erb
 - 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
@@ -185,6 +186,7 @@ files:
 - lib/sessions/configuration.rb
 - lib/sessions/current.rb
 - lib/sessions/device.rb
+- lib/sessions/end_reason.rb
 - lib/sessions/engine.rb
 - lib/sessions/errors.rb
 - lib/sessions/geolocation.rb