clowk 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6bd80a8d0998a7b4779bb719e51a1d31c394cd53a5ea3a46b56cd2206213a949
-  data.tar.gz: 71846822f9bdf17b29357e55266480d5a352f970cd3aa0b256ffc89599277a73
+  metadata.gz: 4b724ef711942092b90d87857fea2d8d439f759813d9312cb8e20d30dcd7201e
+  data.tar.gz: 7c79da7ff63485cd70cc62fac3669a1e0f96041e52ac6782c8c229ffee28972a
 SHA512:
-  metadata.gz: d5b8fcb5938dc7cb1034a7dae4a2aec1e9dbd36cdc4ad2972f43ec99a22cf66e76779e3de3ce826a38bfd24b5add840732b5e05ae34c9b198f1fe1f506640503
-  data.tar.gz: d7adc93a749be711889b792d20c0c9f7e0d280768a40104d149be7ad71902c90052d562704018bde2ac119b9529e82da3d5aac80813387a50d56550fa96f8441
+  metadata.gz: c26df4690279d52da9f035e0636991a135d731b8472ce9071d65003507eb0272a80e7f909249f0e159c313f44fd6a4970d5568ea635517b9278abe1cfda84480
+  data.tar.gz: e8a253974a0b9dcb0610a47b3e0e26b9c24aca10799291b9abaa059399fa8b11a8ff68c1f870d11bbe6d97e715d61019994b2648a9d7b0a8fc5de690e2c36ed5

data/README.md

@@ -299,6 +299,47 @@ request, so an app does not have to wait for everyone to sign out.
 Ask for `:app` if the app reads the token out of `session[...]` itself rather
 than through `current_token`.
 
+### How long a session lasts
+
+The Clowk instance decides. Set the session lifetime in the dashboard (7 days,
+30 days) and the app keeps the user signed in for exactly that long, also in an
+installed PWA that the OS stops and starts again.
+
+```ruby
+config.publishable_key = ENV["CLOWK_PUBLISHABLE_KEY"] # required for refresh tokens
+config.refresh_tokens = true                           # default
+config.refresh_cookie_key = "clowk_refresh_token"      # default
+config.refresh_skew = 60                               # seconds, default
+```
+
+1. The callback trades the sign-in token for an access token and a refresh
+   token (`POST /sessions/exchange`).
+2. Both go into httponly cookies that expire when the Clowk session ends. A
+   cookie with no expiry is deleted when the browser closes, and a PWA closes
+   each time the OS stops it. That was why a PWA lost its session in hours.
+3. When the access token expires (or the app session cookie is gone), the next
+   request renews it with the refresh cookie. There is no redirect.
+4. When Clowk refuses the refresh (revoked, past the lifetime, idle timeout),
+   the local session ends and the user goes to sign-in. When Clowk cannot be
+   reached, the cookies stay and the next request tries again.
+5. `clowk_sign_out!` revokes the session on Clowk too.
+
+Refresh tokens rotate: each one works once. A page and its Turbo frames can
+arrive together with the same expired token, so one request rotates and the
+others take its result from `config.session_status_cache` (`Rails.cache` by
+default). Use a cache all app processes share (Solid Cache, Redis, Memcached).
+
+Also give the app's own session cookie an expiry, so the app does not need a
+refresh each time the PWA opens:
+
+```ruby
+# config/initializers/session_store.rb
+Rails.application.config.session_store :cookie_store, key: "_myapp_session", expire_after: 30.days
+```
+
+Without a publishable key, or with `config.refresh_tokens = false`, the gem keeps
+only the sign-in token, in a cookie that lives as long as the token.
+
 ### Token verification
 
 Tokens signed with `RS256` are verified against Clowk's public key set, fetched

data/lib/clowk/authenticable.rb

@@ -12,6 +12,10 @@ module Clowk
     # must not be swallowed into "the session is probably fine".
     BROKER_UNAVAILABLE = [SystemCallError, Timeout::Error, IOError, SocketError, EOFError].freeze
 
