hubssolib 3.7.1 → 3.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68326a50593cfc8b53f1d5ba20e668a0a18316d8e3c6f9a9b245f213522f46f7
-  data.tar.gz: 9267e261fb2af094e0801cea965007c8ee5760d93886a3525640ecca5603f52a
+  metadata.gz: 5fea64186dc1f80987fb5b531c46ac8eb9fff78878520b38e392a91dad8de7a9
+  data.tar.gz: 2ebe2f6599cbd9bf9dbfbaa6ebbbb81e99fe6f4922c5f8c19e250e380222c3c9
 SHA512:
-  metadata.gz: 1849bcd713bb28f152fae7ca328f0d5f9cbb3b49aef31485019e930ba083af8f79cc3f804d04cf81628aed1bcfdbf669acada4c9cf97b2d190eefe4bc4cf6e9d
-  data.tar.gz: 22c27953133bda55f46e83636298a7b978480bf2d05160a22caf16cecdf4579d39ddff294185dc8510e415fa94a04bd087a6875a983c6cf3df0238e4eac647ee
+  metadata.gz: 44b066f10c3615a752b258d85ccf5316358c33af6589c9702ab6b2ae8036f6e7eda9f99ab2a2707dc9acce9e9377ce5e73f28c3533eaec7c7312ac5e6e828fe3
+  data.tar.gz: 1f7ae4d9e29916eb3d14e3c057b61f95192be76954270fd8570dd596a5552495561df2bddd1f16f887ac613bbcd3292fd75228f4bbddf87faeda698c2a866067

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 3.8.1, 09-Apr-2025
+
+* It's been too long since I worked with DRb! Important fix for "live" (undumpable) vs copied objects which could lead to session enumeration problems in clients. Now, sessions enumerated by user ID are copies as is user data returned by HubSsoLib::Core#hubssolib_enumerate_users.
+* Other data is still live, since there's a fair amount of write-back that expects to be updating objects held by the DRb server itself. This will all get replaced by database storage in HubSsoLib 4, so I'm not going to address the weaknesses present wherein a session might be expired or deleted "under the feet" of a client. The Hub gem's own write-based operations are all on a "current" session, so that could only vanish if an admin independently elected to destroy all user sessions via the Hub Rails app front-end. The implication is that the other user was probably up to no good, and I don't really mind if they just seem to be suddenly logged out, or see a 500 error due to a _very_ inconveniently-timed page fetch.
+
+## 3.8.0, 03-Apr-2025
+
+* Adds helper `HubSsoLib::Core#hubssolib_flash_markup` to compliment `HubSsoLib::Core#hubssolib_flash_data` and help make Flash presentation simpler and more consistent across integrated applications.
+* Deprecates core methods `hubssolib_store_location` (which is now a no-op) and `hubssolib_redirect_back_or_default` (which now always redirects to the default location). **These methods will be removed in Hub 4**. Ephemeral return-to location storage has only worked when sessions are _on_, which once upon a time was always - logged in or not - but changed in Hub 3.4.0, to avoid very large numbers of anonymous sessions building up into a very RAM-hungry pools in the DRb server. This has in hindsight amounted to a breaking change, and I should've bumped to Hub 4 per SemVer at that time, but it was overlooked; apologies. At least in general all it really usually means is that, instead of redirecting back to some calling application after login, the user is left in their Hub account view.
+* Hub's UI element added to navigation bars by using `HubSsoLib::Core#hubssolib_account_link` plus permissions and must-log-in checking in the `HubSsoLib::Core#hubssolib_beforehand` before-action callback already dealt with and continue to deal with redirect-to-origin automatically, so often, applications did't need to store a location and then manually redirect to Hub anyway. If you do need this for some reason, though, the new workflow is create a link or redirection to the URL returned by `HubSsoLib::Core#hubssolib_returnable_account_url`. This simply encodes a return-to address in the URL where needed, removing any requirement for cross-application session storage. The method's documentation describes its uses but, for the majority of use cases, you'll probably only want to be presenting a link for the case where a user must log _in_. In that case, call `hubssolib_returnable_account_url(logged_in: false)`.
+
 ## 3.7.0 and 3.7.1, 28-Mar-2025
 
 * Login indicator cookie wasn't updated on session timeout, so when the page loaded for pages that do *not* require authorisation, the warning flash about being timed out would show, but the indicator would still show a "logged in" state until the next page fetch.
@@ -85,7 +96,7 @@ In Hub v1 and v2, login indication was done via an image that was served by the
 
 ```html
 <a class="img" href="<%= ENV['HUB_PATH_PREFIX'] %>/account/login_conditional">
-  <img src="<%= ENV['HUB_PATH_PREFIX'] %>/account/login_indication" alt="Account" height="22" width="90" />
+  <img src="<%= ENV['HUB_PATH_PREFIX'] %>/account/login_indication" alt="Account" height="22" width="90">
 </a>
 ```
 

data/Gemfile.lock

@@ -1,14 +1,91 @@
 PATH
   remote: .
   specs:
