Use app-specific cookie keys for sessions (#189)

* Update docs

* Use app-specific key for sessions

* Add debug logs

* Allow to configure session key

* bump version

Author: rsamoilov

CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [1.19.1] - 2025-12-26
+
+### Changed
+
+- Use app-specific cookie keys for sessions (#189).
+
 ## [1.19.0] - 2025-12-03
 
 ### Added

lib/rage/cable/cable.rb

@@ -1,5 +1,33 @@
 # frozen_string_literal: true
 
+##
+# `Rage::Cable` provides built-in WebSocket support for Rage apps, similar to Action Cable in Rails. It lets you mount a separate WebSocket application, define channels and connections, subscribe clients to named streams, and broadcast messages in real time.
+#
+# Define a channel:
+# ```ruby
+# class ChatChannel < Rage::Cable::Channel
+#   def subscribed
+#     stream_from "chat"
+#   end
+#
+#   def receive(data)
+#     puts "Received message: #{data['message']}"
+#   end
+# end
+# ```
+#
+# Mount the Cable application:
+# ```ruby
+# Rage.routes.draw do
+#   mount Rage::Cable.application, at: "/cable"
+# end
+# ```
+#
+# Broadcast a message to a stream:
+# ```ruby
+# Rage.cable.broadcast("chat", { message: "Hello, world!" })
+# ```
+#
 module Rage::Cable
   # Create a new Cable application.
   #

lib/rage/configuration.rb

@@ -203,6 +203,14 @@ def log_tags
   end
   # @!endgroup
 
+  # @!group Session Configuration
+  # Allows configuring session settings.
+  # @return [Rage::Configuration::Session]
+  def session
+    @session ||= Session.new
+  end
+  # @!endgroup
+
   # @private
   def internal
     @internal ||= Internal.new
@@ -773,6 +781,17 @@ def parse_disk_backend_options(opts)
     end
   end
 
+  class Session
+    # @!attribute key
+    #   Specify the name of the session cookie.
+    #   @return [String]
+    #   @example Change the session cookie name
+    #     Rage.configure do
+    #       config.session.key = "_myapp_session"
+    #     end
+    attr_accessor :key
+  end
+
   # @private
   class Internal
     attr_accessor :rails_mode

lib/rage/cookies.rb

@@ -12,6 +12,92 @@
   ERR
 end
 
+##
+# Cookies provide a convenient way to store small amounts of data on the client side that persists across requests.
+# They are commonly used for session management, personalization, and tracking user preferences.
+#
+# Rage cookies support both simple string-based cookies and encrypted cookies for sensitive data.
+#
+# To use cookies, add the `domain_name` gem to your `Gemfile`:
+#
+# ```bash
+# bundle add domain_name
+# ```
+#
+# Additionally, if you need to use encrypted cookies, see {Session} for setup steps.
+#
+# ## Usage
+#
+# ### Basic Cookies
+#
+# Read and write simple string values:
+#
+# ```ruby
+# # Set a cookie
+# cookies[:user_name] = "Alice"
+#
+# # Read a cookie
+# cookies[:user_name] # => "Alice"
+#
+# # Delete a cookie
+# cookies.delete(:user_name)
+# ```
+#
+# ### Cookie Options
+#
+# Set cookies with additional options for security and control:
+#
+# ```ruby
+# cookies[:user_id] = {
+#   value: "12345",
+#   expires: 1.year.from_now,
+#   secure: true,
+#   httponly: true,
+#   same_site: :lax
+# }
+# ```
+#
+# ### Encrypted Cookies
+#
+# Store sensitive data securely with automatic encryption:
+#
+# ```ruby
+# # Set an encrypted cookie
+# cookies.encrypted[:api_token] = "secret-token"
+#
+# # Read an encrypted cookie
+# cookies.encrypted[:api_token] # => "secret-token"
+#
+# ```
+#
+# ### Permanent Cookies
+#
+# Create cookies that expire 20 years from now:
+#
+# ```ruby
+# cookies.permanent[:remember_token] = "token-value"
+#
+# # Can be combined with encrypted
+# cookies.permanent.encrypted[:user_id] = current_user.id
+# ```
+#
+# ### Domain Configuration
+#
+# Control which domains can access your cookies:
+#
+# ```ruby
+# # Specific domain
+# cookies[:cross_domain] = { value: "data", domain: "example.com" }
+#
+# # All subdomains
+# cookies[:shared] = { value: "data", domain: :all }
+#
+# # Multiple allowed domains
+# cookies[:limited] = { value: "data", domain: ["app.example.com", "api.example.com"] }
+# ```
+#
+# @see Session
+#
 class Rage::Cookies
   # @private
   def initialize(env, headers)
@@ -190,10 +276,13 @@ def load(value)
         begin
           box.decrypt(Base64.urlsafe_decode64(value).byteslice(2..))
         rescue ArgumentError
+          Rage.logger.debug("Failed to decode encrypted cookie")
           nil
         rescue RbNaCl::CryptoError
+          Rage.logger.debug("Failed to decrypt encrypted cookie")
           i ||= 0
           if (box = fallback_boxes[i])
+            Rage.logger.debug("Trying to decrypt with fallback key ##{i + 1}")
             i += 1
             retry
           end

lib/rage/session.rb

@@ -2,9 +2,68 @@
 
 require "json"
 
+##
+# Sessions securely store data between requests using cookies and are typically one of the most convenient and secure
+# authentication mechanisms for browser-based clients.
+#
+# Rage sessions are encrypted using a secret key. This prevents clients from reading or tampering with session data.
+#
+# ## Setup
+#
+# 1. Add the required gems to your `Gemfile`:
+#
+#     ```bash
+#     bundle add base64 domain_name rbnacl
+#     ```
+#
+# 2. Generate a secret key base (keep this value private and out of version control):
+#
+#     ```bash
+#     ruby -r securerandom -e 'puts SecureRandom.hex(64)'
+#     ```
+#
+# 3. Configure your application to use the generated key, either via configuration:
+#
+#     ```ruby
+#     Rage.configure do |config|
+#       config.secret_key_base = "my-secret-key"
+#     end
+#     ```
+#
+#     or via the `SECRET_KEY_BASE` environment variable:
+#
+#     ```bash
+#     export SECRET_KEY_BASE="my-secret-key"
+#     ```
+#
+# ## System Dependencies
+#
+# Rage sessions use libsodium (via RbNaCl) for encryption. On many Debian-based systems
+# it is installed by default; if not, install it with:
+#
+# - Ubuntu / Debian:
+#
+#     ```bash
+#     sudo apt install libsodium23
+#     ```
+#
+# - Fedora / RHEL / Amazon Linux:
+#
+#     ```bash
+#     sudo yum install libsodium
+#     ```
+#
+# - macOS (using Homebrew):
+#
+#     ```bash
+#     brew install libsodium
+#     ```
+#
 class Rage::Session
   # @private
-  KEY = Rack::RACK_SESSION.to_sym
+  def self.key
+    @key ||= Rage.config.session.key&.to_sym || :"_#{Rage.root.basename.to_s.gsub(/\W/, "_").downcase}_session"
+  end
 
   # @private
   def initialize(cookies)
@@ -92,13 +151,15 @@ def write_session(add: nil, remove: nil, clear: nil)
       read_session.clear
     end
 
-    @cookies[KEY] = { httponly: true, same_site: :lax, value: read_session.to_json }
+    @cookies[self.class.key] = { httponly: true, same_site: :lax, value: read_session.to_json }
   end
 
   def read_session
     @session ||= begin
-      JSON.parse(@cookies[KEY] || "{}", symbolize_names: true)
+      session_value = @cookies[self.class.key] || @cookies[Rack::RACK_SESSION.to_sym] || "{}"
+      JSON.parse(session_value, symbolize_names: true)
     rescue JSON::ParserError
+      Rage.logger.debug("Failed to parse session cookie, resetting session")
       {}
     end
   end

lib/rage/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rage
-  VERSION = "1.19.0"
+  VERSION = "1.19.1"
 end

spec/configuration_spec.rb

@@ -421,4 +421,19 @@ def unknown(_) = true
       end
     end
   end
+
+  describe "#session" do
+    subject { described_class.new.session }
+
+    context "#key" do
+      it "returns nil by default" do
+        expect(subject.key).to be_nil
+      end
+
+      it "persists configuration" do
+        subject.key = "_my_test"
+        expect(subject.key).to eq("_my_test")
+      end
+    end
+  end
 end

spec/controller/api/cookies_spec.rb

@@ -74,6 +74,10 @@
         { session: "MDC9exZmtbHuQ0hKQbfuf69gBQE0oER1y0DInAq686395nMYPVRxt0D3W8wt0jjegw1LNu4MSvQf1LSWdw==" }
       end
 
+      before do
+        allow(Rage).to receive(:logger).and_return(double(debug: nil))
+      end
+
       it "correctly decrypts data" do
         expect(subject.cookies.encrypted[:session]).to eq("fallback-test-value")
       end
@@ -82,6 +86,10 @@
     context "with incorrectly encrypted data" do
       let(:cookies) { { session: "MDC9exZmtbHuQ0hK" } }
 
+      before do
+        allow(Rage).to receive(:logger).and_return(double(debug: nil))
+      end
+
       it "return nil" do
         expect(subject.cookies.encrypted[:session]).to be_nil
       end
@@ -90,6 +98,10 @@
     context "with incorrectly base64 encoded data" do
       let(:cookies) { { session: ";;;;;;;" } }
 
+      before do
+        allow(Rage).to receive(:logger).and_return(double(debug: nil))
+      end
+
       it "return nil" do
         expect(subject.cookies.encrypted[:session]).to be_nil
       end