+    # How long the cookies live when Clowk does not say (a server older than
+    # refresh_expires_in). Clowk's own default session lifetime.
+    FALLBACK_SESSION_LIFETIME = 7 * 24 * 60 * 60
+
     def self.install_dynamic_methods(base)
       scope = Clowk.config.prefix_by.to_s
       current_method = :"current_#{scope}"
@@ -89,6 +93,8 @@ module Clowk
 
     def clowk_current_resource
       @clowk_current_resource ||= begin
+        clowk_end_lapsed_session!
+
         payload = stored_user_payload || verified_request_payload
 
         drop_mirrored_token!
@@ -101,8 +107,13 @@ module Clowk
     # and, for one request after an app drops that setting, in a session
     # written before the change. drop_mirrored_token! clears those. Clowk's own
     # cookie is the source either way.
+    #
+    # An expired token is renewed with the refresh cookie before it is handed
+    # out, so an API call or a session check never carries a dead token.
     def current_token
-      stored_session&.dig("token") || extracted_token
+      token = stored_session&.dig("token") || extracted_token
+
+      clowk_refresh_due?(token) ? clowk_fresh_token : token
     end
 
     def clowk_signed_in?
@@ -175,9 +186,14 @@ module Clowk
       clowk_current_resource
     end
 
-    def clowk_sign_out!
+    # @param revoke [Boolean] also end the session on Clowk, so the refresh
+    #   token cannot sign anyone in again
+    def clowk_sign_out!(revoke: true)
+      Clowk::TokenRefresher.new.revoke(clowk_refresh_cookie) if revoke
+
       clowk_session_store&.delete(Clowk.config.session_key)
       clowk_cookie_jar&.delete(Clowk.config.cookie_key)
+      clowk_cookie_jar&.delete(Clowk.config.refresh_cookie_key)
 
       @clowk_current_resource = nil
     end
@@ -277,16 +293,132 @@ module Clowk
     end
 
     def verified_request_payload
-      return unless extracted_token
+      token = clowk_refresh_due?(extracted_token) ? clowk_fresh_token : extracted_token
+
+      return unless token
 
-      payload = Clowk::JwtVerifier.new.verify(extracted_token)
-      persist_clowk_session(extracted_token, payload)
+      payload = Clowk::JwtVerifier.new.verify(token)
+
+      persist_clowk_session(token, payload)
 
       payload
     rescue Clowk::InvalidTokenError
       nil
     end
 
