sessions 0.1.3 → 0.2.0

data/lib/sessions/adapters/omakase.rb

@@ -12,17 +12,16 @@ module Sessions
     # 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.
+    #      observe `start_new_session_for` (create!) for logins. Normal
+    #      logout is intercepted by ControllerHooks and ends the row in
+    #      place; host-side destroy_all (Rails password reset/account erasure)
+    #      is still tolerated by the model's destroy compatibility hook.
     #
     #   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.
+    #      (labeling the lifecycle end as a logout) is clean.
     #
     #   3. The generated SessionsController#create gets FailedLoginHooks
     #      prepended: `authenticate_by` is deliberately silent on failure
@@ -129,32 +128,77 @@ module Sessions
       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.
+        # After the host resolves the session row, refuse ended lifecycle rows,
+        # enforce opt-in expiry and apply the throttled last_seen_at touch.
+        # In Rails 8 auth this row is the session of record, so an ended row
+        # must be treated as unauthenticated even though it still exists for
+        # audit/history.
         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) }
+          if session.ended?
+            Sessions.safely("omakase.ended") { sessions_clear_omakase_session_cookie }
             ::Current.session = nil if defined?(::Current) && ::Current.respond_to?(:session=)
             nil
+          elsif session.sessions_expired?
+            # The lifecycle row is the server-side liveness source of truth.
+            # If the end transition rolls back (for example, the audit event
+            # cannot be written), do not clear the Rails auth cookie: that
+            # would log the user out while leaving a stale `.live` row behind.
+            # Source: Warden's session_limitable pattern also kicks only after
+            # a durable server-side state change:
+            # https://github.com/devise-security/devise-security/blob/v0.18.0/lib/devise-security/hooks/session_limitable.rb
+            if sessions_end_omakase_session(session, reason: :expired, context: "omakase.expire")
+              Sessions.safely("omakase.expire.cookie") { sessions_clear_omakase_session_cookie }
+              ::Current.session = nil if defined?(::Current) && ::Current.respond_to?(:session=)
+              nil
+            else
+              session
+            end
           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".
+        # Rails' generated auth calls `Current.session.destroy` here:
+        # https://github.com/rails/rails/blob/main/railties/lib/rails/generators/rails/authentication/templates/app/controllers/concerns/authentication.rb.tt
+        # v0.2 preserves the row and marks it ended instead, because the row is
+        # now the lifecycle source of truth. We still delete the signed cookie
+        # exactly like the generated method.
         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=)
+          session = defined?(::Current) ? ::Current.try(:session) : nil
+          if session.respond_to?(:end!)
+            sessions_end_omakase_session!(session, reason: :logout, context: "omakase.terminate")
+            ::Current.session = nil if defined?(::Current) && ::Current.respond_to?(:session=)
+            sessions_clear_omakase_session_cookie
+          else
+            super
           end
-          super
+        end
+
+        def sessions_clear_omakase_session_cookie
+          cookies.delete(:session_id)
+        end
+
+        def sessions_end_omakase_session(session, reason:, context:)
+          session.end!(reason: reason)
+          true
+        rescue StandardError => e
+          Sessions.warn("#{context} failed open: #{e.class}: #{e.message}")
+          false
+        end
+
+        def sessions_end_omakase_session!(session, reason:, context:)
+          session.end!(reason: reason)
+          true
+        rescue StandardError => e
+          # Explicit logout must either persist its lifecycle transition or
+          # abort before deleting the cookie. Otherwise the tracking layer
+          # silently changes auth state while the row still says "live".
+          Sessions.warn("#{context} aborted auth teardown: #{e.class}: #{e.message}")
+          raise
         end
       end
 

data/lib/sessions/adapters/warden.rb

@@ -13,18 +13,25 @@ module Sessions
     # to a sessions-table ROW, turning "exactly one session" into "N devices,
     # each individually revocable" (→ docs/research/04-devise-warden.md §5).
     #
-    #   login  — mint a random token, store [row_id, raw_token] in the
+    #   login  — mint a random token, store structured tracking state in the
     #            per-scope warden session (it survives Warden's :renew SID
     #            rotation and is deleted by Warden itself on logout; we
     #            never key on the Rack SID), persist only the SHA-256
     #            digest on the row.
     #   fetch  — per-request liveness check: row exists + digest matches
