clowk 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 724e8bb8826e85a7ca8a5ab0a35252a173ae351914318fdf1e7337b28d0acf24
-  data.tar.gz: '0649d40341028b61fa6bc6c5ec48f11d4426db5a3919e231b043b512df5d8676'
+  metadata.gz: b01072bf359496a3554b9f8d71aa01574ac36e0a3af9d3f8f1b3f70f403d9518
+  data.tar.gz: f50d5b860acb97711bebaed47f0ba5ab7a3cd9e22e154db84cf2d89a94e207ad
 SHA512:
-  metadata.gz: 9d641c9a88626dbadcd07e71aa433c34526c4e5de64e4727c593ceff50d227ca29ab8cee2352f0f69912e98b10dc4e341e81aa2382be49db192937a7b7fc7a3c
-  data.tar.gz: 6d896475327369927e31eb9ea02c40d635739b945cd01389a2431d2717030364d99fff4eac03b6f10a084a00c80dc0381b5b3d9cf55ce9f5337960b364a19152
+  metadata.gz: 286be44c6c4062b813f88d52c2d47c4a60210a847485a00ebad88e3c73fd4e08092704173446ba3ada396f07d46583d1d3ed5062909dae559f032cd119365d79
+  data.tar.gz: c8cff8c774890c14b70a8e90b16828bbf36184d00979cead290381c314f3e52d10e4d5357ff4841aa635caaf17ae843901b6bb8f449cd4947e22b746e79d8f87

data/README.md

@@ -69,7 +69,7 @@ end
 The callback flow includes:
 
 - session-backed `state` validation
-- JWT verification with your instance `secret_key`
+- JWT verification against Clowk's published keys (RS256), falling back to your instance `secret_key` for legacy HS256 tokens
 - internal-only redirect sanitization
 - session reset before persisting the authenticated user
 - `httponly` cookie persistence with `SameSite=Lax`
@@ -103,13 +103,56 @@ Important settings:
 
 | Setting | Purpose |
 | --- | --- |
-| `secret_key` | Required. Used to verify JWT signatures. |
-| `publishable_key` | Preferred for auth URL resolution. The gem resolves the latest instance URL from it before sign in/sign up. |
+| `secret_key` | Verifies legacy HS256 tokens. Not needed to verify RS256 tokens. |
+| `publishable_key` | Preferred for auth URL resolution. The gem resolves the latest instance URL from it before sign in/sign up. Also the default `audience`. |
 | `subdomain_url` | Fallback auth domain when you do not want publishable-key-based resolution. |
+| `jwks_url` | Where to fetch Clowk's public keys. Defaults to `<auth domain>/.well-known/jwks.json`. |
+| `audience` | Expected `aud` claim on RS256 tokens. Defaults to `publishable_key`. Set to `nil` to skip the check. |
 | `prefix_by` | Prefix used to generate helper names. Default: `:clowk`. |
 | `mount_path` | Local mount prefix used by helper path generation. Default: `/clowk`. |
 | `callback_path` | Callback route Clowk redirects back to. Default: `/clowk/oauth/callback`. |
 | `http_logger` | Optional logger used by `Clowk::Http`. |
+| `session_status_cache` | Where API-only apps cache session status. Defaults to `Rails.cache`. |
+
+### API-only Rails apps
+
+`Clowk::Authenticable` works in `ActionController::API` controllers with no
+extra setup — no session middleware, no cookie middleware:
+
+```ruby
+class ApplicationController < ActionController::API
+  include Clowk::Authenticable
+
+  before_action :authenticate_clowk!
+end
+```
+
+What changes in that mode:
+
+- **Nothing is written back.** A bearer request produces no `Set-Cookie` and no
+  session write. There is no browser to hold a cookie, a mobile client ignores
+  it, and writing a session per request defeats the point of being stateless.
+- **Failures are always 401 JSON**, never a redirect — including when the
+  request carries no `Accept: application/json`. A 302 to a sign-in page is
+  useless to an API caller.
+- **Session status is cached in `session_status_cache`** instead of the Rails
+  session, keyed by a digest of the token. Without it, `enforce_active_session`
+  would cost a round trip to Clowk on every authenticated request.
+
+### Token verification
+
+Tokens signed with `RS256` are verified against Clowk's public key set, fetched
+from `jwks_url` and cached in memory. The `kid` header selects the key, and a
+`kid` the cache has not seen triggers a single refetch — that is what makes key
+rotation invisible instead of an outage.
+
+Because every consumer trusts the same public key under RS256, the `aud` claim
+is what keeps a token minted for one app from verifying in another. It defaults
+to your `publishable_key`, so the check is on without extra configuration.
+
+Tokens signed with `HS256` still verify against `secret_key`, so tokens issued
+before Clowk migrated to RS256 keep working until they expire. Audience is not
+enforced on that path: those tokens predate the claim.
 
 Auth URL resolution priority:
 