+    # Trades the sign-in token for an access + refresh pair, so the session
+    # lasts what the Clowk instance configures. Falls back to the sign-in
+    # token alone when there is no publishable key, the token has no session,
+    # or Clowk cannot be reached.
+    def clowk_exchange_sign_in_token(token)
+      return token unless Clowk.config.refresh_tokens && clowk_cookie_jar
+
+      pair = Clowk::TokenRefresher.new.exchange(token)
+
+      return token unless pair
+
+      clowk_adopt_token_pair!(pair)
+
+      pair[:access_token]
+    rescue Clowk::InvalidTokenError, *BROKER_UNAVAILABLE => e
+      Clowk.config.http_logger&.warn("[Clowk] token exchange skipped: #{e.class}: #{e.message}")
+
+      token
+    end
+
+    def clowk_refresh_due?(token)
+      return false unless Clowk.config.refresh_tokens
+      return false if clowk_refresh_cookie.blank?
+      return true if token.blank?
+
+      expires_at = clowk_token_expiry(token)
+
+      expires_at.nil? || expires_at - Clowk.config.refresh_skew.to_i <= Time.now.to_i
+    end
+
+    # A refused refresh means the session is over on Clowk (revoked, past its
+    # lifetime, idle), so the local one ends too. An unreachable Clowk is not
+    # an answer: the cookies stay for the next request.
+    def clowk_fresh_token
+      return @clowk_fresh_token if defined?(@clowk_fresh_token)
+
+      @clowk_fresh_token = begin
+        pair = Clowk::TokenRefresher.new.refresh(clowk_refresh_cookie)
+
+        clowk_adopt_token_pair!(pair)
+
+        pair[:access_token]
+      rescue Clowk::InvalidTokenError
+        clowk_sign_out!(revoke: false)
+
+        nil
+      rescue *BROKER_UNAVAILABLE => e
+        Clowk.config.http_logger&.warn("[Clowk] token refresh unavailable: #{e.class}: #{e.message}")
+
+        extracted_token
+      end
+    end
+
+    # Both cookies end when the Clowk session ends. A cookie with no expiry is
+    # deleted when the browser closes, and an installed PWA closes each time
+    # the OS stops it.
+    def clowk_adopt_token_pair!(pair)
+      expires_at = Time.now + (pair[:refresh_expires_in].presence || FALLBACK_SESSION_LIFETIME).to_i
+
+      @clowk_session_expires_at = expires_at
+
+      clowk_write_cookie(Clowk.config.cookie_key, pair[:access_token], expires_at)
+      clowk_write_cookie(Clowk.config.refresh_cookie_key, pair[:refresh_token], expires_at) if pair[:refresh_token].present?
+
+      held = stored_session
+      store = clowk_session_store
+
+      return if held.nil? || store.nil?
+
+      updated = held.merge("expires_at" => expires_at.to_i)
+      updated["token"] = pair[:access_token] if Clowk.config.token_store == :app
+
+      store[Clowk.config.session_key] = updated
+    end
+
+    def clowk_write_cookie(key, value, expires_at)
+      clowk_cookie_jar&.[]=(key, {
+        value: value,
+        expires: expires_at,
+        httponly: true,
+        same_site: :lax,
+        secure: clowk_secure_request?
+      })
+    end
+
+    def clowk_secure_request?
+      request.respond_to?(:ssl?) && request.ssl?
+    end
+
+    def clowk_refresh_cookie
+      clowk_cookie_jar&.[](Clowk.config.refresh_cookie_key).presence
+    end
+
+    def clowk_token_expiry(token)
+      JWT.decode(token, nil, false).first["exp"]&.to_i
+    rescue JWT::DecodeError
+      nil
+    end
+
+    # The stored session carries the end of the Clowk session. Past it, the
+    # local session ends too, even when the host app's session cookie lives on.
+    def clowk_end_lapsed_session!
+      held = stored_session
+
+      return if held.nil?
+
+      expires_at = (held["expires_at"] || held[:expires_at]).to_i
+
+      return unless expires_at.positive? && expires_at <= Time.now.to_i
+
+      clowk_sign_out!(revoke: false)
+    end
+
     # Bearer header or cookie only — never the query string. A valid token in a
     # URL would otherwise sign the visitor in on ANY path, bypassing the state
     # check that makes the OAuth callback safe, and would stay replayable for the
@@ -319,16 +451,21 @@ module Clowk
       return if store.nil?
 
       claims = {user: payload, signed_in_at: Time.now.to_i}
+      claims[:expires_at] = @clowk_session_expires_at.to_i if @clowk_session_expires_at
 
       store[Clowk.config.session_key] =
         (Clowk.config.token_store == :app) ? claims.merge(token:) : claims
 
-      clowk_cookie_jar&.[]=(Clowk.config.cookie_key, {
-        value: token,
-        httponly: true,
-        same_site: :lax,
-        secure: request.ssl?
-      })
+      return if @clowk_session_expires_at
+
+      clowk_write_cookie(Clowk.config.cookie_key, token, clowk_token_cookie_expiry(token))
+    end
+
+    # Without a refresh token the cookie lives as long as the token does.
+    def clowk_token_cookie_expiry(token)
+      expires_at = clowk_token_expiry(token)
+
+      expires_at ? Time.at(expires_at) : nil
     end
 
     # A session written under :app still carries the token, and

data/lib/clowk/configuration.rb

@@ -28,6 +28,9 @@ module Clowk
     attr_accessor :max_session_age
     attr_accessor :fail_open_on_broker_error
     attr_accessor :token_store
+    attr_accessor :refresh_tokens
+    attr_accessor :refresh_cookie_key
+    attr_accessor :refresh_skew
     attr_writer :session_status_cache
 
     def initialize
@@ -86,6 +89,21 @@ module Clowk
       # :app is there for an app that reads the token out of `session[...]`
       # itself, rather than through `current_token`.
       @token_store = nil