-    #            (constant-time) → throttled touch; row gone (revoked!) →
-    #            the proven session_limitable kick: clear, logout, throw.
+    #            (constant-time) + row is live → throttled touch; row ended
+    #            for an explicit reason → the proven session_limitable kick:
+    #            clear, logout, throw. Missing/mismatched tracking fails open
+    #            unless a legacy v0.1.x event tombstone proves a pre-lifecycle
+    #            remote revocation.
     #   failure — record the failed attempt with the typed identity.
-    #   logout — destroy the row, labeled as a logout.
+    #   logout — mark the row ended, labeled as a logout.
     module Warden
-      # Key inside `warden.session(scope)` holding [row_id, raw_token].
+      # Key inside `warden.session(scope)` holding the sessions gem tracking
+      # state. v0.2 writes a small Hash (`id`, `token`, `mode`) instead of the
+      # old `[row_id, raw_token]` tuple so a nil token can never accidentally
+      # read like an auth credential. The parser still accepts arrays because
+      # production users may carry v0.1.x cookies during deploy.
       SESSION_KEY = "sessions"
 
       # Rememberable can restore a user on background/native JSON requests
@@ -145,7 +152,7 @@ module Sessions
         row.sessions_skip_supersede = skip_supersede
         Sessions.with_request(request) { row.save! }
 
-        warden.session(scope)[SESSION_KEY] = [row.id, token]
+        warden.session(scope)[SESSION_KEY] = tracking_state(row, token: token, mode: "credential")
         row
       end
 
@@ -168,8 +175,8 @@ module Sessions
         end
         return if data == :skip
 
-        session_token = data && data[:login]
-        if session_token.nil?
+        tracking = parse_tracking_state(data && data[:login])
+        if tracking.nil?
           if data && data[:pending_login]
             activate_pending_login(record, warden, scope, data[:pending_login])
           else
@@ -179,34 +186,65 @@ module Sessions
         end
 
         # The lookup is NOT wrapped in `safely`: an ERRORED lookup and a
-        # MISSING row must be distinguishable. A row that's genuinely gone
-        # (or a token that doesn't match) means revocation → kick. A raised
-        # lookup — the sessions table unreachable, a timeout, a migration
-        # mid-deploy — means the TRACKING layer is down, and tracking must
-        # never break authentication: fail OPEN, let the request through
-        # untracked, try again next request.
+        # MISSING row must be distinguishable from a raised lookup, but a
+        # missing/mismatched tracking row is still not automatically auth
+        # state. In v0.2, only a matching row whose own ended_reason is
+        # explicit may kick. The event lookup below is legacy-only for v0.1.x
+        # cookies whose rows were already destroyed before lifecycle columns
+        # existed.
+        # A raised lookup — the sessions table unreachable, a timeout, a
+        # migration mid-deploy — means the TRACKING layer is down, and
+        # tracking must never break authentication: fail OPEN, let the request
+        # through untracked, try again next request.
         begin
-          id, token = session_token
-          found = Sessions.session_model.find_by(id: id)
-          row = if found&.sessions_token_matches?(token)
-                  found
-                elsif token.nil? && existing_row_session?(found, record, scope, warden.request)
-                  found
-                end
+          found = Sessions.session_model.find_by(id: tracking[:id])
+          if tracking[:mode] == "hint"
+            # v0.1.3 intentionally reattached remember-me restores to an
+            # existing device row without writing another login event, storing
+            # [row_id, nil] in Warden. That is fine as a tracking hint, but it
+            # must never become an auth/liveness check. Touch when the signed
+            # browser-continuity cookie still agrees; otherwise clear only the
+            # gem's tracking key and let Devise/Rails keep owning auth.
+            # Source: https://github.com/rameerez/sessions/blob/v0.1.3/CHANGELOG.md
+            if existing_row_session?(found, record, scope, warden.request) && found.live?
+              Sessions.safely("warden.remembered_existing.touch") { found.touch_last_seen!(warden.request) }
+            elsif (replacement = live_replacement_for(found, record, scope, warden.request))
+              attach_existing_row(replacement, warden, scope)
+            else
+              clear_tracking_key(warden, scope)
+            end
+            return
+          end
+
+          row = found if found&.sessions_token_matches?(tracking[:token])
         rescue StandardError => e
           Sessions.warn("warden.fetch failed open: #{e.class}: #{e.message}")
           return
         end
 
         if row.nil?
