hubssolib 3.7.0 → 3.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13d41f0609a0ebf34e61267f91db31652699915b531010ddbda76ecc63110239
-  data.tar.gz: aea0e7149740e0d25714bc1a0b9a2b5333910058497a0ec24906a65364475218
+  metadata.gz: 68326a50593cfc8b53f1d5ba20e668a0a18316d8e3c6f9a9b245f213522f46f7
+  data.tar.gz: 9267e261fb2af094e0801cea965007c8ee5760d93886a3525640ecca5603f52a
 SHA512:
-  metadata.gz: 30c7c7f431d456cb286bd439be4e7ec3d80abde85d856e6f8914daf3d46e8f5ca0d36ac380a7240ddecde149f225fd8c80a5738070d9ed9404e87e77823e1e85
-  data.tar.gz: c48fefd6183cbfe3d5f8c9bd9e5f503d31f24524ff000121f73b0f2651d7d081e72fa5f4870d0ae6ec6d7599d900eea8b4b4b283380d36a3f2184e2da46a69dc
+  metadata.gz: 1849bcd713bb28f152fae7ca328f0d5f9cbb3b49aef31485019e930ba083af8f79cc3f804d04cf81628aed1bcfdbf669acada4c9cf97b2d190eefe4bc4cf6e9d
+  data.tar.gz: 22c27953133bda55f46e83636298a7b978480bf2d05160a22caf16cecdf4579d39ddff294185dc8510e415fa94a04bd087a6875a983c6cf3df0238e4eac647ee

data/CHANGELOG.md

@@ -1,7 +1,8 @@
-## 3.7.0, 28-Mar-2025
+## 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
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    hubssolib (3.7.0)
+    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.7.0'
+  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

@@ -1092,6 +1092,13 @@ module HubSsoLib
       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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hubssolib
 version: !ruby/object:Gem::Version
-  version: 3.7.0
+  version: 3.7.1
 platform: ruby
 authors:
 - Andrew Hodgkinson and others