clowk 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5027a092ba122ab807f5c0340bc30399f7ab85f9ef41bc99c5610b68df6f47f7
-  data.tar.gz: 1f0dd44bf7696a1e3cffed45cb4c48edc92db3025007db39c6ea721f119619a8
+  metadata.gz: 1593747e0040a0056565a40b2bf1699d8242af1d253751ce3ea5c86949ff1f7a
+  data.tar.gz: 33147a1e6f88c7970d52bf33403566c09309315c53b8e080416aaece4f1ecc2a
 SHA512:
-  metadata.gz: 20a10b0715b1695694c51b915490ad852ba43004e9f1ec1b0fbc7af1d192737250234d4342ea1cac3db7ef6a94dc992b17795ee5ab2f0e0fcc6b23e7237a7c27
-  data.tar.gz: 124f14e7d6e53e7c904faa98befc85d18e7f1644f02d654a01c037555d589f4085069945435c7c81aaad36db4158b019b8f61faaeb359ac61839b09edf65d7a0
+  metadata.gz: 0cf89e539def821193dd451c8902e581423f103acd8881ce67d7eadb9cfd9e2e69302a265769679eb5a906593a89253f4781cf625546ee3bbd3d8d012d15584a
+  data.tar.gz: f4993722c5349f80a7a10f39cff94d3b76b4909b700272f23458bca7d227fa263258c78b01cf511e2cb5d30640dae84a991fd686939fc4fbfcd2cee7b2e5e757

data/README.md

@@ -107,13 +107,101 @@ Important settings:
 | `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. |
+| `audience` | Expected `aud` claim on RS256 tokens. Defaults to `publishable_key`. Set to `false` 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`. |
 
+### Runtime credentials
+
+`Clowk.configure` is the right place for credentials that are a boot constant.
+Some apps do not have that: an operator pastes a publishable key into a settings
+screen and expects sign-in to work on the next request, or one process serves
+several tenants and each one has its own instance.
+
+For those, there is one method — `Clowk.with_credentials`. It scopes the
+credentials to a block instead of the process:
+
+```ruby
+Clowk.with_credentials(publishable_key: "pk_live_…") do
+  # sign-in URLs, JWKS, token verification and the SDK client
+  # all resolve against that instance in here
+end
+```
+
+`secret_key` and `subdomain_url` go in the same way and are both optional —
+RS256 needs no secret, and the auth domain is resolved from the publishable key
+when absent.
+
+In a Rails controller, wire it with an `around_action` you name yourself:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Clowk::Authenticable
+
+  around_action :require_tenant_key!
+  before_action :authenticate_clowk_user!
+
+  private
+
+  def require_tenant_key!(&)
+    Clowk.with_credentials(publishable_key: Tenant.current.key, &)
+  end
+end
+```
+
+How you spell the block is yours too — `(&)`, `(&block)`, `(&action)`, or
+`{ yield }`. The examples here use `(&)`; nothing in the gem depends on it.
+
+`:allow_own_credentials!`, `:use_workspace_sso!` — the gem does not care, and
+never looks for a method named its way. Where the credentials come from is
+equally yours: an environment variable, a settings row, the subdomain, a header.
+
+`nil` runs the block against the boot configuration, so a request with no tenant
+needs no branch at the call site:
+
+```ruby
+def require_tenant_key!(&)
+  Clowk.with_credentials(Tenant.current&.clowk_credentials, &)
+end
+```
+
+That second form takes a `Clowk::Credentials` object, for callers that already
+have one — a row that knows how to describe itself, say. The keyword form builds
+it for you, so the common case never has to name the class.
+
+The same call works in a job, a rake task or a script; there is nothing
+controller-specific about it, and `Clowk::Authenticable` deliberately adds no
+second name for the same idea.
+
+Nothing installs the filter for you. `around_action` has to wrap
+`authenticate_clowk_user!`, and where it sits among your own filters is a
+decision only your app can make — a gem that registers callbacks on your
+controller is one you have to read to know what runs.
+
+`Clowk.credentials` is the reader: the scoped value when one is in force, the
+boot configuration otherwise. An app that never scopes anything behaves exactly
+as it did before this existed, and explicitly passed arguments
+(`Clowk::SDK::Client.new(secret_key: …)`) still win over both.
+
+**There is no `Clowk.secret_key = …` setter, on purpose.** A setter has no
+lifetime, so the first request that raises between the assignment and its reset
+leaves that key installed process-wide — and the secret key mints HS256 tokens
+for any subject, on the verification path that does not check `aud`. A leaked
+scope would be an authentication bypass rather than an untidy configuration. The
+block's `ensure` is what makes the lifetime a property of the API instead of the
+caller's discipline. Scopes nest, and the inner one restores the outer.
+
+Scoping is fiber-based (`ActiveSupport::IsolatedExecutionState`), so it survives
+streaming responses and async adapters rather than reverting to the global
+halfway through a request.
+
+The caches were already built for this: `Clowk::Jwks` keys by URL and
+`Clowk::Subdomain` keys by publishable key, so switching instances at runtime
+selects a different cache entry instead of poisoning the previous one.
+
 ### API-only Rails apps
 
 `Clowk::Authenticable` works in `ActionController::API` controllers with no
@@ -259,6 +347,27 @@ Mounted routes exposed by the engine:
 
 When you mount the engine elsewhere, the same route set is exposed under your chosen prefix.
 
+### Turbo and the sign-in redirect
+
+`/clowk/sign_in` answers with a redirect to your Clowk instance, which is a
+different origin. **Turbo cannot follow a cross-origin redirect.** It does not
+raise and it does not warn: the fetch is dropped, the page stays exactly as it
+was, and the submit reads as a button that does nothing. A later manual refresh
+works, which makes it look like flakiness rather than a missing opt-out.
+
+Links are fine. A **form** that ends up at `/sign_in` — a settings screen that
+turns sign-in on, say — has to opt out so the browser performs the navigation
+itself:
+
+```erb
+<%= form_with url: clowk.sign_in_path, method: :get, data: { turbo: false } do |form| %>
+  <%= form.submit 'Sign in' %>
+<% end %>
+```
+
+The same applies to any of your own actions that redirect to `/sign_in` at the
+end: the chain still terminates cross-origin.
+
 ## Token sources
 
 The concern can read the token from:
@@ -405,4 +514,4 @@ Its job is to make the Rails side of Clowk integration predictable:
 
 ## License
 
-AGPL-3.0. See `LICENSE`.
+MIT. See `LICENSE`.

data/clowk.gemspec

@@ -11,8 +11,8 @@ Gem::Specification.new do |spec|
   spec.summary = "Rails SDK for Clowk authentication"
   spec.description = "Clowk Authentication, JWT verification, and future API access"
   spec.homepage = "https://clowk.in"
-  spec.license = "AGPL-3.0-only"
-  spec.required_ruby_version = ">= 3.3"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1"
   spec.metadata = {
     "rubygems_mfa_required" => "true"
   }

data/lib/clowk/authenticable.rb

@@ -55,6 +55,26 @@ module Clowk
       Clowk::Authenticable.install_dynamic_methods(self)
     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.
+    #
+    # There is no method here for that, on purpose. `Clowk.with_credentials`
+    # does it, works the same in a job or a rake task, and one name is one name
+    # to remember:
+    #
+    #   around_action :require_tenant_key!
+    #
+    #   def require_tenant_key!(&)
+    #     Clowk.with_credentials(publishable_key: Tenant.current.key, &)
+    #   end
+    #
+    # Name that filter whatever your app calls the idea, and spell the block
+    # however you like — `(&)`, `(&block)`, `{ yield }`. Nothing in this gem
+    # looks for a method of its own naming, and no macro installs a callback
+    # for you. `around_action` has to wrap `authenticate_clowk_user!`, and
+    # where it sits among your own filters is a decision only your app can make.
+
     def clowk_current_resource
       @clowk_current_resource ||= begin
         payload = stored_user_payload || verified_request_payload
@@ -241,9 +261,11 @@ module Clowk
       resource = clowk_current_resource
 
       return unless resource&.session_id
-      return unless Clowk.config.secret_key.present?
+      secret_key = Clowk.credentials.secret_key
+
+      return unless secret_key.present?
 
-      client = Clowk::SDK::Client.new(secret_key: Clowk.config.secret_key)
+      client = Clowk::SDK::Client.new(secret_key: secret_key)
       result = client.tokens.verify_with_session(token: current_token)
       status = result&.dig(:session)
 

data/lib/clowk/credentials.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "active_support/isolated_execution_state"
+
+module Clowk
+  # Credentials — which Clowk instance is answering, right here, right now.
+  #
+  # Everything else in Configuration describes the HOST: where the callback
+  # lives, how long HTTP waits, what the helpers are called. Those are decided
+  # once, at boot, by the person who wrote the initializer. These four are
+  # different — they name an instance, and an app that lets an operator paste a
+  # publishable key into a settings screen, or that serves several tenants from
+  # one process, has to be able to answer "which instance" per request rather
+  # than per process.
+  #
+  # A value object rather than four accessors because they only mean anything
+  # together. A publishable key from one instance beside a secret key from
+  # another is not a partial configuration, it is a broken one, and separate
+  # setters make that state reachable in between two assignments.
+  #
+  # `audience` defaults to the publishable key, which is what Clowk stamps into
+  # `aud` — the same rule Configuration#audience has always had, and it is
+  # carried here rather than left on the global for the reason this class
+  # exists: a SCOPED publishable key must be checked against a scoped audience.
+  # Reading the audience off the global while the key came from a tenant would
+  # verify one tenant's token against another tenant's expectation, silently,
+  # on the happy path. Pass `false` to switch the check off.
+  #
+  # See Clowk.with_credentials for why the scoped form is a block and not a
+  # setter.
+  # A Struct rather than a Data, and frozen by hand, so the gem keeps running on
+  # Ruby 3.1 — `Data` arrived in 3.2. The freeze is not decoration: credentials
+  # are installed into a scope and read from four places while a request runs,
+  # and a member somebody could reassign halfway through would be the
+  # half-swapped state this class exists to make unreachable.
+  Credentials = Struct.new(:publishable_key, :secret_key, :subdomain_url, :jwks_url, :audience,
+    keyword_init: true) do
+    # Every member optional: an app that only sets a publishable key is the
+    # common case, and RS256 needs nothing else.
+    #
+    # `audience` is DERIVED HERE, at construction, rather than in the reader.
+    # Deriving it on read would mean `to_h` and `==` saw nil while callers saw
+    # the publishable key — a value object that disagrees with itself. Settled
+    # once, so what it holds is what it means.
+    def initialize(publishable_key: nil, secret_key: nil, subdomain_url: nil,
+      jwks_url: nil, audience: nil)
+      super(
+        publishable_key: publishable_key,
+        secret_key: secret_key,
+        subdomain_url: subdomain_url,
+        jwks_url: jwks_url,
+        audience: audience.nil? ? publishable_key : audience
+      )
+
+      freeze
+    end
+
+    # The boot configuration, as credentials. This is what `Clowk.credentials`
+    # falls back to, so an installation that configures once and never scopes
+    # anything behaves exactly as it did before this existed.
+    def self.from(config)
+      new(
+        publishable_key: config.publishable_key,
+        secret_key: config.secret_key,
+        subdomain_url: config.subdomain_url,
+        jwks_url: config.jwks_url,
+        audience: config.audience
+      )
+    end
+  end
+
+  class << self
+    # The credentials in force for the current execution context.
+    #
+    # The scoped override if there is one, the boot configuration otherwise.
+    # Read this instead of Clowk.config wherever an instance is being named, so
+    # a consumer that never scopes anything pays nothing and a consumer that
+    # does is served correctly.
+    def credentials
+      ActiveSupport::IsolatedExecutionState[:clowk_credentials] || Credentials.from(config)
+    end
+
+    # Run a block against a particular Clowk instance.
+    #
+    # THE ONLY METHOD AN APP EVER CALLS. Attributes go straight in, so the
+    # common case never has to name the Credentials class:
+    #
+    #   Clowk.with_credentials(publishable_key: tenant.key) do
+    #     # sign-in URLs, JWKS, verification and the API client
+    #     # all resolve against that instance in here
+    #   end
+    #
+    # A prebuilt object works too, for callers that already have one — an
+    # ActiveRecord row that knows how to describe itself, say:
+    #
+    #   Clowk.with_credentials(tenant.clowk_credentials) { … }
+    #
+    # And nil runs the block against the boot configuration, so "this request
+    # has no tenant" needs no branch at the call site:
+    #
+    #   Clowk.with_credentials(tenant&.clowk_credentials) { … }
+    #
+    # A BLOCK, AND DELIBERATELY NOT A SETTER. `Clowk.secret_key = x` has no
+    # lifetime: the first request that raises between the assignment and its
+    # reset leaves that key installed process-wide, and the secret key mints
+    # HS256 tokens for any subject — Clowk::JwtVerifier routes to the symmetric
+    # path whenever `alg` is not RS256, and that path does not check the
+    # audience. So a leaked scope is not an untidy configuration, it is an
+    # authentication bypass. The `ensure` below is the whole API.
+    #
+    # Fiber-scoped via ActiveSupport::IsolatedExecutionState rather than
+    # Thread.current, so it survives the places Rails hands work to a fiber —
+    # streaming responses, async adapters — instead of silently reverting to
+    # the global halfway through a request.
+    #
+    # Nesting restores the enclosing scope, not the global.
+    def with_credentials(credentials = nil, **attributes)
+      resolved = credentials || (Credentials.new(**attributes) unless attributes.empty?)
+
+      return yield if resolved.nil?
+
+      previous = ActiveSupport::IsolatedExecutionState[:clowk_credentials]
+      ActiveSupport::IsolatedExecutionState[:clowk_credentials] = resolved
+
+      yield
+    ensure
+      ActiveSupport::IsolatedExecutionState[:clowk_credentials] = previous if resolved
+    end
+  end
+end

data/lib/clowk/jwks.rb

@@ -30,7 +30,7 @@ module Clowk
         end
       end
 
-      def key_for(kid, jwks_url: Clowk.config.jwks_url)
+      def key_for(kid, jwks_url: Clowk.credentials.jwks_url)
         url = jwks_url || default_url
 
         key = lookup(url, kid)
@@ -48,7 +48,7 @@ module Clowk
       end
 
       def default_url
-        base = Clowk.config.subdomain_url || Clowk::Subdomain.resolve_url!
+        base = Clowk.credentials.subdomain_url || Clowk::Subdomain.resolve_url!
 
         "#{base.to_s.chomp("/")}#{WELL_KNOWN_PATH}"
       rescue ConfigurationError

data/lib/clowk/jwt_verifier.rb

@@ -11,8 +11,11 @@ module Clowk
     # 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)
+    # Credentials come from Clowk.credentials, which is the scoped override when
+    # one is in force and the boot configuration otherwise. `issuer` stays on
+    # config: it describes the token format, not which instance issued it.
+    def initialize(secret_key: Clowk.credentials.secret_key, issuer: Clowk.config.issuer,
+      audience: Clowk.credentials.audience, jwks_url: Clowk.credentials.jwks_url)
       @secret_key = secret_key
       @issuer = issuer
       @audience = audience

data/lib/clowk/sdk/client.rb

@@ -7,8 +7,8 @@ module Clowk
     class Client
       def initialize(options = {})
         @api_base_url = options.fetch(:api_base_url, nil).presence || Clowk.config.api_base_url
-        @secret_key = options.fetch(:secret_key, Clowk.config.secret_key)
-        @publishable_key = options.fetch(:publishable_key, Clowk.config.publishable_key)
+        @secret_key = options.fetch(:secret_key, Clowk.credentials.secret_key)
+        @publishable_key = options.fetch(:publishable_key, Clowk.credentials.publishable_key)
       end
 
       def method_missing(method_name, *, **, &)

data/lib/clowk/subdomain.rb

@@ -47,8 +47,8 @@ module Clowk
     end
 
     def initialize(options = {})
-      @publishable_key = options.fetch(:publishable_key, Clowk.config.publishable_key)
-      @subdomain_url = options.fetch(:subdomain_url, Clowk.config.subdomain_url)
+      @publishable_key = options.fetch(:publishable_key, Clowk.credentials.publishable_key)
+      @subdomain_url = options.fetch(:subdomain_url, Clowk.credentials.subdomain_url)
     end
 
     def resolve_url!

data/lib/clowk/version.rb

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

data/lib/clowk.rb

@@ -29,11 +29,16 @@ module Clowk
 
     def reset!
       Subdomain.clear_cache! if defined?(Subdomain)
+      ActiveSupport::IsolatedExecutionState[:clowk_credentials] = nil
       @config = Configuration.new
     end
   end
 end
 
+# After the module body: Credentials reopens `class << self` to add
+# `credentials` and `with_credentials`, so the module has to exist first.
+require_relative "clowk/credentials"
+
 require_relative "clowk/current"
 require_relative "clowk/http/response"
 require_relative "clowk/http/logger_middleware"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clowk
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Clowk
@@ -107,6 +107,7 @@ files:
 - lib/clowk/controllers/base_controller.rb
 - lib/clowk/controllers/callbacks_controller.rb
 - lib/clowk/controllers/sessions_controller.rb
+- lib/clowk/credentials.rb
 - lib/clowk/current.rb
 - lib/clowk/engine.rb
 - lib/clowk/helpers/url_helpers.rb
@@ -129,7 +130,7 @@ files:
 - lib/clowk/version.rb
 homepage: https://clowk.in
 licenses:
-- AGPL-3.0-only
+- MIT
 metadata:
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -139,7 +140,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.3'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="