-    hubssolib (3.7.1)
+    hubssolib (3.8.1)
       base64 (~> 0.2)
       drb (~> 2.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    actioncable (8.0.2)
+      actionpack (= 8.0.2)
+      activesupport (= 8.0.2)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (8.0.2)
+      actionpack (= 8.0.2)
+      activejob (= 8.0.2)
+      activerecord (= 8.0.2)
+      activestorage (= 8.0.2)
+      activesupport (= 8.0.2)
+      mail (>= 2.8.0)
+    actionmailer (8.0.2)
+      actionpack (= 8.0.2)
+      actionview (= 8.0.2)
+      activejob (= 8.0.2)
+      activesupport (= 8.0.2)
+      mail (>= 2.8.0)
+      rails-dom-testing (~> 2.2)
+    actionpack (8.0.2)
+      actionview (= 8.0.2)
+      activesupport (= 8.0.2)
+      nokogiri (>= 1.8.5)
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actiontext (8.0.2)
+      actionpack (= 8.0.2)
+      activerecord (= 8.0.2)
+      activestorage (= 8.0.2)
+      activesupport (= 8.0.2)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (8.0.2)
+      activesupport (= 8.0.2)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (8.0.2)
+      activesupport (= 8.0.2)
+      globalid (>= 0.3.6)
+    activemodel (8.0.2)
+      activesupport (= 8.0.2)
+    activerecord (8.0.2)
+      activemodel (= 8.0.2)
+      activesupport (= 8.0.2)
+      timeout (>= 0.4.0)
+    activestorage (8.0.2)
+      actionpack (= 8.0.2)
+      activejob (= 8.0.2)
+      activerecord (= 8.0.2)
+      activesupport (= 8.0.2)
+      marcel (~> 1.0)
+    activesupport (8.0.2)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
     base64 (0.2.0)
+    benchmark (0.4.0)
+    bigdecimal (3.1.9)
+    builder (3.3.0)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.0)
+    crass (1.0.6)
     date (3.4.1)
     debug (1.10.0)
       irb (~> 1.10)
@@ -18,20 +95,90 @@ GEM
     doggo (1.4.0)
       rspec-core (~> 3.13)
     drb (2.2.1)
+    erubi (1.13.1)
+    globalid (1.2.1)
+      activesupport (>= 6.1)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
     io-console (0.8.0)
-    irb (1.15.1)
+    irb (1.15.2)
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
+    logger (1.7.0)
+    loofah (2.24.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.8.1)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.0.4)
+    mini_mime (1.1.5)
+    mini_portile2 (2.8.8)
+    minitest (5.25.5)
+    net-imap (0.5.6)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    nio4r (2.7.4)
+    nokogiri (1.18.7)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
     pp (0.6.2)
       prettyprint
     prettyprint (0.2.0)
     psych (5.2.3)
       date
       stringio
-    rdoc (6.13.0)
+    racc (1.8.1)
+    rack (3.1.12)
+    rack-session (2.1.0)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.2.1)
+      rack (>= 3)
+    rails (8.0.2)
+      actioncable (= 8.0.2)
+      actionmailbox (= 8.0.2)
+      actionmailer (= 8.0.2)
+      actionpack (= 8.0.2)
+      actiontext (= 8.0.2)
+      actionview (= 8.0.2)
+      activejob (= 8.0.2)
+      activemodel (= 8.0.2)
+      activerecord (= 8.0.2)
+      activestorage (= 8.0.2)
+      activesupport (= 8.0.2)
+      bundler (>= 1.15.0)
+      railties (= 8.0.2)
+    rails-dom-testing (2.2.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.2)
+      loofah (~> 2.21)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (8.0.2)
+      actionpack (= 8.0.2)
+      activesupport (= 8.0.2)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      zeitwerk (~> 2.6)
+    rake (13.2.1)
+    rdoc (6.13.1)
       psych (>= 4.0.0)
-    reline (0.6.0)
+    reline (0.6.1)
       io-console (~> 0.5)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
@@ -46,6 +193,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.2)
+    securerandom (0.4.1)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
@@ -53,6 +201,17 @@ GEM
     simplecov-html (0.13.1)
     simplecov_json_formatter (0.1.4)
     stringio (3.1.6)
+    thor (1.3.2)
+    timeout (0.4.3)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uri (1.0.3)
+    useragent (0.16.11)
+    websocket-driver (0.7.7)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.7.2)
 
 PLATFORMS
   ruby
@@ -61,6 +220,7 @@ DEPENDENCIES
   debug (~> 1.1)
   doggo (~> 1.4)
   hubssolib!
+  rails (~> 8.0)
   rspec (~> 3.13)
   rspec-mocks (~> 3.13)
   simplecov (~> 0.22)

data/README.md

@@ -449,4 +449,25 @@ end
 * Your previously submitted action scheme and URL are also given in case you need them because you've decided to implement one callback handler for different kinds of untrusted action.
 * The `action_payload` is where all your important data, meaningful only to you, resides and this must contain everything else, other than the above parameters, required to complete the action previously sent for review, _while making sure things are attributed to the correct user_.
 
