hubssolib 3.6.1 → 3.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eaea423d2eec6433b30522f6a6d46ab3c1b2868bb860d985cd7472116a17bc95
-  data.tar.gz: 19ae77e97c1e480b6b6cba78eee22523d9964af677ac9a9531582aa68883350b
+  metadata.gz: 68326a50593cfc8b53f1d5ba20e668a0a18316d8e3c6f9a9b245f213522f46f7
+  data.tar.gz: 9267e261fb2af094e0801cea965007c8ee5760d93886a3525640ecca5603f52a
 SHA512:
-  metadata.gz: db1d1f887967b480cb7ef066b1d038ca4540c5aa18fdb307a42fa825f20ca5c9cc7390bccdf9d5b7de247d9ccdfe0b7219f40cc7c7e7cc7b283d2c0a9a458be5
-  data.tar.gz: ccc14fd7c1015d61bc40cde504976d4eafc38368fa2bcb076b3f1e89fe9974b5c2179f55295789c28f25256335f02479161d8966cc774ce8b924bbb41d646119
+  metadata.gz: 1849bcd713bb28f152fae7ca328f0d5f9cbb3b49aef31485019e930ba083af8f79cc3f804d04cf81628aed1bcfdbf669acada4c9cf97b2d190eefe4bc4cf6e9d
+  data.tar.gz: 22c27953133bda55f46e83636298a7b978480bf2d05160a22caf16cecdf4579d39ddff294185dc8510e415fa94a04bd087a6875a983c6cf3df0238e4eac647ee

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 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.
+* User trust mechanism introduced, including HubSsoLib::Core#hubssolib_trusted? convenience accessor for Hub-integrated applications to check on user trust and `HubSsoLib::Core#hubssolib_review_action` convenience alias for `HubSsoLib::Trust.get_trust_object().review_action`.
+* 3.7.1, released only a few minutes after 3.7.0, added the aforementioned `#hubssolib_retrieve_action` method, previously overlooked.
+
 ## 3.6.1, 27-Mar-2025
 
 Some fixes:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    hubssolib (3.6.1)
+    hubssolib (3.7.1)
       base64 (~> 0.2)
       drb (~> 2.2)
 

data/README.md

@@ -376,3 +376,77 @@ In the example of "permissions for arbitrary user" you may well not have ready a
 When a user logs in with a traditional log-in system, there's usually some message shown on the page presented when log-in is successful. This is achieved through the Hub equivalent of the Rails `flash` hash. Replace your preferred mechanism for including contents of the `flash` hash into your views (usually via one or more layout files) with an equivalent which calls Hub's flash handling code, which aggregates both current application and cross-application flash content into one.
 
 Just using `<%= hubssolib_flash_tags -%>` in your layout(s) and/or view(s) will output merged flash data. HTML is generated consisting of `h2` tags with class names derived from the keys used in the flash tag. Each heading tag encapsulates the value for the key and is followed by an empty paragraph tag for spacing reasons on older browsers when more than one key is present, though normally there is only one. Hub itself commonly uses keys `:notice` ("green" / general information - e.g. "you are now logged in"), `:attention` ("orange" / something unusual happened - e.g. "your session timed out so you were logged out") and `:alert` ("red" / something bad happened - e.g. "incorrect password given").