+
+      # Keeps the user signed in for the session lifetime the Clowk instance
+      # configures (7 days, 30 days, whatever the dashboard says), not for the
+      # one hour an access token lives.
+      #
+      # On sign-in the callback trades the token for an access + refresh pair.
+      # Both go into cookies that expire when the Clowk session ends, so they
+      # survive a closed browser or a stopped PWA. An expired access token is
+      # renewed on the next request, without a redirect. Needs the publishable
+      # key; without one the gem keeps only the sign-in token, as before.
+      @refresh_tokens = true
+      @refresh_cookie_key = "clowk_refresh_token"
+
+      # Renew the access token this many seconds before it expires.
+      @refresh_skew = 60
     end
 
     # Where API-only apps cache session status, since they have no Rails session

data/lib/clowk/controllers/callbacks_controller.rb

@@ -13,6 +13,9 @@ module Clowk
       return_to = flow["return_to"]
 
       reset_clowk_session!
+
+      token = clowk_exchange_sign_in_token(token)
+
       persist_clowk_session(token, payload)
 
       redirect_back_or(Clowk.config.after_sign_in_path, return_to:)

data/lib/clowk/sdk/session_token.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Clowk
+  module SDK
+    # The refresh token lifecycle. Authenticated with the publishable key: the
+    # refresh token is the credential.
+    #
+    #   pair = client.session_tokens.exchange(token: sign_in_token)
+    #   pair = client.session_tokens.refresh(refresh_token: pair[:refresh_token])
+    #
+    # Each pair is a Hash with :access_token, :refresh_token, :expires_in,
+    # :refresh_expires_in and :session_id. A refused call raises
+    # Clowk::InvalidTokenError.
+    class SessionToken < Resource
+      def self.resource_path
+        "sessions"
+      end
+
+      # Trades the sign-in token from the callback for an access + refresh pair.
+      def exchange(token:)
+        pair_from(client.post("#{self.class.resource_path}/exchange", {token: token}))
+      end
+
+      # Spends the refresh token and returns its successor.
+      def refresh(refresh_token:)
+        pair_from(client.post("#{self.class.resource_path}/refresh", {refresh_token: refresh_token}))
+      end
+
+      # Ends the session the refresh token belongs to.
+      def revoke(refresh_token:)
+        client.post("#{self.class.resource_path}/revoke", {refresh_token: refresh_token})
+      end
+
+      private
+
+      def pair_from(response)
+        body = response.body_parsed
+
+        unless response.success?
+          message = body.is_a?(Hash) ? body["error"] : nil
+
+          raise Clowk::InvalidTokenError, message || "session token request failed"
+        end
+
+        data = (body.is_a?(Hash) && body["data"].is_a?(Hash)) ? body["data"] : body
+        pair = data.to_h.deep_symbolize_keys
+
+        raise Clowk::InvalidTokenError, "session token response has no access_token" if pair[:access_token].blank?
+
+        pair
+      end
+    end
+  end
+end