data/lib/clowk/authenticable.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "active_support/concern"
+require "digest"
 
 module Clowk
   module Authenticable
@@ -107,16 +108,23 @@ module Clowk
     end
 
     def clowk_sign_out!
-      session.delete(Clowk.config.session_key)
-      cookies.delete(Clowk.config.cookie_key)
+      clowk_session_store&.delete(Clowk.config.session_key)
+      clowk_cookie_jar&.delete(Clowk.config.cookie_key)
 
       @clowk_current_resource = nil
     end
 
     private
 
+    # An API-only app has no session middleware, so there is nowhere to redirect
+    # a browser to and no way to come back. Redirecting there would answer a
+    # failed API call with a 302 to a sign-in page the caller cannot use.
+    def clowk_api_request?
+      clowk_session_store.nil? || request.format.json?
+    end
+
     def clowk_handle_unauthenticated
-      if request.format.json?
+      if clowk_api_request?
         render json: {error: "Unauthorized"}, status: :unauthorized
       else
         redirect_to clowk_sign_in_path(return_to: request.fullpath)
@@ -124,13 +132,38 @@ module Clowk
     end
 
     def clowk_handle_expired_session(_session_info)
-      if request.format.json?
+      if clowk_api_request?
         render json: {error: "Session expired or inactive"}, status: :unauthorized
       else
         redirect_to clowk_sign_in_path(return_to: request.fullpath)
       end
     end
 
+    # Probed rather than assumed: accessing `session` without the middleware
+    # raises, and `respond_to?` is true either way because the method is
+    # delegated to the request.
+    def clowk_session_store
+      return @clowk_session_store if defined?(@clowk_session_store)
+
+      @clowk_session_store = begin
+        store = session
+        store.respond_to?(:[]) ? store : nil
+      rescue
+        nil
+      end
+    end
+
+    def clowk_cookie_jar
+      return @clowk_cookie_jar if defined?(@clowk_cookie_jar)
+
+      @clowk_cookie_jar = begin
+        jar = cookies
+        jar.respond_to?(:[]=) ? jar : nil
+      rescue
+        nil
+      end
+    end
+
     def verified_request_payload
       return unless extracted_token
 
@@ -152,7 +185,10 @@ module Clowk
     end
 
     def stored_session
-      raw_session = session[Clowk.config.session_key]
+      store = clowk_session_store
+      return if store.nil?
+
+      raw_session = store[Clowk.config.session_key]
       return unless raw_session.respond_to?(:to_h)
 
       raw_session.to_h
@@ -163,25 +199,31 @@ module Clowk
       payload&.deep_symbolize_keys
     end
 
+    # No-op for API-only apps. A bearer request must not come back with a
+    # Set-Cookie: there is no browser to hold it, the mobile client ignores it,
+    # and writing a session per request defeats the point of being stateless.
     def persist_clowk_session(token, payload)