+Use `head ...` to indicate non-200 responses. If you don't want the originating user to get notified of a successful run, then on-success, also reply with `head :ok` or `head 200` (according to style preference). If you want to ask Hub to notify the user, then on-success instead do this:
+
+```ruby
+render json: { mail_item_url: ..., mail_subject: ... }, status: :ok
+```
+
+The payload items shown above are both mandatory:
+
+* `mail_item_url` is the full URL of the entity that you just successfully edited, updated, or some other sensible URL to take the user (this will be included verbatim in the e-mail)
+* `mail_subject` is a subject line of your choosing - for example, `"Your new forum post is now visible"`. Hub might add a prefix such as `[ORGNAME] ...`
+
+If either item is missing or blank, or if for any reason Hub finds itself unable to associated the action with a user record on Hub's side, then no e-mail message will be sent.
+
+**IMPORTANT:** The Hub application's database migration at the time you updated to 3.7.0 will have set existing users to trusted for historic data, but new users are untrusted. If you introduce trust integration to your site's other apps after this, you might want to enter the console to update any new users added since likewise; inside `app/hub`, issue:
+
+```
+$ bundle exec rails c
+> User.update_all(trusted: true)
+> exit
+```
+
 The trust mechanism involves a fair amount of effort on the integrating app's side but it can be very useful if you have a site where, despite your best efforts, sometimes spam/bot accounts manage to get inside and try to flood the system with spam. It's just one of many different potential protection and mitigation mechanisms that your site might choose to employ.

data/hubssolib.gemspec

@@ -4,7 +4,7 @@ spec = Gem::Specification.new do |s|
   s.platform = Gem::Platform::RUBY
   s.name     = 'hubssolib'
 
-  s.version  = '3.7.1'
+  s.version  = '3.8.1'
   s.author   = 'Andrew Hodgkinson and others'
   s.email    = 'ahodgkin@rowing.org.uk'
   s.homepage = 'http://pond.org.uk/'
@@ -28,6 +28,7 @@ spec = Gem::Specification.new do |s|
   s.add_dependency 'base64', '~> 0.2'
 
   s.add_development_dependency 'debug',       '~> 1.1'
+  s.add_development_dependency 'rails',       '~> 8.0'
   s.add_development_dependency 'simplecov',   '~> 0.22'
   s.add_development_dependency 'doggo',       '~> 1.4'
   s.add_development_dependency 'rspec',       '~> 3.13'

data/lib/hub_sso_lib.rb

@@ -69,7 +69,7 @@ module HubSsoLib
 
   # Location of Hub application root.
   #
-  HUB_PATH_PREFIX = ENV['HUB_PATH_PREFIX'] || ''
+  HUB_PATH_PREFIX = (ENV['HUB_PATH_PREFIX'] || '').sub(/(\/)+$/, '')
 
   # Time limit, *in seconds*, for the account inactivity timeout. If a user
   # performs no Hub actions during this time they will be automatically logged
@@ -366,17 +366,16 @@ module HubSsoLib
   #          26-Feb-2025 (ADH): Add 'trusted' concept.                  #
   #######################################################################
 
+  # This *must not* be 'undumped', since it gets passed from clients back to
+  # the persistent DRb server process. A client thread may disappear and be
+  # recreated by the web server at any time; if the user object is undumpable,
+  # then the DRb server has to *call back to the client* (in DRb, clients are
+  # also servers...!) to find out about the object. Trouble is, if the client
+  # thread has been recreated, the server will be trying to access to stale
+  # objects that only exist if the garbage collector hasn't got to them yet.
+  #
   class User
 
-    # This *must not* be 'undumped', since it gets passed from clients
-    # back to the persistent DRb server process. A client thread may
-    # disappear and be recreated by the web server at any time; if the
-    # user object is undumpable, then the DRb server has to *call back
-    # to the client* (in DRb, clients are also servers...!) to find out
-    # about the object. Trouble is, if the client thread has been
-    # recreated, the server will be trying to access to stale objects
-    # that only exist if the garbage collector hasn't got to them yet.
-
     attr_accessor :user_salt
     attr_accessor :user_roles
     attr_accessor :user_updated_at
@@ -394,29 +393,11 @@ module HubSsoLib
     attr_accessor :user_password_reset_code_expires_at
     attr_accessor :user_trusted
 
-    def initialize
-      @user_salt = nil
-      @user_roles = nil
-      @user_updated_at = nil
-      @user_activated_at = nil
-      @user_real_name = nil
-      @user_crypted_password = nil
-      @user_remember_token_expires_at = nil
-      @user_activation_code = nil
-      @user_member_id = nil
-      @user_id = nil
-      @user_password_reset_code = nil
-      @user_remember_token = nil
-      @user_email = nil
-      @user_created_at = nil
-      @user_password_reset_code_expires_at = nil
-      @user_trusted = nil
-    end
   end # User class
 
   #######################################################################