data/lib/clowk/token_refresher.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Clowk
+  # Exchanges and refreshes session tokens, one refresh per refresh token.
+  #
+  # Refresh tokens rotate: each one works once. A page and its Turbo frames
+  # can arrive together with the same expired access token, and each would
+  # spend the same refresh token. Only the first wins, and the rest would sign
+  # the user out. The first request takes a lock in the cache and shares the
+  # new pair; the others wait for it and use the same pair.
+  #
+  # The lock works across processes only with a shared cache (Solid Cache,
+  # Redis, Memcached). With a per-process cache, Clowk's grace window for a
+  # just-rotated token keeps the session alive, and the late request is
+  # signed in again on the next request.
+  class TokenRefresher
+    LOCK_TTL = 10
+    RESULT_TTL = 30
+    WAIT_TIMEOUT = 5.0
+    WAIT_INTERVAL = 0.05
+
+    def initialize(cache: Clowk.config.session_status_cache, client: nil)
+      @cache = cache
+      @client = client
+    end
+
+    # @return [Hash, nil] the pair, or nil when no publishable key is set
+    # @raise [Clowk::InvalidTokenError] when Clowk refuses the token
+    def exchange(token)
+      return unless publishable_key?
+
+      sdk.session_tokens.exchange(token: token)
+    end
+
+    # @return [Hash] the new pair
+    # @raise [Clowk::InvalidTokenError] when Clowk refuses the refresh token
+    def refresh(refresh_token)
+      key = Digest::SHA256.hexdigest(refresh_token.to_s)
+
+      shared = read_shared(key)
+
+      return shared if shared
+
+      return rotate(refresh_token, key) if acquire_lock(key)
+
+      wait_for_shared(key) || raise(Clowk::InvalidTokenError, "concurrent refresh did not finish")
+    end
+
+    # Ends the session on Clowk. Best effort: a sign-out must not fail because
+    # the broker is down.
+    def revoke(refresh_token)
+      return if refresh_token.blank? || !publishable_key?
+
+      sdk.session_tokens.revoke(refresh_token: refresh_token)
+    rescue Clowk::Error, *Clowk::Authenticable::BROKER_UNAVAILABLE
+      nil
+    end
+
+    private
+
+    attr_reader :cache
+
+    def rotate(refresh_token, key)
+      pair = sdk.session_tokens.refresh(refresh_token: refresh_token)
+
+      cache&.write(result_key(key), pair, expires_in: RESULT_TTL)
+
+      pair
+    rescue Clowk::InvalidTokenError
+      cache&.write(result_key(key), {refused: true}, expires_in: RESULT_TTL)
+
+      raise
+    ensure
+      cache&.delete(lock_key(key))
+    end
+
+    def acquire_lock(key)
+      return true if cache.nil?
+
+      cache.write(lock_key(key), 1, unless_exist: true, expires_in: LOCK_TTL)
+    end
+
+    def wait_for_shared(key)
+      deadline = monotonic_now + WAIT_TIMEOUT
+
+      while monotonic_now < deadline
+        sleep(WAIT_INTERVAL)
+
+        shared = read_shared(key)
+
+        return shared if shared
+      end
+
+      nil
+    end
+
+    def read_shared(key)
+      shared = cache&.read(result_key(key))&.deep_symbolize_keys
+
+      raise Clowk::InvalidTokenError, "refresh token was refused" if shared&.dig(:refused)
+
+      shared
+    end
+
+    def result_key(key)
+      "clowk:refresh:result:#{key}"
+    end
+
+    def lock_key(key)
+      "clowk:refresh:lock:#{key}"
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def publishable_key?
+      Clowk.credentials.publishable_key.present?
+    end
+
+    def sdk
+      @client ||= Clowk::SDK::Client.new
+    end
+  end
+end

data/lib/clowk/version.rb

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

data/lib/clowk.rb

@@ -51,6 +51,7 @@ require_relative "clowk/sdk/session"
 require_relative "clowk/sdk/subdomain"
 require_relative "clowk/sdk/token"
 require_relative "clowk/sdk/session_config"
+require_relative "clowk/sdk/session_token"
 require_relative "clowk/sdk/client"
 require_relative "clowk/subdomain"
 require_relative "clowk/jwks"
@@ -58,6 +59,7 @@ require_relative "clowk/jwt_verifier"
 require_relative "clowk/helpers/url_helpers"
 require_relative "clowk/middleware/token_extractor"
 require_relative "clowk/authenticable"
+require_relative "clowk/token_refresher"
 require_relative "clowk/controllers/base_controller"
 require_relative "clowk/controllers/callbacks_controller"
 require_relative "clowk/controllers/sessions_controller"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clowk
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Clowk
@@ -123,10 +123,12 @@ files:
 - lib/clowk/sdk/resource.rb
 - lib/clowk/sdk/session.rb
 - lib/clowk/sdk/session_config.rb
+- lib/clowk/sdk/session_token.rb
 - lib/clowk/sdk/subdomain.rb
 - lib/clowk/sdk/token.rb
 - lib/clowk/sdk/user.rb
 - lib/clowk/subdomain.rb
+- lib/clowk/token_refresher.rb
 - lib/clowk/version.rb
 homepage: https://clowk.in
 licenses: