clowk 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1fa17ef38ffc2cce253e598ab2c2478ba05f5f7c638601ec833bafa00377ebc
-  data.tar.gz: 396b0e5c36dcaa01a10397f6227af24dcdf5274a06145222da54855aba71a076
+  metadata.gz: 6bd80a8d0998a7b4779bb719e51a1d31c394cd53a5ea3a46b56cd2206213a949
+  data.tar.gz: 71846822f9bdf17b29357e55266480d5a352f970cd3aa0b256ffc89599277a73
 SHA512:
-  metadata.gz: 1fd3f7de008dd50644494e85e0771113ae98be1efdc1abcae7d97888b6af84f7aa2f5fd086aa711d3be4b2984b0a626c9bdddc5d66c6c8bc41955b21325c3717
-  data.tar.gz: 36067b774a1d57d833909bcee4316d29a25ee5a907b03063f8ee52545adbf36b09a9857b4b374065a60956f2a5a386044138592b9643e0cf5a7b2f48dec50da8
+  metadata.gz: d5b8fcb5938dc7cb1034a7dae4a2aec1e9dbd36cdc4ad2972f43ec99a22cf66e76779e3de3ce826a38bfd24b5add840732b5e05ae34c9b198f1fe1f506640503
+  data.tar.gz: d7adc93a749be711889b792d20c0c9f7e0d280768a40104d149be7ad71902c90052d562704018bde2ac119b9529e82da3d5aac80813387a50d56550fa96f8441

data/README.md

@@ -274,28 +274,30 @@ Both ends — the broker said inactive, the ceiling passed — go through
 
 ### Where the token is kept
 
-Clowk writes the token to its own cookie, and — by default, as every version
-before 0.9 did — mirrors a copy into the app's Rails session.
+Clowk writes the token to its own cookie. The setting decides one thing: whether
+a copy is **also** mirrored into the host app's Rails session.
 
 ```ruby
-config.token_store = :cookie   # Clowk's cookie only
-config.token_store = :session  # also mirrored into the session (the default)
+config.token_store = nil   # Clowk's own cookie, and nowhere else (the default)
+config.token_store = :app  # also mirrored into the app's Rails session
 ```
 
-The copy is not free. A Rails session lives in **one** cookie with about 4096
-bytes to its name, and in production, where tokens are RS256, the token is most
-of what a session weighs. Hand a browser more than it will hold and it discards
-the whole cookie in silence — no error server-side, none in the console, the
-previous cookie simply stays. Everything written on that request goes with it: a
-flash message, a selected tenant, a CSRF rotation. What a person sees is a button
-that does nothing.
+The copy is not free, which is why `nil` is the default. A Rails session lives in
+**one** cookie with about 4096 bytes to its name, and in production, where tokens
+are RS256, the token is most of what a session weighs. Hand a browser more than
+it will hold and it discards the whole cookie in silence — no error server-side,
+none in the console, the previous cookie simply stays. Everything written on that
+request goes with it: a flash message, a selected tenant, a CSRF rotation. What a
+person sees is a button that does nothing. An app pays that risk on every request
+to keep a copy of a token it already has.
 
-Under `:cookie` the session keeps the claims and the sign-in time, nothing else.
+Under `nil` the session keeps the claims and the sign-in time, nothing else.
 `current_token` reads Clowk's cookie instead, which is where an API-only app has
-always read it from. Sessions written before the switch are pruned on their next
+always read it from. Sessions written before the upgrade are pruned on their next
 request, so an app does not have to wait for everyone to sign out.
 
-The default stays `:session` so an upgrade changes nothing until you ask.
+Ask for `:app` if the app reads the token out of `session[...]` itself rather
+than through `current_token`.
 
 ### Token verification
 

data/lib/clowk/authenticable.rb

@@ -97,9 +97,9 @@ module Clowk
       end
     end
 
-    # The session first, which holds a copy only under token_store :session —
-    # and, for one request after an app switches to :cookie, in a session
-    # written before the switch. drop_mirrored_token! clears those. Clowk's own
+    # The session first, which holds a copy only under token_store :app —
+    # 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.
     def current_token
       stored_session&.dig("token") || extracted_token
@@ -321,7 +321,7 @@ module Clowk
       claims = {user: payload, signed_in_at: Time.now.to_i}
 
       store[Clowk.config.session_key] =
-        (Clowk.config.token_store == :cookie) ? claims : claims.merge(token:)
+        (Clowk.config.token_store == :app) ? claims.merge(token:) : claims
 
       clowk_cookie_jar&.[]=(Clowk.config.cookie_key, {
         value: token,
@@ -331,13 +331,13 @@ module Clowk
       })
     end
 
-    # A session written under :session still carries the token, and
+    # A session written under :app still carries the token, and
     # persist_clowk_session does not run again while that session stands — so
-    # without this, switching an app to :cookie would shrink nothing until every
+    # without this, an app that drops :app would shrink nothing until every
     # person signed out and back in. Drops the copy once, on the first request
-    # after the switch.
+    # after the change.
     def drop_mirrored_token!
-      return unless Clowk.config.token_store == :cookie
+      return if Clowk.config.token_store == :app
 
       store = clowk_session_store
       held = stored_session

data/lib/clowk/configuration.rb

@@ -66,24 +66,26 @@ module Clowk
       # the next request; max_session_age is what bounds that.
       @fail_open_on_broker_error = true
 
-      # Where the token is kept for the next request: :session or :cookie.
+      # Whether the token is ALSO mirrored into the host app's Rails session:
+      # nil for no, :app for yes.
       #
       # Clowk's own cookie is written either way — it is what `current_token`
       # reads when the session has none, and the only place an API-only app has
-      # ever had. The setting decides whether a COPY is also mirrored into the
-      # app's Rails session, as every version before 0.9 did.
+      # ever had. That is why nil is not "nowhere": it is Clowk's cookie alone.
       #
-      # That copy is not free. A Rails session lives in ONE cookie with about
-      # 4096 bytes to its name, and in production, where tokens are RS256, the
-      # token is most of what a session weighs. Hand a browser more than it will
-      # hold and it discards the whole cookie in silence: no error server-side,
-      # none in the console, the previous cookie simply stays. Everything written
-      # on that request goes with it — a flash message, a selected tenant — which
-      # reads as a button that does nothing.
+      # The copy is not free, which is why nil is the default. A Rails session
+      # lives in ONE cookie with about 4096 bytes to its name, and in
+      # production, where tokens are RS256, the token is most of what a session
+      # weighs. Hand a browser more than it will hold and it discards the whole
+      # cookie in silence: no error server-side, none in the console, the
+      # previous cookie simply stays. Everything written on that request goes
+      # with it — a flash message, a selected tenant — which reads as a button
+      # that does nothing. An app pays that risk on every request to keep a copy
+      # of a token it already has.
       #
-      # :session stays the default so an upgrade changes nothing until an app
-      # asks for :cookie.
-      @token_store = :session
+      # :app is there for an app that reads the token out of `session[...]`
+      # itself, rather than through `current_token`.
+      @token_store = nil
     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.9.0"
+  VERSION = "0.10.0"
 end

metadata

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