-  # Class:   Session                                                    #
-  #          (C) Hipposoft 2006                                         #
+  # Class:   Session family                                             #
+  #          (C) Hipposoft 2006-2025                                    #
   #                                                                     #
   # Purpose: Session support object, used to store session metadata in  #
   #          an insecure cross-application cookie.                      #
@@ -424,37 +405,67 @@ module HubSsoLib
   # Author:  A.D.Hodgkinson                                             #
   #                                                                     #
   # History: 22-Oct-2006 (ADH): Created.                                #
+  #          09-Apr-2025 (ADH): Dumpable/undumpable variants created.   #
   #######################################################################
 
-  class Session
-
-    # Unlike a User, this *is* undumpable since it only gets passed from
-    # server to client. The server's always here to service requests
-    # from the client and used sessions are never garbage collected
-    # since the DRb server's front object, a SessionFactory, keeps them
-    # in a hash held within an instance variable.
-
-    include DRb::DRbUndumped
-
-    attr_accessor :session_last_used
-    attr_accessor :session_return_to
-    attr_accessor :session_flash
-    attr_accessor :session_user
-    attr_accessor :session_rotated_key
-
-    def initialize
-      @session_last_used   = Time.now.utc
-      @session_return_to   = nil
-      @session_flash       = {}
-      @session_user        = HubSsoLib::User.new
-      @session_rotated_key = nil
+  # A dumpable base class that can be used for undumpable proxies, where a
+  # change made in an object passed to a client is reflected on the server
+  # where the object actually lives; or for dumpable clones of sessions sent
+  # as read-only copies to clients which won't disppear due to server side
+  # deletion from key rotation, expiry or admin-driven deletion.
+  #
+  class SessionBase
+
+    ATTRIBUTES = %i{
+      session_last_used
+      session_flash
+      session_user
+      session_rotated_key
+    }
+
+    ATTRIBUTES.each { | attr | attr_accessor(attr) }
+    attr_reader :session_return_to # DEPRECATED
+
+    def initialize(copying_session: nil)
+      if copying_session.nil?
+        self.session_last_used   = Time.now.utc
+        self.session_flash       = {}
+        self.session_user        = HubSsoLib::User.new
+        self.session_rotated_key = nil
+      else
+        ATTRIBUTES.each do | attr |
+          self.send("#{attr}=", copying_session.send(attr))
+        end
+      end
 
     rescue => e
       Sentry.capture_exception(e) if defined?(Sentry) && Sentry.respond_to?(:capture_exception)
       raise
     end
+
+  end # SessionBase class
+
+  # Unlike a User, this *is* undumpable since it only gets passed from server
+  # to client. The server's always here to service requests from the client and
+  # used sessions are never garbage collected since the DRb server's front
+  # object, a SessionFactory, keeps them in a hash held within an instance
+  # variable.
+  #
+  # A recognised weakness here is that a session might disappear from under the
+  # feet of an accessing application, due to key rotation or explicit deletion.
+  #
+  class Session < SessionBase
+    include DRb::DRbUndumped
   end # Session class
 
+  # No special conditions - this is just a dumpable session. You should usually
+  # create it based on an undumpable, 'live' session thus:
+  #
+  #   SessionCopy.new(copying_session: undumpable_session)
+  #
+  class SessionCopy < SessionBase
+  end # SessionCopy class
+
   #######################################################################
   # Class:   SessionFactory                                             #
   #          (C) Hipposoft 2006                                         #
@@ -613,7 +624,9 @@ module HubSsoLib
       keys  = if count > HUB_SESSION_ENUMERATION_KEY_MAX
         nil
       else
-        @hub_sessions.keys # (Hash#keys returns a new array)
+        HUB_MUTEX.synchronize do
+          @hub_sessions.keys # (Hash#keys returns a new array)
+        end
       end
 
       return { count: count, keys: keys }
@@ -627,8 +640,18 @@ module HubSsoLib
     # given session key. No key rotation occurs. Returns +nil+ if no entry is
     # found for that key.
     #
+    # This returns a *LIVE OBJECT* owned by the DRb server. Writes made to this
+    # object will affect the live session state. However, the session might be
+    # invalidated at any time by actions such as key rotation, expiration or
+    # explicit user deletion. Attempts to read or write properties would then
+    # lead to exceptions such as:
+    #
+    #   "424" is not id value (RangeError)
+    #
+    # ...where 424 is the internal object ID of meaning only to the DRb system.
+    #
     def retrieve_session_by_key(key)
-      @hub_sessions[key]
+      HUB_MUTEX.synchronize { @hub_sessions[key] }
     end
 
     # WARNING: Comparatively slow.
@@ -638,15 +661,24 @@ module HubSsoLib
     # values yielding HubSsoLib::Session instances as values is returned.
     #
     # The array is ordered by least-recently-active first to most-recent last.
+    # Returned data is a copy of internal session information and should be
+    # considered read-only; changes made will have no effect outside your own
+    # application.
     #
     # IN THE CURRENT IMPLEMENTATION THIS JUST SEQUENTIALLY SCANS ALL ACTIVE
     # SESSIONS IN THE HASH and must therefore lock on mutex for the duration.
     #
     def retrieve_sessions_by_user_id(user_id)
       HUB_MUTEX.synchronize do
-        @hub_sessions.select do | key, session |
-          session&.session_user&.user_id == user_id
+        collection = {}
+
+        @hub_sessions.each do | key, session |
+          if session&.session_user&.user_id == user_id
+            collection[key] = SessionCopy.new(copying_session: session)
+          end
         end
+
+        collection
       end
     end
 
@@ -655,10 +687,16 @@ module HubSsoLib
     # session data. Does nothing if the key is not found.
     #
     def destroy_session_by_key(key)
+      unless @hub_be_quiet
+        puts "Session factory: Deleting session with key #{key}"
+      end
+
       HUB_MUTEX.synchronize do
         @hub_sessions.delete(key)
       end
 
+      return nil
+
     rescue => e
       Sentry.capture_exception(e) if defined?(Sentry) && Sentry.respond_to?(:capture_exception)
       raise
@@ -674,12 +712,44 @@ module HubSsoLib
     # SESSIONS IN THE HASH and must therefore lock on mutex for the duration.
     #
     def destroy_sessions_by_user_id(user_id)
+      unless @hub_be_quiet
+        puts "Session factory: Deleting all session records for user ID #{user_id.inspect}"
+      end
+
       HUB_MUTEX.synchronize do
         @hub_sessions.reject! do | key, session |
           session&.session_user&.user_id == user_id
         end
       end
 
+      return nil
+
+    rescue => e
+      Sentry.capture_exception(e) if defined?(Sentry) && Sentry.respond_to?(:capture_exception)
+      raise
+    end
+
+    # WARNING: Comparatively slow.
+    #
+    # Call only if you MUST update details of a session user inside all Hub
+    # sessions. Pass the user ID and HubSsoLib::User details that are to be
+    # stored for all sessions owned by that user ID.
+    #
+    def update_sessions_by_user_id(user_id, user)
+      unless @hub_be_quiet
+        puts "Session factory: Updating all session records for user ID #{user_id.inspect}"
+      end
+
+      HUB_MUTEX.synchronize do
+        @hub_sessions.each do | key, session |
+          if session&.session_user&.user_id == user_id
+            session.session_user = user
+          end
+        end
+      end
+
+      return nil
+
     rescue => e
       Sentry.capture_exception(e) if defined?(Sentry) && Sentry.respond_to?(:capture_exception)
       raise
@@ -722,6 +792,8 @@ module HubSsoLib
         puts "Session factory: ...Destroyed #{destroyed} session(s)"
       end
 
+      return nil
+
     rescue => e
       Sentry.capture_exception(e) if defined?(Sentry) && Sentry.respond_to?(:capture_exception)
       raise
@@ -964,34 +1036,97 @@ module HubSsoLib
       end
     end
 
-    # Returns markup for a link that leads to Hub's conditional login endpoint,
-    # inline-styled as a red "Log in" or green "Account" button. This can be
-    # used in page templates to avoid needing any additional images or other
-    # such resources and using pure HTML + CSS for the login indication.
+    # Return a URL that leads to a Hub "log in" page if the user is not logged
+    # in currently, else an "account" page for logged-in users.
+    #
+    # +universal+:: Use +true+ if concerned that a "Back" browser button action
+    #               might cause a page to appear that's got a cached link which
+    #               may no longer reflect the current state. This jumps to Hub
+    #               and redirects to the "log in" or "account" destinations
+    #               depending on current state. If using this, bear in mind
+    #               that the link text must be ambiguous, because the eventual
+    #               destination isn't known.
+    #
+    #               It's often better to just use #hubssolib_account_link to
+    #               create markup for this in a navigation area.
+    #
+    #               The default is +false+, which means that a bespoke link
+    #               for the exact current instantaneous log in state is
+    #               generated; the +logged_in+ parameter applies (see below).
+    #
+    # +logged_in+:: If +universal+ is +false+, then this parameter defaults to
+    #               the current user logged-in state, but can be overridden
+    #               with +true+ (act as if someone is logged in) or +false+
+    #               (act as if someone is not logged in).
+    #
+    # +return_to+:: Overrides the use of <tt>request.original_url</tt> to give
+    #               an alternative return-after-logging-in URL. Will be of no
+    #               use for users already logged in. This is rarely used, but
+    #               might be helpful if you (say) want them to return to the
+    #               current page, but with a specific fragment added ("#foo").
+    #               Specify as a String, Symbol or URI, at your preference.
+    #
+    # Note that the universal links, or a not-logged-in state link will include
+    # a query string which takes the value of <tt>request.original_url</tt> or,
+    # if not defined, tries <tt>request.referrer</tt> (else is absent). This is
+    # a URL used for the redirection after successful login. The logged-in
+    # state link does not require this addition so omits it for brevity.
+    #
+    def hubssolib_returnable_account_url(
+      universal: false,
+      logged_in: self.hubssolib_logged_in?,
+      return_to: nil
+    )
+      account_url = if universal
+        "#{HUB_PATH_PREFIX}/account/login_conditional"
+      else
+        "#{HUB_PATH_PREFIX}/#{'account/login' unless logged_in}"
+      end
+
+      # Attach a return-to URL always for the universal case which needs to
+      # work regardless of login state; else we only need it when logged out,
+      # so that we can return to the originating location after logging in.
+      # There's no functional difference - just a simpler URL that omits what
+      # would otherwise be an unused query string parameter.
+      #
+      if universal or not logged_in
+        if return_to.nil?
+          request_obj = self.try(:request)
+          return_to   = request_obj.try(:original_url) || request_obj.try(:referrer)
+        end
+
+        if return_to.present?
+          account_url << "?return_to_url=#{CGI.escape(return_to.to_s)}"
+        end
+      end
+
+      return account_url
+    end
+
+    # Returns markup for a link that leads to Hub's login or logout link, using
+    # pure HTML + CSS for styling. A universal "conditional login" link is used
+    # since page data may be old due to e.g. a "back" button being used, after
+    # the user either logged in or out elsewhere. This possibility is also why
+    # JavaScript is used, updating the button styling the correct login state
+    # if needed. This requires the "pageshow" event to be supported. NOSCRIPT
+    # browsers use the a no-cache image-based fallback, which is much less
+    # efficient, but works.
     #