-          # Revoked (the row is gone) or tampered (digest mismatch): the
-          # proven session_limitable sequence — log the scope out and hand
-          # control to the failure app. NOT wrapped in `safely`: the throw
-          # is control flow, not an error.
-          kick!(warden, scope)
+          if legacy_explicitly_ended_session?(tracking[:id])
+            # Explicit remote revocation/expiry is the one intentional place
+            # where a legacy v0.1.x destroyed row may still end a Devise
+            # session. v0.2 rows should be present and ended in place.
+            kick!(warden, scope)
+          else
+            clear_tracking_key(warden, scope)
+          end
+        elsif row.ended?
+          if row.sessions_kicks_on_resume?
+            kick!(warden, scope)
+          elsif (replacement = live_replacement_for(row, record, scope, warden.request))
+            attach_existing_row(replacement, warden, scope)
+          else
+            clear_tracking_key(warden, scope)
+          end
         elsif Sessions.safely("warden.expired?") { row.sessions_expired? }
-          Sessions.safely("warden.expire") { row.revoke!(reason: :expired) }
-          kick!(warden, scope)
+          # Expiry is gem-initiated, so it must be durable before we touch
+          # Warden auth state. If the lifecycle write rolls back, fail open:
+          # the user stays authenticated and the next request can retry the
+          # expiry instead of leaving an orphan `.live` row.
+          kick!(warden, scope) if end_row_for_auth_teardown(row, reason: :expired, context: "warden.expire")
         else
           Sessions.safely("warden.touch") { row.touch_last_seen!(warden.request) }
         end
@@ -300,7 +338,7 @@ module Sessions
         device_id = device_id_from_request(warden.request)
         return if device_id.blank?
 
-        rows = Sessions.session_model.where(user: record, device_id: device_id)
+        rows = Sessions.session_model.live.where(user: record, device_id: device_id)
         rows = rows.where(scope: scope.to_s) if Sessions.session_model.column_names.include?("scope")
         rows.order(created_at: :desc).first
       rescue StandardError
@@ -308,7 +346,7 @@ module Sessions
       end
 
       def attach_existing_row(row, warden, scope)
-        warden.session(scope)[SESSION_KEY] = [row.id, nil]
+        warden.session(scope)[SESSION_KEY] = tracking_state(row, mode: "hint")
         Sessions.safely("warden.remembered_existing.touch") { row.touch_last_seen!(warden.request) }
         row
       end
@@ -327,6 +365,19 @@ module Sessions
         false
       end
 
+      def live_replacement_for(row, record, scope, request)
+        device_id = row&.try(:device_id).presence || device_id_from_request(request)
+        return if device_id.blank?
+
+        model = Sessions.session_model
+        rows = model.live.where(user: record, device_id: device_id)
+        rows = rows.where(scope: scope.to_s) if model.column_names.include?("scope")
+        rows = rows.where.not(id: row.id) if row
+        rows.order(created_at: :desc).first
+      rescue StandardError
+        nil
+      end
+
       def device_id_from_request(request)
         return unless request.respond_to?(:cookie_jar)
 
@@ -386,10 +437,10 @@ module Sessions
 
       def adopted_row(record, scope, adoption_key:)
         model = Sessions.session_model
-        rows = model.where(user: record)
+        rows = model.live.where(user: record)
         rows = rows.where(scope: scope.to_s) if model.column_names.include?("scope")
 
-        row = model.find_by(adoption_key: adoption_key) if adoption_key_column?(model) && adoption_key.present?
+        row = model.live.find_by(adoption_key: adoption_key) if adoption_key_column?(model) && adoption_key.present?
         row = nil unless adopted_row?(row)
         row ||= rows.order(created_at: :desc).detect { |candidate| adopted_row?(candidate) }
 
@@ -429,13 +480,60 @@ module Sessions
         model.column_names.include?("adoption_key")
       end
 