+
+
+
+## Trust mechanism
+
+Hub 3.7.0 and later introduce a trust mechanism. Users have a "trusted" flag that's off by default for any new user. Participating applications can check the current user trust with `hubssolib_trusted?`. For actions where you care about trust - which are typically for creations (e.g. post to a forum, comment on an article) then:
+
+* The relevant controller action proceeds as normal to the point of being ready to save new or updated record(s)
+* If the user is untrusted and the to-be-saved record(s) is/are valid, and so should save OK...
+  - ...instead assemble information about the action and send it to Hub
+  - ...and *do not* save anything but instead exit with an appropriate flash message (e.g. "Thanks, that's gone into our moderation queue and should show up soon - please check back later!").
+
+You send an action to Hub with an alias method `hubssolib_review_action` which has this effective signature:
+
+```ruby
+def hubssolib_review_action(
+  user_email:,
+  action_scheme:,
+  action_url:,
+  action_payload:,
+  action_as_html:,
+  callback_url:
+)
+```
+
+...where you pass:
+
+* The user's email address _as known to Hub_, which is used to look up the user on the Hub side
+* The HTTP method that was being used as a string, case insensitive, e.g. `POST`, for display to admins only
+* The URL in full upon which this current request was made, for display to admins only
+* The payload - usually just `params`, as-is - you'll get send this back again later, so include everything you need to reprocess the action
+* Your choice of **safe** HTML that the Hub application will show as a preview (this may undergo some allow-list sanitisation; Hub does not expect a malicious integrated application to send it bad HTML which attempts skullduggery, but it shouldn't compromise its view layer just because something unsafe got sent accidentally, either!)
+* **A callback URL** described below
+
+If an admin thinks that the submission is bad - e.g. spam - then you won't hear about it again. Otherwise, the admin thinks the delayed action should now be taken for real. To accomplish this, Hub will `POST` back (and always uses `POST`) to your `callback_url` **in JSON** with an object that just has a key, `id`.
+
+You create a controller action for your endpoint which retrieves the action details using code similar to this:
+
+```ruby
+# The request format might be JSON because ".json" ended the path of the
+# URI used to call here, but a missing or incorrect Content-Type header
+# may mean that Rack/Rails doesn't process the body into "params" as
+# expected. The latter would result in a nonsense database lookup which
+# is harmless but wasteful, so don't do it.
+#
+if request.format.json? && request.headers['Content-Type']&.downcase == 'application/json'
+  @details = hubssolib_retrieve_action(id: params[:id])
+  head :unprocessable_entity if @details.nil?
+else
+  head :unsupported_media_type
+end
+```
+
+...then uses the object to work out what to do next. The retrieved object is a Hash, with **Symbol keys at the top level** but **String keys in `action_payload`**:
+
+```
+{
+  timestamp:        untrusted_action.created_at,
+  user_email:       untrusted_action.user_email,
+  user_unique_name: user_unique_name,
+  action_scheme:    untrusted_action.action_scheme,
+  action_url:       untrusted_action.action_url,
+  action_payload:   untrusted_action.action_payload
+}
+```
+
+...so that's:
+
+* The created-at time when you sent the action for review. This is usually only needed if you're dealing with a delayed edit/update action, where you might need to make sure that nobody else had edited the same entity in the mean time.
+* The previously submitted user e-mail is given so you know _who_ it was that is now being trusted, along with the associated Hub "unique display name" (e.g. `Jane Doe (14510)`).
+* 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_.
+
+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.6.1'
+  s.version  = '3.7.1'
   s.author   = 'Andrew Hodgkinson and others'
   s.email    = 'ahodgkin@rowing.org.uk'
   s.homepage = 'http://pond.org.uk/'

data/lib/hub_sso_lib.rb

@@ -23,14 +23,16 @@ module HubSsoLib
   require 'json'
   require 'yaml'
 
-  # DRb connection.
+  # DRb connections.
   #
-  HUB_CONNECTION_URI = ENV['HUB_CONNECTION_URI'] || 'drbunix:' + File.join( ENV['HOME'] || '/', '/.hub_drb')
+  HUB_CONNECTION_URI       = ENV['HUB_CONNECTION_URI'      ] || 'drbunix:' + File.join(ENV['HOME'] || '/', '/.hub_drb')
+  HUB_TRUST_CONNECTION_URI = ENV['HUB_TRUST_CONNECTION_URI'] || 'drbunix:' + File.join(ENV['HOME'] || '/', '/.hub_trust_drb')
 
-  unless HUB_CONNECTION_URI.downcase.start_with?('drbunix:')
+  unless HUB_CONNECTION_URI.downcase.start_with?('drbunix:') && HUB_TRUST_CONNECTION_URI.downcase.start_with?('drbunix:')
     puts
     puts '*' * 80
-    puts "You *must* use a 'drbunix:' scheme for HUB_CONNECTION_URI (#{ HUB_CONNECTION_URI.inspect } is invalid)"
+    puts 'You *must* "drbunix:" for HUB_CONNECTION_URI and HUB_TRUST_CONNECTION_URI.'
+    puts "Either or both of #{HUB_CONNECTION_URI.inspect} and #{HUB_TRUST_CONNECTION_URI.inspect} is invalid)"
     puts '*' * 80
     puts
 
@@ -39,7 +41,7 @@ module HubSsoLib
 
   # External application command registry for on-user-change events.
   #
-  HUB_COMMAND_REGISTRY = ENV['HUB_COMMAND_REGISTRY'] || File.join( ENV['HOME'] || '/', '/.hub_cmd_reg')
+  HUB_COMMAND_REGISTRY = ENV['HUB_COMMAND_REGISTRY'] || File.join(ENV['HOME'] || '/', '/.hub_cmd_reg')
 
   unless Dir.exist?(File.dirname(HUB_COMMAND_REGISTRY))
     puts
@@ -221,7 +223,7 @@ module HubSsoLib
       return @role_array.dup
     end
 
-    # Return a copy of the intenal roles list as a human readable string.
+    # Return a copy of the internal roles list as a human readable string.
     #
     def to_human_s
       human_names = []
@@ -259,6 +261,7 @@ module HubSsoLib
       return false if roles.nil?
 
       # Ensure we've an array of roles, one way or another
+      #
       roles = roles.to_s       if roles.class == Symbol
       roles = roles.split(',') if roles.class == String
 
@@ -360,6 +363,7 @@ module HubSsoLib
   # Author:  A.D.Hodgkinson                                             #
   #                                                                     #
   # History: 21-Oct-2006 (ADH): Created.                                #
+  #          26-Feb-2025 (ADH): Add 'trusted' concept.                  #
   #######################################################################
 
   class User
@@ -388,6 +392,7 @@ module HubSsoLib
     attr_accessor :user_email
     attr_accessor :user_created_at
     attr_accessor :user_password_reset_code_expires_at
+    attr_accessor :user_trusted
 
     def initialize
       @user_salt = nil
@@ -405,6 +410,7 @@ module HubSsoLib
       @user_email = nil
       @user_created_at = nil
       @user_password_reset_code_expires_at = nil
+      @user_trusted = nil
     end
   end # User class
 
@@ -465,7 +471,7 @@ module HubSsoLib
 
   class SessionFactory
     def initialize
-      @hub_be_quiet = ! ENV['HUB_QUIET_SERVER'].nil?
+      @hub_be_quiet = (ENV['HUB_QUIET_SERVER'] == 'yes')
       @hub_sessions = {}
 
       puts "Session factory: Awakening..." unless @hub_be_quiet
@@ -785,7 +791,7 @@ module HubSsoLib
       QUEUE = ::Queue.new
 
       def self.run
-        puts "Server: Starting at #{ HUB_CONNECTION_URI }" if ENV['HUB_QUIET_SERVER'].nil?
+        puts "Server: Starting at #{ HUB_CONNECTION_URI }" if ENV['HUB_QUIET_SERVER'] != 'yes'
 
         @@hub_session_factory = HubSsoLib::SessionFactory.new
 
@@ -815,6 +821,79 @@ module HubSsoLib
     end # Runner class
   end # Server module
 
+  #######################################################################
+  # Class:   Trust                                                      #
+  #                                                                     #
+  # Purpose: Allow other applications to call into the Hub Rails        #
+  #          application to tell it about untrusted user operations.    #
+  #          The application can then store the details, e-mail         #
+  #          moderators and in due course call back to the originating  #
+  #          other application to move the user action forwards.        #
+  #                                                                     #
+  #          The external API is HubSsoLib::Trust::Server, implemented  #
+  #          by the Hub Rails application, not this gem.                #
+  #                                                                     #
+  # Author:  A.D.Hodgkinson                                             #
+  #                                                                     #
+  # History: 19-Mar-2025 (ADH): Created                                 #
+  #######################################################################
+
+  class Trust
+
+    # Return the DRb endpoint URI for the trust server.
+    #
+    def self.get_trust_server_connection_uri
+      HUB_TRUST_CONNECTION_URI
+    end
+
+    # Start the trust server. This should only ever be called by the Hub Rails
+    # application, which implements HubSsoLib::Trust::Server.
+    #
+    def self.launch_server
+      uri             = self.get_trust_server_connection_uri()
+      path            = URI.parse(uri).path
+      already_running = File.exist?(path)
+
+      unless ENV['HUB_QUIET_SERVER'] == 'yes'
+        message = unless already_running
+          "Trust server: Starting at #{ uri }"
+        else
+          "Trust server: Already running at at #{ uri }"
+        end
+
+        puts message
+      end
+
+      unless already_running
+        loop do
+          DRb.start_service(uri, ::HubSsoLib::Trust::Server.new)
+          DRb.thread.join # Keep the thread alive...
+        end               # ...but auto-restart if e.g. DRb.stop_service() is invoked
+      end
+    end
+
+    # Obtain a connection to the trust server. This is called by any client
+    # code that needs to talk to the server which must, at the time called, be
+    # running via startup within the Hub Rails application.
+    #
+    # The returned object is an instance of ::HubSsoLib::Trust::Server, which
+    # is defined inside the Hub Rails application. See there for details.
+    #
+    def self.get_trust_object
+      HUB_MUTEX.synchronize do
+        begin
+          DRb.current_server
+        rescue DRb::DRbServerNotFound
+          DRb.start_service()
+        end
+
+        @@trust_object ||= DRbObject.new_with_uri(self.get_trust_server_connection_uri())
+      end
+
+      return @@trust_object
+    end
+  end
+
   #######################################################################
   # Module:  Core                                                       #
   #          Various authors                                            #
@@ -848,6 +927,8 @@ module HubSsoLib
     #
     def hubssolib_log_out
       self.hubssolib_current_user = nil # (which deals with all related session and cookie consequences)
+      @hubssolib_session = nil
+      cookies.delete(HUB_LOGIN_INDICATOR_COOKIE, domain: :all, path: '/')
     end
 
     # Returns true or false if a user is logged in or not, respectively.
@@ -991,6 +1072,33 @@ module HubSsoLib
       return (puser && !puser.empty? && puser != pnormal)
     end
 
+    # Convenience method that returns +true+ if there's a currently logged-in
+    # Hub user that has been flagged as trusted, else - whether there is no
+    # current user, or they haven't been flagged as trusted - returns +false+.
+    #
+    def hubssolib_trusted?
+      self.hubssolib_current_user&.user_trusted == 'true'
+    end
+
+    # Convenience accessor to HubSsoLib::Trust.get_trust_object().review_action
+    # - see that method for details. Note that the Trust object is implemented
+    # in the Hub application, not here; see:
+    #
+    #   HubSsoLib::Trust::Server::review_action
+    #
+    # ...in "app/hub/lib/hub_sso_lib/trust/server.rb".
+    #
+    def hubssolib_review_action(**args)
+      HubSsoLib::Trust.get_trust_object().review_action(**args)
+    end
+
+    # The equivalent of #hubssolib_review_action, but for retrieving details of
+    # an action when Hub invokes your callback via POST request.
+    #
+    def hubssolib_retrieve_action(**args)
+      HubSsoLib::Trust.get_trust_object().retrieve_action(**args)
+    end
+
     # Public read-only accessor methods for common user activities:
     # return the current user's roles as a Roles object, or nil if
     # there's no user.
@@ -1031,7 +1139,7 @@ module HubSsoLib
     # hubssolib_get_name.
     #
     def hubssolib_unique_name
-      user = hubssolib_current_user
+      user = self.hubssolib_current_user
       user ? "#{user.user_real_name} (#{user.user_id})" : 'Anonymous'
     end
 
@@ -1267,7 +1375,7 @@ module HubSsoLib
         # quietly log out and let action processing carry on.
 
         if (hubssolib_session_expired?)
-          hubssolib_log_out
+          hubssolib_log_out()
           hubssolib_set_flash(:attention, 'Your session timed out, so you are no longer logged in.')
         else
           hubssolib_set_last_used(Time.now.utc)
@@ -1297,7 +1405,6 @@ module HubSsoLib
     def hubssolib_afterwards
       begin
         DRb.current_server
-        DRb.stop_service()
       rescue DRb::DRbServerNotFound
         # Nothing to do; no service is running.
       end
@@ -1441,11 +1548,13 @@ module HubSsoLib
 
           :hubssolib_current_user,
           :hubssolib_unique_name,
+          :hubssolib_account_link,
+          :hubssolib_flash_data,
+
           :hubssolib_logged_in?,
           :hubssolib_authorized?,
           :hubssolib_privileged?,
-          :hubssolib_account_link,
-          :hubssolib_flash_data
+          :hubssolib_trusted?
         )
       end
     end
@@ -1606,8 +1715,9 @@ module HubSsoLib
     # halted (since the overall return value is therefore 'false').
     #
     def hubssolib_access_denied
-      # See hubsso_must_login for the reason behind the following call.
 
+      # See hubsso_must_login for the reason behind the following call.
+      #
       if hubssolib_ensure_https
         hubssolib_set_flash(:alert, 'You do not have permission to carry out that action on this site.')
         redirect_to HUB_PATH_PREFIX + '/'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: hubssolib
 version: !ruby/object:Gem::Version
-  version: 3.6.1
+  version: 3.7.1
 platform: ruby
 authors:
 - Andrew Hodgkinson and others
 bindir: bin
 cert_chain: []
-date: 2025-03-26 00:00:00.000000000 Z
+date: 2025-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: drb