-    # JavaScript is used so that e.g. "back" button fully-cached displays by a
-    # browser will get updated with the correct login state, where needed (so
-    # long as the 'pageshow' event is supported). NOSCRIPT browsers use the old
-    # no-cache image fallback, which is much less efficient, but works.
+    # Although the JavaScript-powered option could use the non-conditional link
+    # for log in/out and swap those, it's simpler just to use generate the same
+    # link for all states - script-capable or otherwise, logged in or out,
     #
     def hubssolib_account_link
-      logged_in        = self.hubssolib_logged_in?()
-      ui_href          = "#{HUB_PATH_PREFIX}/account/login_conditional"
+      logged_in_url    = self.hubssolib_returnable_account_url(universal: false, logged_in: true)
+      logged_out_url   = self.hubssolib_returnable_account_url(universal: false, logged_in: false)
+      universal_url    = self.hubssolib_returnable_account_url(universal: true)
+
       noscript_img_src = "#{HUB_PATH_PREFIX}/account/login_indication.png"
       noscript_img_tag = helpers.image_tag(noscript_img_src, size: '90x22', border: '0', alt: 'Log in or out')
 
-      if self.respond_to?(:request)
-        return_to_url = self.request.try(:original_url)
-
-        if return_to_url.present?
-          return_query = URI.encode_www_form({ return_to_url: return_to_url.to_s })
-          ui_href << "?#{return_query}"
-        end
-      end
-
-      logged_in_link   = helpers.link_to('Account',        ui_href, id: 'hubssolib_logged_in_link')
-      logged_out_link  = helpers.link_to('Log in',         ui_href, id: 'hubssolib_logged_out_link')
-      noscript_link    = helpers.link_to(noscript_img_tag, ui_href, id: 'hubssolib_login_noscript')
+      logged_in_link   = helpers.link_to('Account',        logged_in_url,  id: 'hubssolib_logged_in_link')
+      logged_out_link  = helpers.link_to('Log in',         logged_out_url, id: 'hubssolib_logged_out_link')
+      noscript_link    = helpers.link_to(noscript_img_tag, universal_url,  id: 'hubssolib_login_noscript')
 
       # Yes, it's ugly, but yes, it works and it's a lot better for the server
       # to avoid the repeated image fetches. It probably works out as overall
@@ -1172,8 +1307,8 @@ module HubSsoLib
 
       unless hub_session_info[:keys].nil? # (keyset too large, enumeration prohibited)
         hub_session_info[:keys].each do | key |
-          session = hubssolib_factory().retrieve_session_by_key(key)
-          hub_users << session.session_user unless session&.session_user&.user_id.nil?
+          session_user = hubssolib_factory().retrieve_session_by_key(key)&.session_user
+          hub_users << session_user unless session_user&.user_id.nil?
         end
       end
 
@@ -1217,6 +1352,18 @@ module HubSsoLib
       hubssolib_factory().destroy_sessions_by_user_id(hub_user_id) unless hub_user_id.nil?
     end
 
+    # WARNING: Comparatively slow.
+    #
+    # If a Hub user record changes, make sure their session records reflect
+    # the updated demographics according to the HubSsoLib::User provided.
+    #
+    # For information about performance limitations, see
+    # HubSsoLib::SessionFactory#destroy_sessions_by_user_id.
+    #
+    def hubssolib_update_user_sessions(hub_user_id, hub_user)
+      hubssolib_factory().update_sessions_by_user_id(hub_user_id, hub_user) unless hub_user_id.nil?
+    end
+
     # If an application needs to know about changes of a user e-mail address
     # or display name (e.g. because of sync to a local relational store of
     # users related to other application-managed resources, with therefore a