+      def clear_tracking_key(warden, scope)
+        warden.session(scope).delete(SESSION_KEY)
+      rescue StandardError
+        nil
+      end
+
+      def tracking_state(row, mode:, token: nil)
+        {
+          "v" => 2,
+          "id" => row.id,
+          "token" => token,
+          "mode" => mode
+        }
+      end
+
+      def parse_tracking_state(value)
+        case value
+        when Hash
+          id = value["id"] || value[:id]
+          token = value["token"] || value[:token]
+          mode = (value["mode"] || value[:mode]).presence
+        when Array
+          id, token = value
+          mode = token.present? ? "credential" : "hint"
+        else
+          return nil
+        end
+
+        return nil if id.blank?
+
+        mode = token.present? ? "credential" : (mode || "hint")
+        { id: id, token: token, mode: mode }
+      rescue StandardError
+        nil
+      end
+
+      def legacy_explicitly_ended_session?(id)
+        return false if id.blank?
+
+        events = Sessions::Event.where(session_id: id)
+        events.expirations.exists? ||
+          events.revocations.where.not(revoked_reason: "superseded").exists?
+      rescue StandardError => e
+        Sessions.warn("warden.fetch legacy end-event lookup failed open: #{e.class}: #{e.message}")
+        false
+      end
+
       # SCOPE-PRECISE teardown: only this scope's warden entries go (the
       # serialized user key and our token stash) — an admin scope riding
       # the same rack session, and unrelated host session data (carts,
       # locale, return-to paths), survive a user-scope kick. Deleting the
       # keys BEFORE logout matters: our before_logout hook then finds no
-      # token and records nothing (a kick is not a logout — the revocation
-      # event was already written by whoever destroyed the row).
+      # token and records nothing (a kick is not a logout — the lifecycle
+      # reason/event were already written by the explicit ending).
       def kick!(warden, scope)
         warden.raw_session.delete("warden.user.#{scope}.key")
         warden.raw_session.delete("warden.user.#{scope}.session")
@@ -483,9 +581,8 @@ module Sessions
       # --- Hook 4: logout ---------------------------------------------------------
 
       # Fires once per scope (including forced logouts: timeout, lockout,
-      # our own revocation kick). If the row is already gone — revoked from
-      # another device — there's nothing to do; the `revoked` event was
-      # written by whoever destroyed it.
+      # our own revocation kick). If the row is already ended, there's nothing
+      # to do; lifecycle state is idempotent.
       #
       # CRITICAL: read the RAW session here, never `warden.session(scope)`.
       # Warden's logout deletes `@users[scope]` BEFORE running before_logout
@@ -494,19 +591,29 @@ module Sessions
       # logout came from a hook that logs out and throws (Devise's
       # activatable on unconfirmed/locked accounts, timeoutable) that loops:
       # activatable → logout → us → re-auth → activatable → … SystemStackError.
-      def record_logout(_record, warden, opts)
-        Sessions.safely("warden.logout") do
-          scope = opts[:scope]
-          data = warden.raw_session["warden.user.#{scope}.session"]&.dig(SESSION_KEY)
-          next unless data
+      def record_logout(record, warden, opts)
+        scope = opts[:scope]
+        tracking = parse_tracking_state(warden.raw_session["warden.user.#{scope}.session"]&.dig(SESSION_KEY))
+        return unless tracking
 
-          id, token = data
-          row = Sessions.session_model.find_by(id: id)
-          next unless row&.sessions_token_matches?(token)
+        row = Sessions.session_model.find_by(id: tracking[:id])
+        return unless row
+        return unless row.live?
 
-          row.revocation_reason ||= :logout
-          row.destroy
-        end
+        token_backed = tracking[:mode] == "credential" && row.sessions_token_matches?(tracking[:token])
+        tokenless_known_device = tracking[:mode] == "hint" &&
+                                 existing_row_session?(row, record, scope, warden.request)
+        return unless token_backed || tokenless_known_device
+
+        # Warden 1.2.9 runs before_logout callbacks before deleting the
+        # serialized session keys (proxy.rb#logout). Raising here aborts the
+        # auth teardown, so an audit/lifecycle persistence failure cannot log
+        # the user out while leaving the row live.
+        # Source: https://github.com/wardencommunity/warden/blob/v1.2.9/lib/warden/proxy.rb#L266-L279
+        row.end!(reason: :logout)
+      rescue StandardError => e
+        Sessions.warn("warden.logout aborted auth teardown: #{e.class}: #{e.message}")
+        raise
       end
 
       def warden_default_scope(env)
@@ -529,6 +636,14 @@ module Sessions
       rescue StandardError
         false
       end
+
+      def end_row_for_auth_teardown(row, reason:, context:)
+        row.end!(reason: reason)
+        true
+      rescue StandardError => e
+        Sessions.warn("#{context} failed open: #{e.class}: #{e.message}")
+        false
+      end
     end
   end
 end

data/lib/sessions/configuration.rb

@@ -55,9 +55,10 @@ module Sessions
 
     # Terminate other sessions when the user's password changes (ASVS 3.3.3
     # / 7.4.3; Laravel's logoutOtherDevices and Phoenix's token nuke are the
-    # cross-framework precedent; Rails 8.1's own password reset already
-    # destroy_alls). Wired by `has_sessions` via an after_update on the
-    # password digest column, so it works on both auth stacks.
+    # cross-framework precedent; Rails 8.1's generated password reset uses
+    # `destroy_all`, which our direct-delete compatibility hook still labels
+    # honestly). Wired by `has_sessions` via an after_update on the password
+    # digest column, so it works on both auth stacks.
     attr_accessor :revoke_on_password_change
 
     # Devise mode only: revoking a session also rotates the user's

data/lib/sessions/current.rb

@@ -9,10 +9,10 @@ module Sessions
   #
   # Why it exists: the omakase adapter records logins from MODEL callbacks
   # (Session#after_create_commit — the only seam that captures 100% of the
-  # generated lifecycle, including 8.1's password-reset destroy_all), and
-  # model callbacks have no request. This carries the request reference
-  # across that gap. Background jobs and console code simply see nil and the
-  # pipeline degrades gracefully (rows parse from their own stored columns).
+  # generated login lifecycle), and model callbacks have no request. This
+  # carries the request reference across that gap. Background jobs and
+  # console code simply see nil and the pipeline degrades gracefully (rows
+  # parse from their own stored columns).
   class Current < ActiveSupport::CurrentAttributes
     # The ActionDispatch::Request being served, if any.
     attribute :request

data/lib/sessions/end_reason.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Sessions
+  # Canonical lifecycle vocabulary for registry rows.
+  #
+  # v0.1.x used "row missing + event tombstone" as the revocation signal. That
+  # made Warden infer security intent from absence, which is exactly how quiet
+  # housekeeping ended up looking too much like a real logout. v0.2 moves the
+  # source of truth onto the session row itself: events are audit trail, not
+  # liveness state.
+  #
+  # External precedents:
+  # - Rails 8 generated auth resolves a Session row on every request:
+  #   https://github.com/rails/rails/blob/main/railties/lib/rails/generators/rails/authentication/templates/app/controllers/concerns/authentication.rb.tt
+  # - Rodauth's active_sessions feature keeps explicit active-session state
+  #   separate from audit logging:
+  #   https://github.com/jeremyevans/rodauth/blob/master/lib/rodauth/features/active_sessions.rb
+  module EndReason
+    LOGOUT = "logout"
+    EXPIRED = "expired"
+    SUPERSEDED = "superseded"
+
+    REVOKED = %w[
+      user_revoked
+      admin_revoked
+      password_change
+      logout_everywhere
+      pruned
+      unknown
+    ].freeze
+
+    INTERNAL = [SUPERSEDED].freeze
+    EVENTS = {
+      LOGOUT => "logout",
+      EXPIRED => "expired"
+    }.freeze
+
+    KICKING = ([LOGOUT, EXPIRED] + REVOKED).freeze
+
+    module_function
+
+    def normalize(reason)
+      value = reason.to_s.presence || "unknown"
+      value == "revoked" ? "user_revoked" : value
+    end
+
+    def internal?(reason)
+      INTERNAL.include?(normalize(reason))
+    end
+
+    def kicks_on_resume?(reason)
+      KICKING.include?(normalize(reason))
+    end
+
+    def event_for(reason)
+      normalized = normalize(reason)
+      return nil if internal?(normalized)
+
+      EVENTS.fetch(normalized, "revoked")
+    end
+
+    def revoked_reason_for(reason)
+      normalized = normalize(reason)
+      event_for(normalized) == "revoked" ? normalized : nil
+    end
+  end
+end

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

@@ -7,7 +7,7 @@ module Sessions
   # here. Either way the model gains the events trail and the revocation
   # verbs:
   #
-  #   current_user.sessions.active
+  #   current_user.sessions.live
   #   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
@@ -75,7 +75,7 @@ module Sessions
     def revoke_other_sessions!(current: nil, by: nil, reason: :logout_everywhere)
       current = Sessions.current if current.nil?
 
-      scope = sessions
+      scope = sessions.live
       scope = scope.where.not(id: current.id) if current.respond_to?(:id)
       scope.each { |session| session.revoke!(reason: reason, by: by || self) }
       true
@@ -84,7 +84,7 @@ module Sessions
     # 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) }
+      sessions.live.each { |session| session.revoke!(reason: reason, by: by) }
       true
     end