-      session[Clowk.config.session_key] = {
+      store = clowk_session_store
+      return if store.nil?
+
+      store[Clowk.config.session_key] = {
         token:,
         user: payload,
         signed_in_at: Time.now.to_i
       }
 
-      cookies[Clowk.config.cookie_key] = {
+      clowk_cookie_jar&.[]=(Clowk.config.cookie_key, {
         value: token,
         httponly: true,
         same_site: :lax,
         secure: request.ssl?
-      }
+      })
     end
 
     def resolve_session_status
-      cached = stored_session&.dig("session_status") || stored_session&.dig(:session_status)
+      cached = clowk_read_cached_session_status
 
-      return cached&.deep_symbolize_keys if cached && clowk_session_status_fresh?
+      return cached if cached
 
       resource = clowk_current_resource
 
@@ -192,16 +234,56 @@ module Clowk
       result = client.tokens.verify_with_session(token: current_token)
       status = result&.dig(:session)
 
-      if status && stored_session
-        session[Clowk.config.session_key] = stored_session.merge(
+      clowk_write_cached_session_status(status) if status
+
+      status
+    rescue Clowk::InvalidTokenError
+      nil
+    end
+
+    def clowk_read_cached_session_status
+      if clowk_session_store
+        cached = stored_session&.dig("session_status") || stored_session&.dig(:session_status)
+
+        return cached&.deep_symbolize_keys if cached && clowk_session_status_fresh?
+
+        return nil
+      end
+
+      store = clowk_status_cache
+      return nil unless store
+
+      store.read(clowk_status_cache_key)&.deep_symbolize_keys
+    end
+
+    def clowk_write_cached_session_status(status)
+      if clowk_session_store
+        clowk_session_store[Clowk.config.session_key] = stored_session.merge(
           "session_status" => status,
           "session_status_checked_at" => Time.now.to_i
         )
+
+        return
       end
 
-      status
-    rescue Clowk::InvalidTokenError
-      nil
+      ttl = Clowk.config.session_status_ttl.to_i
+      store = clowk_status_cache
+
+      return unless store && ttl.positive?
+
+      store.write(clowk_status_cache_key, status, expires_in: ttl)
+    end
+
+    # Stateless apps have no session to hang the cached status on, so without an
+    # external store every authenticated request would pay a round trip to
+    # Clowk. Keyed by token digest — the raw token must not end up in a cache
+    # key that could be logged.
+    def clowk_status_cache
+      Clowk.config.session_status_cache
+    end
+
+    def clowk_status_cache_key
+      "clowk:session_status:#{Digest::SHA256.hexdigest(current_token.to_s)}"
     end
 
     # Whether the cached status may still be trusted. Timestamped alongside the

data/lib/clowk/configuration.rb

@@ -12,7 +12,9 @@ module Clowk
     attr_accessor :http_retry_attempts
     attr_accessor :http_retry_interval
     attr_accessor :http_write_timeout
+    attr_writer :audience
     attr_accessor :issuer
+    attr_accessor :jwks_url
     attr_accessor :mount_path
     attr_accessor :publishable_key
     attr_accessor :prefix_by
@@ -23,6 +25,7 @@ module Clowk
     attr_accessor :enforce_active_session
     attr_accessor :on_session_expired
     attr_accessor :session_status_ttl
+    attr_writer :session_status_cache
 
     def initialize
       @api_base_url = "https://api.clowk.dev/api/v1"
@@ -51,6 +54,22 @@ module Clowk
       @session_status_ttl = 300
     end
 
+    # Where API-only apps cache session status, since they have no Rails session
+    # to hang it on. Defaults to Rails.cache when Rails is loaded; set to nil to
+    # check with Clowk on every authenticated request.
+    def session_status_cache
+      return @session_status_cache if defined?(@session_status_cache)
+
+      @session_status_cache = (defined?(::Rails) && ::Rails.respond_to?(:cache)) ? ::Rails.cache : nil
+    end
+
+    # Defaults to the publishable key, which is what Clowk stamps into `aud`.
+    # Consumers already configure that key, so audience checking is on by
+    # default rather than something you have to know to switch on.
+    def audience
+      @audience.nil? ? @publishable_key : @audience
+    end
+
     def after_sign_in_path
       resolve_path(@after_sign_in_path)
     end

data/lib/clowk/engine.rb

@@ -9,6 +9,13 @@ module Clowk
         include Clowk::Helpers::UrlHelpers
       end
 
+      # API-only apps never load :action_controller_base, so without this hook
+      # clowk_sign_in_path — reached from the unauthenticated fallback — raises
+      # NoMethodError instead of rendering a 401.
+      ActiveSupport.on_load(:action_controller_api) do
+        include Clowk::Helpers::UrlHelpers
+      end
+
       ActiveSupport.on_load(:action_view) do
         include Clowk::Helpers::UrlHelpers
       end

data/lib/clowk/jwks.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+require "uri"
+
+module Clowk
+  # Fetches and caches Clowk's public key set.
+  #
+  # Keys are cached process-wide because verifying a token must not cost an
+  # HTTP round trip. A `kid` the cache has never seen forces one refetch — that
+  # is what makes key rotation invisible to consumers instead of an outage.
+  class Jwks
+    CACHE_TTL = 600
+    WELL_KNOWN_PATH = "/.well-known/jwks.json"
+
+    # Rotation should resolve in one refetch. Anything beyond that is a
+    # misconfigured issuer or a forged `kid`, and hammering the auth server on
+    # every unverifiable token turns a bad token into an outage.
+    REFETCH_COOLDOWN = 10
+
+    @cache_mutex = Mutex.new
+
+    class << self
+      def clear_cache!
+        @cache_mutex.synchronize do
+          @cache = {}
+          @last_refetch_at = {}
+        end
+      end
+
+      def key_for(kid, jwks_url: Clowk.config.jwks_url)
+        url = jwks_url || default_url
+
+        key = lookup(url, kid)
+        return key if key
+
+        # Cold or expired cache: this is the ordinary first fetch, not a
+        # rotation, so it must not spend the miss budget. Data is fresh
+        # afterwards, so a miss here means the kid is genuinely unknown.
+        return fetch_and_lookup(url, kid) unless warm?(url)
+
+        # Warm cache and an unknown kid: the set may have rotated under us.
+        return nil unless claim_refetch_slot!(url)
+
+        fetch_and_lookup(url, kid)
+      end
+
+      def default_url
+        base = Clowk.config.subdomain_url || Clowk::Subdomain.resolve_url!
+
+        "#{base.to_s.chomp("/")}#{WELL_KNOWN_PATH}"
+      rescue ConfigurationError
+        raise ConfigurationError, "set jwks_url, subdomain_url or publishable_key to verify RS256 tokens"
+      end
+
+      private
+
+      def fetch_and_lookup(url, kid)
+        fetch!(url)
+        lookup(url, kid)
+      end
+
+      def warm?(url)
+        @cache_mutex.synchronize do
+          entry = cache[url]
+
+          !entry.nil? && entry[:expires_at] > Time.now
+        end
+      end
+
+      def lookup(url, kid)
+        @cache_mutex.synchronize do
+          entry = cache[url]
+
+          next nil unless entry
+          next nil if entry[:expires_at] <= Time.now
+
+          entry[:keys][kid]
+        end
+      end
+
+      # Throttles only the refetches a cache miss triggers, not ordinary TTL
+      # refreshes. A rotation is picked up on the very next token; a storm of
+      # forged kids costs at most one fetch per cooldown window.
+      def claim_refetch_slot!(url)
+        @cache_mutex.synchronize do
+          last = last_refetch_at[url]
+
+          next false if last && Time.now - last < REFETCH_COOLDOWN
+
+          last_refetch_at[url] = Time.now
+          true
+        end
+      end
+
+      def fetch!(url)
+        uri = URI.parse(url)
+        base = uri.dup
+        base.path = ""
+        base.query = nil
+        base.fragment = nil
+
+        response = Http.get(base_url: base.to_s, path: uri.path, logger: Clowk.config.http_logger)
+
+        raise InvalidTokenError, "could not fetch JWKS from #{url}" unless response.success?
+
+        keys = parse(response.body)
+
+        @cache_mutex.synchronize do
+          cache[url] = {keys: keys, expires_at: Time.now + CACHE_TTL}
+        end
+
+        keys
+      end
+
+      def parse(body)
+        payload = body.is_a?(Hash) ? body : JSON.parse(body.to_s)
+        entries = payload["keys"] || payload[:keys] || []
+
+        entries.each_with_object({}) do |jwk, acc|
+          jwk = jwk.transform_keys(&:to_s)
+          next unless jwk["kty"] == "RSA" && jwk["kid"]
+
+          acc[jwk["kid"]] = to_rsa(jwk)
+        end
+      rescue JSON::ParserError => e
+        raise InvalidTokenError, "malformed JWKS document: #{e.message}"
+      end
+
+      # Built through DER rather than assigning n/e onto a blank key: OpenSSL 3
+      # made key objects immutable, so `set_key` no longer exists.
+      def to_rsa(jwk)
+        sequence = OpenSSL::ASN1::Sequence([
+          OpenSSL::ASN1::Integer(decode_bn(jwk["n"])),
+          OpenSSL::ASN1::Integer(decode_bn(jwk["e"]))
+        ])
+
+        OpenSSL::PKey::RSA.new(sequence.to_der)
+      end
+
+      def decode_bn(value)
+        OpenSSL::BN.new(Base64.urlsafe_decode64(pad(value.to_s)), 2)
+      end
+
+      # JWKS values are unpadded base64url; Ruby's decoder wants padding.
+      def pad(value)
+        remainder = value.length % 4
+
+        remainder.zero? ? value : value + ("=" * (4 - remainder))
+      end
+
+      def cache
+        @cache ||= {}
+      end
+
+      def last_refetch_at
+        @last_refetch_at ||= {}
+      end
+    end
+  end
+end

data/lib/clowk/jwt_verifier.rb

@@ -4,24 +4,87 @@ require "jwt"
 
 module Clowk
   class JwtVerifier
-    ALGORITHM = "HS256"
+    LEGACY_ALGORITHM = "HS256"
+    ASYMMETRIC_ALGORITHM = "RS256"
 
-    def initialize(secret_key: Clowk.config.secret_key, issuer: Clowk.config.issuer)
+    # Kept because it is part of the gem's public surface. Prefer
+    # LEGACY_ALGORITHM — this no longer describes what the verifier accepts.
+    ALGORITHM = LEGACY_ALGORITHM
+
+    def initialize(secret_key: Clowk.config.secret_key, issuer: Clowk.config.issuer,
+      audience: Clowk.config.audience, jwks_url: Clowk.config.jwks_url)
       @secret_key = secret_key
       @issuer = issuer
+      @audience = audience
+      @jwks_url = jwks_url
     end
 
     def verify(token)
+      payload, = asymmetric?(token) ? verify_asymmetric(token) : verify_legacy(token)
+      payload.deep_symbolize_keys
+    rescue JWT::DecodeError, JWT::VerificationError, JWT::ExpiredSignature,
+      JWT::InvalidIssuerError, JWT::InvalidAudError => e
+      raise InvalidTokenError, e.message
+    end
+
+    private
+
+    def asymmetric?(token)
+      header(token)["alg"] == ASYMMETRIC_ALGORITHM
+    rescue JWT::DecodeError
+      false
+    end
+
+    def header(token)
+      JWT.decode(token, nil, false).last
+    end
+
+    # Tokens signed with the shared instance secret. Kept so tokens issued
+    # before the RS256 migration keep working until they expire.
+    def verify_legacy(token)
       raise ConfigurationError, "missing Clowk secret_key" if @secret_key.to_s.empty?
 
-      options = {algorithm: ALGORITHM}
-      options[:iss] = @issuer if @issuer
-      options[:verify_iss] = @issuer.present?
+      JWT.decode(token, @secret_key, true, base_options.merge(algorithm: LEGACY_ALGORITHM))
+    end
 
-      payload, = JWT.decode(token, @secret_key, true, options)
-      payload.deep_symbolize_keys
-    rescue JWT::DecodeError, JWT::VerificationError, JWT::ExpiredSignature, JWT::InvalidIssuerError => e
-      raise InvalidTokenError, e.message
+    def verify_asymmetric(token)
+      kid = header(token)["kid"]
+
+      raise InvalidTokenError, "token is missing kid header" if kid.to_s.empty?
+
+      key = Jwks.key_for(kid, jwks_url: @jwks_url)
+
+      raise InvalidTokenError, "unknown signing key: #{kid}" unless key
+
+      JWT.decode(token, key, true, asymmetric_options)
+    end
+
+    def base_options
+      opts = {}
+
+      if @issuer
+        opts[:iss] = @issuer
+        opts[:verify_iss] = true
+      end
+
+      opts
+    end
+
+    # Audience is enforced only here, and deliberately so. Under RS256 every
+    # consumer trusts the same public key, so without `aud` a token minted for
+    # another app would verify cleanly — the shared secret used to prevent that
+    # by accident. HS256 tokens are already scoped by the per-instance secret,
+    # and the ones issued before this claim existed carry no `aud` at all, so
+    # enforcing it there would reject valid tokens during the migration window.
+    def asymmetric_options
+      opts = base_options.merge(algorithm: ASYMMETRIC_ALGORITHM)
+
+      if @audience
+        opts[:aud] = @audience
+        opts[:verify_aud] = true
+      end
+
+      opts
     end
   end
 end

data/lib/clowk/version.rb

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

data/lib/clowk.rb

@@ -48,6 +48,7 @@ require_relative "clowk/sdk/token"
 require_relative "clowk/sdk/session_config"
 require_relative "clowk/sdk/client"
 require_relative "clowk/subdomain"
+require_relative "clowk/jwks"
 require_relative "clowk/jwt_verifier"
 require_relative "clowk/helpers/url_helpers"
 require_relative "clowk/middleware/token_extractor"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clowk
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Clowk
@@ -115,6 +115,7 @@ files:
 - lib/clowk/http/response.rb
 - lib/clowk/http/retry_middleware.rb
 - lib/clowk/http/timeout_middleware.rb
+- lib/clowk/jwks.rb
 - lib/clowk/jwt_verifier.rb
 - lib/clowk/middleware/token_extractor.rb
 - lib/clowk/sdk/client.rb