@@ -1327,7 +1474,6 @@ module HubSsoLib
         cookies.delete(HUB_LOGIN_INDICATOR_COOKIE, domain: :all, path: '/')
 
         if login_is_required
-          hubssolib_store_location()
           return hubssolib_must_login()
         else
           return true
@@ -1354,14 +1500,10 @@ module HubSsoLib
         # if OK, else indicate that access is denied.
 
         if (hubssolib_session_expired?)
-          hubssolib_store_location()
           hubssolib_log_out()
           hubssolib_set_flash(:attention, 'Sorry, your session timed out; you need to log in again to continue.')
 
-          # We mean this: redirect_to :controller => 'account', :action => 'login'
-          # ...except for the Hub, rather than the current application (whatever
-          # it may be).
-          redirect_to HUB_PATH_PREFIX + '/account/login'
+          redirect_to hubssolib_returnable_account_url(logged_in: false)
         else
           hubssolib_set_last_used(Time.now.utc)
           return hubssolib_authorized? ? true : hubssolib_access_denied()
@@ -1410,28 +1552,17 @@ module HubSsoLib
       end
     end
 
-    # Store the URI of the current request in the session, or store the
-    # optional supplied specific URI.
-    #
-    # We can return to this location by calling #redirect_back_or_default.
+    # Deprecated. Don't use this. See #hubssolib_returnable_account_url.
     #
     def hubssolib_store_location(uri_str = request.url)
-      if (uri_str && !uri_str.empty?)
-        uri_str = hubssolib_promote_uri_to_ssl(uri_str, request.host) unless request.ssl?
-        hubssolib_set_return_to(uri_str)
-      else
-        hubssolib_set_return_to(nil)
-      end
+      Rails.logger.warn('hubssolib_store_location: DEPRECATED (no-op)') rescue nil
     end
 
-    # Redirect to the URI stored by the most recent store_location call or
-    # to the passed default.
+    # Deprecated. Don't use this. See #hubssolib_returnable_account_url.
     #
     def hubssolib_redirect_back_or_default(default)
-      url = hubssolib_get_return_to()
-      hubssolib_set_return_to(nil)
-
-      redirect_to(url || default)
+      Rails.logger.warn('hubssolib_redirect_back_or_default: DEPRECATED (always redirects to default)') rescue nil
+      redirect_to(default)
     end
 
     # Take a URI and pass an optional host parameter. Decomposes the URI,
@@ -1440,9 +1571,10 @@ module HubSsoLib
     # as a flat string.
     #
     def hubssolib_promote_uri_to_ssl(uri_str, host = nil)
-      uri = URI.parse(uri_str)
-      uri.host = host if host
+      uri        = URI.parse(uri_str)
+      uri.host   = host if host
       uri.scheme = hub_bypass_ssl? ? 'http' : 'https'
+
       return uri.to_s
     end
 
@@ -1454,8 +1586,7 @@ module HubSsoLib
       if request.ssl? || hub_bypass_ssl?
         return true
       else
-        # This isn't reliable: redirect_to({ :protocol => 'https://' })
-        redirect_to( hubssolib_promote_uri_to_ssl( request.request_uri, request.host ) )
+        redirect_to(hubssolib_promote_uri_to_ssl(request.original_url))
         return false
       end
     end
@@ -1465,21 +1596,32 @@ module HubSsoLib
     # dropped. However, we also want this to work without being logged in, so
     # in that case it uses the normal flash as a backup when *writing*.
     #
+    # This method returns the Hub flash if logged in, else +nil+.
+    #
     def hubssolib_get_flash
       session = self.hubssolib_get_session()
-      session&.session_flash || {}
+      session&.session_flash
     end
 
+    # Set Flash information under the given symbol with the given text message,
+    # using the Hub cross-application flash store if logged in, else the
+    # this-application local session flash store otherwise.
+    #
     def hubssolib_set_flash(symbol, message)
       session = self.hubssolib_get_session()
-      f       = hubssolib_get_flash() unless session.nil?
-      f       = self.flash if f.nil? && self.respond_to?(:flash)
+
+      f   = hubssolib_get_flash()
+      f ||= self.flash if self.respond_to?(:flash)
+      f ||= {}
 
       f[symbol] = message
 
       session.session_flash = f unless session.nil?
     end
 
+    # Clears the *hub* flash for logged-in users, but not the local application
+    # session flash.
+    #
     def hubssolib_clear_flash
       session = self.hubssolib_get_session()
       session.session_flash = {} unless session.nil?
@@ -1495,6 +1637,10 @@ module HubSsoLib
     # values. This allows both the Hub and standard flashes to have values
     # inside them under the same key. All keys are strings.
     #
