clowk 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1593747e0040a0056565a40b2bf1699d8242af1d253751ce3ea5c86949ff1f7a
-  data.tar.gz: 33147a1e6f88c7970d52bf33403566c09309315c53b8e080416aaece4f1ecc2a
+  metadata.gz: 66d644459bae62c4a73b869fadc50402bfbe6fb060c0c6fc5ee521361a852be7
+  data.tar.gz: 1e81f740b072795cb9a84c2013f406ee5ea34a9bf5c1c92797cea9efd1c22d4e
 SHA512:
-  metadata.gz: 0cf89e539def821193dd451c8902e581423f103acd8881ce67d7eadb9cfd9e2e69302a265769679eb5a906593a89253f4781cf625546ee3bbd3d8d012d15584a
-  data.tar.gz: f4993722c5349f80a7a10f39cff94d3b76b4909b700272f23458bca7d227fa263258c78b01cf511e2cb5d30640dae84a991fd686939fc4fbfcd2cee7b2e5e757
+  metadata.gz: 824a01a8708d3b4f1805c83acc20d2161c9e72f3be7c47ae9e1c2d9d80bbff624292d20e65cf03b53ca5384874caef3f1d038482cd4d4593cc688537b63a2d31
+  data.tar.gz: d4703e671a924025452c08686d6134f85563108d0edeb18bb049f9f9e4d119228d404ba3eccddae21840b2b63267c416aebac1b4a7f925689a9e37cd642cbf95

data/README.md

@@ -227,6 +227,48 @@ What changes in that mode:
   session, keyed by a digest of the token. Without it, `enforce_active_session`
   would cost a round trip to Clowk on every authenticated request.
 
+### Keeping a session honest
+
+A valid token proves who signed in, not that the session still stands —
+revocation lives server-side. `config.enforce_active_session = true` checks it,
+and `config.session_status_ttl` decides how often that costs a round trip.
+
+Some actions cannot take a cached answer. Rotating a secret, deleting an
+account, removing a member: a status from fourteen minutes ago is a hole. Name
+those actions and they get a live one:
+
+```ruby
+class ApiKeysController < ApplicationController
+  clowk_require_fresh_session only: [:create, :update, :destroy]
+end
+```
+
+It takes the same options as `before_action`. Everything not named keeps the
+cached check, so an app pays for the round trip on the few actions it cannot
+undo and nowhere else. `clowk_enforce_fresh_session!` is the same thing as a
+method, and `clowk_session_active?(force: true)` returns the answer instead of
+enforcing it.
+
+Two settings decide what happens when Clowk itself cannot be reached:
+
+```ruby
+config.fail_open_on_broker_error = true   # default
+config.max_session_age = 12.hours         # default nil
+```
+
+Failing open leaves the session standing and checks again on the next request —
+a blip on the way to a single droplet must not sign everyone out. Only network
+failures count; anything else still raises, because a bug must not read as "the
+session is probably fine".
+
+`max_session_age` is the other half of that, and failing open is not safe
+without it: a local ceiling the broker plays no part in, so a permanently
+unreachable Clowk cannot keep a session alive forever. Past it the session ends
+with no round trip at all.
+
+Both ends — the broker said inactive, the ceiling passed — go through
+`config.on_session_expired` when you set one.
+
 ### Token verification
 
 Tokens signed with `RS256` are verified against Clowk's public key set, fetched

data/lib/clowk/authenticable.rb

@@ -7,6 +7,11 @@ module Clowk
   module Authenticable
     extend ActiveSupport::Concern
 
+    # What a liveness check can raise once Clowk::Http's retries are spent, plus
+    # connection-refused, which retries never cover. Anything else is a bug and
+    # must not be swallowed into "the session is probably fine".
+    BROKER_UNAVAILABLE = [SystemCallError, Timeout::Error, IOError, SocketError, EOFError].freeze
+
     def self.install_dynamic_methods(base)
       scope = Clowk.config.prefix_by.to_s
       current_method = :"current_#{scope}"
@@ -14,6 +19,7 @@ module Clowk
       signed_in_method = :"#{scope}_signed_in?"
 
       enforce_session_method = :"#{scope}_enforce_session!"
+      enforce_fresh_method = :"#{scope}_enforce_fresh_session!"
       sign_out_method = :"#{scope}_sign_out!"
 
       base.class_eval do
@@ -41,6 +47,12 @@ module Clowk
           end
         end
 
+        unless enforce_fresh_method == :clowk_enforce_fresh_session!
+          define_method(enforce_fresh_method) do
+            clowk_enforce_fresh_session!
+          end
+        end
+
         unless sign_out_method == :clowk_sign_out!
           define_method(sign_out_method) do
             clowk_sign_out!
@@ -55,6 +67,22 @@ module Clowk
       Clowk::Authenticable.install_dynamic_methods(self)
     end
 
+    class_methods do
+      # Demand a live answer from Clowk before these actions, whatever a cached
+      # status says.
+      #
+      #   class ApiKeysController < ApplicationController
+      #     clowk_require_fresh_session only: [:create, :update, :destroy]
+      #   end
+      #
+      # Takes the same options as before_action. Everything NOT listed keeps the
+      # cached check, which is the point: an app pays for a round trip on the few
+      # actions that cannot be undone, and nowhere else.
+      def clowk_require_fresh_session(**options)
+        before_action(**options) { clowk_enforce_fresh_session! }
+      end
+    end
+
     # Per-request credentials — for apps whose keys are not a boot constant:
     # an operator pastes a publishable key into a settings screen, or one
     # process serves several tenants.
@@ -90,27 +118,45 @@ module Clowk
       clowk_current_resource.present?
     end
 
-    def clowk_session_status
-      @clowk_session_status ||= resolve_session_status
-    end
+    # @param force [Boolean] ignore any cached status and ask Clowk now
+    def clowk_session_status(force: false)
+      return @clowk_session_status if defined?(@clowk_session_status) && !force
 
-    def clowk_session_active?
-      clowk_session_status&.dig(:status) == "active"
+      @clowk_session_status = resolve_session_status(force: force)
     end
 
-    def clowk_enforce_session!
-      return if clowk_session_active?
+    # @param force [Boolean] see {#clowk_session_status}
+    def clowk_session_active?(force: false)
+      status = clowk_session_status(force: force)
 
-      session_info = clowk_session_status
-      callback = Clowk.config.on_session_expired
+      # "Could not ask" rather than "not active": a blip on the way to a single
+      # droplet must not sign everyone out. max_session_age is the bound on how
+      # long that can carry a session Clowk would have refused.
+      return true if @clowk_session_check_unavailable && Clowk.config.fail_open_on_broker_error
 
-      if callback.respond_to?(:call)
-        callback.call(self, session_info)
+      status&.dig(:status) == "active"
+    end
 
-        return
-      end
+    # Ends the session unless Clowk says, right now, that it still stands.
+    #
+    # For the handful of actions where a cached "active" is not good enough:
+    # rotating a secret, deleting an account, removing a member. Everything else
+    # should take the cached check — this is a round trip, on purpose.
+    #
+    #   clowk_require_fresh_session only: [:destroy, :rotate_secret]
+    #
+    # Before 0.7 the only way to get this was `session_status_ttl = 0`, which
+    # bought freshness here by paying a round trip on every page instead.
+    def clowk_enforce_fresh_session!
+      clowk_enforce_session!(force: true)
+    end
 
-      clowk_handle_expired_session(session_info)
+    # @param force [Boolean] see {#clowk_session_status}
+    def clowk_enforce_session!(force: false)
+      return clowk_expire_session!(nil) if clowk_session_beyond_max_age?
+      return if clowk_session_active?(force: force)
+
+      clowk_expire_session!(clowk_session_status)
     end
 
     def clowk_authenticate!
@@ -158,6 +204,37 @@ module Clowk
       end
     end
 
+    # One route out of a session that must end, whatever ended it — the broker
+    # said inactive, or the local ceiling passed. Apps hook it with
+    # config.on_session_expired; the default answers 401 or redirects.
+    def clowk_expire_session!(session_info)
+      callback = Clowk.config.on_session_expired
+
+      if callback.respond_to?(:call)
+        callback.call(self, session_info)
+
+        return
+      end
+
+      clowk_handle_expired_session(session_info)
+    end
+
+    # A ceiling Clowk plays no part in. Without it, failing open on an
+    # unreachable broker would mean a session that never ends.
+    #
+    # signed_in_at is stamped once, when the session is established:
+    # clowk_current_resource prefers the stored payload, so persist_clowk_session
+    # does not run again while the session stands.
+    def clowk_session_beyond_max_age?
+      max = Clowk.config.max_session_age.to_i
+
+      return false unless max.positive?
+
+      started = (stored_session&.dig("signed_in_at") || stored_session&.dig(:signed_in_at)).to_i
+
+      started.positive? && (Time.now.to_i - started) > max
+    end
+
     def clowk_handle_expired_session(_session_info)
       if clowk_api_request?
         render json: {error: "Session expired or inactive"}, status: :unauthorized
@@ -253,8 +330,9 @@ module Clowk
       })
     end
 
-    def resolve_session_status
-      cached = clowk_read_cached_session_status
+    def resolve_session_status(force: false)
+      @clowk_session_check_unavailable = false
+      cached = force ? nil : clowk_read_cached_session_status
 
       return cached if cached
 
@@ -273,6 +351,14 @@ module Clowk
 
       status
     rescue Clowk::InvalidTokenError
+      nil
+    rescue *BROKER_UNAVAILABLE => e
+      # Never cached: "we could not ask" is not an answer worth keeping, and the
+      # next request should try again rather than inherit this one's bad luck.
+      @clowk_session_check_unavailable = true
+
+      Clowk.config.http_logger&.warn("[Clowk] session check unavailable: #{e.class}: #{e.message}")
+
       nil
     end
 
@@ -291,7 +377,22 @@ module Clowk
       store.read(clowk_status_cache_key)&.deep_symbolize_keys
     end
 
+    # A TTL of zero means "never trust a cached status", so there is nothing to
+    # write anywhere — the read side already discards whatever is there
+    # (clowk_session_status_fresh? is false without a positive TTL).
+    #
+    # The guard used to sit below the session branch and cover only the external
+    # cache, so an app that set the TTL to zero — to guarantee a genuinely fresh
+    # check before a destructive action — still had the full status payload
+    # written into its session on every single request, and never read back.
+    # That is write-only weight in a cookie with 4096 bytes to live in, and it
+    # ends as ActionDispatch::Cookies::CookieOverflow on whichever request
+    # happens to add a flash message.
     def clowk_write_cached_session_status(status)
+      ttl = Clowk.config.session_status_ttl.to_i
+
+      return unless ttl.positive?
+
       if clowk_session_store
         clowk_session_store[Clowk.config.session_key] = stored_session.merge(
           "session_status" => status,
@@ -301,10 +402,9 @@ module Clowk
         return
       end
 
-      ttl = Clowk.config.session_status_ttl.to_i
       store = clowk_status_cache
 
-      return unless store && ttl.positive?
+      return unless store
 
       store.write(clowk_status_cache_key, status, expires_in: ttl)
     end

data/lib/clowk/configuration.rb

@@ -25,6 +25,8 @@ module Clowk
     attr_accessor :enforce_active_session
     attr_accessor :on_session_expired
     attr_accessor :session_status_ttl
+    attr_accessor :max_session_age
+    attr_accessor :fail_open_on_broker_error
     attr_writer :session_status_cache
 
     def initialize
@@ -52,6 +54,16 @@ module Clowk
       # which silently turns every later enforcement call into a no-op. Set 0 to
       # check on every call.
       @session_status_ttl = 300
+
+      # A local ceiling the broker plays no part in, so a permanently
+      # unreachable Clowk cannot keep a session alive forever — the other half
+      # of failing open. nil leaves the broker as the only authority.
+      @max_session_age = nil
+
+      # A network blip must not sign everyone out. When the liveness check
+      # cannot be made at all, the session is left standing and checked again on
+      # the next request; max_session_age is what bounds that.
+      @fail_open_on_broker_error = true
     end
 
     # Where API-only apps cache session status, since they have no Rails session

data/lib/clowk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clowk
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clowk
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Clowk