+    # You may well prefer to use #hubssolib_flash_markup to obtain something
+    # that can be written straight into a view, unless it doesn't meet your
+    # markup requirements.
+    #
     def hubssolib_flash_data
 
       # These known key values are used to guarantee an order in the output
@@ -1510,14 +1656,14 @@ module HubSsoLib
       # Get an array of keys for the Hub flash with the ordered key items
       # first and store data from that flash; same again for standard.
 
-      hash = hubssolib_get_flash()
+      hash = hubssolib_get_flash() || {}
       keys = ordered_keys | hash.keys
 
       keys.each do | key |
         compiled_data['hub'][key] = hash[key] if hash.key?(key)
       end
 
-      if defined?( flash )
+      if self.respond_to?( :flash )
         hash = flash.to_h()
         keys = ordered_keys | hash.keys
 
@@ -1527,11 +1673,60 @@ module HubSsoLib
       end
 
       hubssolib_clear_flash()
-      flash.discard()
+      flash.clear()
 
       return compiled_data
     end
 
+    # A companion to #hubssolib_flash_data which returns standardised Flash
+    # markup for your view. THIS MUST ONLY BE USED IN A VIEW / HELPER, or at
+    # least somewhere that ActionView::Helpers::TagHelper#tag is available.
+    #
+    # * An outer DIV with class "flash" wraps the content.
+    #
+    # * Within that, +H2+ tags wrap each message in the flash data. These
+    #   tags also have class "flash", along with an additional tag which is
+    #   equal to the key under which the message was found - so if adding a
+    #   flash message under, say, <tt>:alert</tt>, the rendered result would
+    #   be <tt>&lt;h2 class="flash alert"&gt;...&lt;/h2&gt;</tt>.
+    #
+    # * As a special case, a key with the suffix <tt>_html_safe</tt> is taken
+    #   to contain HTML-safe strings and potential markup, so you could do
+    #   things like add emphasis, other classes or styles to the data written
+    #   inside the +H2+ tag. Be very careful to make sure any non-markup data
+    #   is properly escaped first. The key-related class in the arising +H2+
+    #   tag _excludes_ the suffix, so e.g. <tt>:notice_html_safe</tt> will
+    #   lead to class +notice+.
+    #
+    # Hub session-sourced and Rails local app session-sourced flash data is
+    # treated the same, with Hub-sourced data listed first. The other is
+    # otherwise undefined (it's rare for there to be more than one thing in
+    # the flash at any given time, though).
+    #
+    def hubssolib_flash_markup
+      data = hubssolib_flash_data()
+      proc = Proc.new do | key, value |
+        key = key.to_s
+
+        if key.end_with?( '_html_safe' )
+          value = value.html_safe()
+          key   = key.chomp( '_html_safe' )
+        end
+
+        helpers.tag.h2(value, class: "flash #{ key }")
+      end
+
+      return helpers.tag.div(class: 'flash') do
+        data['hub'].each do | key, value |
+          helpers.concat(proc.call(key, value))
+        end
+
+        data['standard'].each do | key, value |
+          helpers.concat(proc.call(key, value))
+        end
+      end
+    end
+
     # Retrieve the message of an exception stored as an object in the given
     # string.
     #
@@ -1548,8 +1743,10 @@ module HubSsoLib
 
           :hubssolib_current_user,
           :hubssolib_unique_name,
+          :hubssolib_returnable_account_url,
           :hubssolib_account_link,
           :hubssolib_flash_data,
+          :hubssolib_flash_markup,
 
           :hubssolib_logged_in?,
           :hubssolib_authorized?,
@@ -1703,7 +1900,7 @@ module HubSsoLib
       #
       if hubssolib_ensure_https
         hubssolib_set_flash(:alert, 'You must log in before you can continue.')
-        redirect_to HUB_PATH_PREFIX + '/account/login'
+        redirect_to hubssolib_returnable_account_url(logged_in: false)
       end
 
       return false
@@ -1795,16 +1992,6 @@ module HubSsoLib
       session = self.hubssolib_get_session()
       session.session_last_used = time unless session.nil?
     end
-
-    def hubssolib_get_return_to
-      self.hubssolib_get_session()&.session_return_to
-    end
-
-    def hubssolib_set_return_to(uri)
-      session = self.hubssolib_get_session()
-      session.session_return_to = uri unless session.nil?
-    end
-
   end # Core module
 end # HubSsoLib module
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: hubssolib
 version: !ruby/object:Gem::Version
-  version: 3.7.1
+  version: 3.8.1
 platform: ruby
 authors:
 - Andrew Hodgkinson and others
 bindir: bin
 cert_chain: []
-date: 2025-03-28 00:00:00.000000000 Z
+date: 2025-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: drb
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -124,6 +138,7 @@ files:
 - Gemfile
 - Gemfile.lock
 - README.md
+- hubssolib-3.7.0.gem
 - hubssolib.gemspec
 - lib/hub_sso_lib.rb
 homepage: http://pond.org.uk/