linger 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 479ee2a71c47fda737a765386fde2dada477256e69c29efe1aa871de5938cdc9
+  data.tar.gz: 6a7b9461429e3a1376a382b35df611695b5b60dd728b9eabfb323f319add8b45
+SHA512:
+  metadata.gz: eb5f3971ad71e12259399aaa71578f02ce8c7a02b3729ae9823ca3c02975e6bba1ca7034ee91b976c372e8ae522dfdcd381072dcf390cdce65fa8e9e6dd2aaa4
+  data.tar.gz: 1d075cb656ffe36736bad93dca30828f70359a0680ee040a2f42a40e396a7361d4441543c47c4d9a594473be75b59a73d8ea16b8626d3e355c30d109ad7c20da

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2022 leastbad
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,49 @@
+# Linger
+
+Linger takes advantage of the [new](https://github.com/stimulusreflex/stimulus_reflex/pull/588) `throw :forbidden` feature in StimulusReflex 3.5 to provide _unopinionated_ authentication security to Reflexes. If you have two tabs open and sign out in one, you should not be able to run Reflexes in the other tab. If you have sessions active on multiple devices, signing out on one should not impact the sessions on the others. These deceptively hard requirements are addressed by creating a composite key in Redis for every uniquely identified session.
+
+Developers can respond to authentication failures by handling Reflexes that arrive in a new `forbidden` state. Forbidden Reflexes are functionally identical to halted Reflexes (eg. `throw :abort`) except that they (conceptually and semantically) represent Reflexes which were not allowed to execute.
+
+You are **strongly advised** to consult the [Lingering Presence](https://github.com/leastbad/lingering_presence) reference application for further details, especially in advance of full documentation.
+
+## Requirements and setup
+
+- StimulusReflex 3.5
+- Redis server 4.0 and Redis Ruby client 4.2
+
+Add the `linger` gem to your `Gemfile`.
+
+Linger makes use of the same shared Redis config that Kredis uses. Just make sure that you have a valid `config/redis/shared.yml` and you're all set. You can learn more on the [Kredis](https://github.com/rails/kredis#setting-ssl-options-on-redis-connections) page.
+
+## Usage
+
+In your Reflex class, create a `before_reflex` callback:
+
+```ruby
+before_reflex :authenticate_connection!
+```
+
+We recommend placing this in the `app/reflexes/application_reflex.rb` class, but you can manually add it to your Reflex classes on an ad-hoc basis.
+
+```ruby
+class ApplicationReflex < StimulusReflex::Reflex
+  before_reflex :authenticate_connection!
+end
+```
+
+You are then responsible for calling `Linger` methods to allow and deny user contexts across all possible cases. You pass in whatever variables are expected, based on your `identified_by` Set that is defined in your `app/channels/application_channel/channel.rb`. The order you provide the identifiers is not important:
+
+```ruby
+# after sign in
+Linger.allow session, current_user
+Linger.deny session
+# after sign out
+Linger.allow session
+Linger.deny session, current_user
+```
+
+Finally, the developer can either terminate Action Cable connections or create a handler for the `reflexForbidden` life-cycle state. You can see that a starting point for customization is presented in `app/javascript/controllers/application_controller.js` where you can see a sample handler for forbidden Reflexes is described. Instead of refreshing the page, you could use a notification library to pop up a toast message, for example.
+
+## Credit and acknowledgements
+
+The structure of this project borrows both layout and code extensively from [Kredis](https://github.com/rails/kredis). Thanks to all of the Kredis contributors for such an excellent tool.

data/lib/install/install.rb

@@ -0,0 +1,6 @@
+yaml_path = Rails.root.join("config/redis/shared.yml")
+unless yaml_path.exist?
+  say "Adding `config/redis/shared.yml`"
+  empty_directory yaml_path.parent.to_s
+  copy_file "#{__dir__}/shared.yml", yaml_path
+end

data/lib/install/shared.yml

@@ -0,0 +1,15 @@
+production: &production
+  url: <%= ENV.fetch("REDIS_URL", "redis://127.0.0.1:6379/0") %>
+  timeout: 1
+
+development: &development
+  url: <%= ENV.fetch("REDIS_URL", "redis://127.0.0.1:6379/0") %>
+  timeout: 1
+
+  # You can also specify host, port, and db instead of url
+  # host: <%= ENV.fetch("REDIS_SHARED_HOST", "127.0.0.1") %>
+  # port: <%= ENV.fetch("REDIS_SHARED_PORT", "6379") %>
+  # db: <%= ENV.fetch("REDIS_SHARED_DB", "11") %>
+
+test:
+  <<: *development

data/lib/linger/authentication.rb

@@ -0,0 +1,11 @@
+module Linger::Authentication
+  extend ActiveSupport::Concern
+
+  def authenticate_connection!
+    identifier_exists = false
+    Linger.instrument :meta, message: "Verifing #{connection.connection_identifier}" do
+      identifier_exists = Linger.redis.exists?(connection.connection_identifier)
+    end
+    throw :forbidden unless identifier_exists
+  end
+end

data/lib/linger/connections.rb

@@ -0,0 +1,26 @@
+require "redis"
+
+module Linger::Connections
+  mattr_accessor :connections, default: {}
+  mattr_accessor :configurator
+  mattr_accessor :connector, default: ->(config) { Redis.new(config) }
+
+  def configured_for(name)
+    connections[name] ||= Linger.instrument :meta, message: "Connected to #{name}" do
+      connector.call configurator.config_for("redis/#{name}")
+    end
+  end
+
+  def clear_all
+    Linger.instrument :meta, message: "Connections all cleared" do
+      connections.each_value do |connection|
+        if Linger.namespace
+          keys = connection.keys("#{Linger.namespace}:*")
+          connection.del keys if keys.any?
+        else
+          connection.flushdb
+        end
+      end
+    end
+  end
+end

data/lib/linger/log_subscriber.rb

@@ -0,0 +1,15 @@
+require "active_support/log_subscriber"
+
+class Linger::LogSubscriber < ActiveSupport::LogSubscriber
+  def meta(event)
+    info formatted_in(MAGENTA, event)
+  end
+
+  private
+
+  def formatted_in(color, event, type: nil)
+    color "  Linger #{type} (#{event.duration.round(1)}ms)  #{event.payload[:message]}", color, true
+  end
+end
+
+Linger::LogSubscriber.attach_to :linger

data/lib/linger/namespace.rb

@@ -0,0 +1,13 @@
+module Linger::Namespace
+  def namespace=(namespace)
+    Thread.current[:linger_namespace] = namespace
+  end
+
+  def namespace
+    Thread.current[:linger_namespace]
+  end
+
+  def namespaced_key(key)
+    namespace ? "#{namespace}:#{key}" : key
+  end
+end

data/lib/linger/railtie.rb

@@ -0,0 +1,33 @@
+class Linger::Railtie < ::Rails::Railtie
+  config.linger = ActiveSupport::OrderedOptions.new
+
+  initializer "linger.testing" do
+    ActiveSupport.on_load(:active_support_test_case) do
+      parallelize_setup { |worker| Linger.namespace = "test-#{worker}" }
+      teardown { Linger.clear_all }
+    end
+  end
+
+  initializer "linger.logger" do
+    Linger::LogSubscriber.logger = config.linger.logger || Rails.logger
+  end
+
+  initializer "linger.configuration" do
+    Linger::Connections.connector = config.linger.connector || ->(config) { Redis.new(config) }
+  end
+
+  initializer "linger.configurator" do
+    Linger.configurator = Rails.application
+  end
+
+  initializer "linger.action_cable" do
+    ActiveSupport.on_load(:action_cable) do
+      StimulusReflex::Reflex.include Linger::Authentication
+    end
+  end
+
+  rake_tasks do
+    path = File.expand_path("..", __dir__)
+    Dir.glob("#{path}/tasks/**/*.rake").each { |f| load f }
+  end
+end

data/lib/linger/version.rb

@@ -0,0 +1,3 @@
+module Linger
+  VERSION = "0.1.0"
+end

data/lib/linger.rb

@@ -0,0 +1,56 @@
+require "active_support"
+
+require "linger/version"
+
+require "linger/connections"
+require "linger/log_subscriber"
+require "linger/namespace"
+require "linger/authentication"
+
+require "linger/railtie" if defined?(Rails::Railtie)
+
+module Linger
+  include Authentication
+  include Namespace
+  include Connections
+  extend self
+
+  mattr_accessor :logger
+
+  def redis(config: :shared)
+    configured_for(config)
+  end
+
+  def allow(*identifiers, **options)
+    key = build_key(identifiers)
+    instrument :meta, message: "Allowing #{key}" do
+      redis.set key, options[:data] || Time.zone.now
+    end
+  end
+
+  def deny(*identifiers)
+    key = build_key(identifiers)
+    instrument :meta, message: "Denying #{key}" do
+      redis.del key
+    end
+  end
+
+  def instrument(channel, **options, &block)
+    ActiveSupport::Notifications.instrument("#{channel}.linger", **options, &block)
+  end
+
+  private
+
+  def build_key(identifiers)
+    Linger.namespaced_key(identifiers.map do |identifier|
+      case identifier
+      when ActionDispatch::Request::Session
+        identifier.id.to_s
+      when Rack::Session::SessionId
+        identifier.to_s
+      else
+        identifier.respond_to?(:to_gid_param) ? identifier.to_gid_param : identifier.to_s
+      end
+    end.sort.join(":"))
+  end
+end

data/lib/tasks/linger/install.rake

@@ -0,0 +1,6 @@
+namespace :linger do
+  desc "Install linger"
+  task :install do
+    system "#{RbConfig.ruby} ./bin/rails app:template LOCATION=#{File.expand_path("../../install/install.rb", __dir__)}"
+  end
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: linger
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- leastbad
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-06-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+description: 
+email: hello@leastbad.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- lib/install/install.rb
+- lib/install/shared.yml
+- lib/linger.rb
+- lib/linger/authentication.rb
+- lib/linger/connections.rb
+- lib/linger/log_subscriber.rb
+- lib/linger/namespace.rb
+- lib/linger/railtie.rb
+- lib/linger/version.rb
+- lib/tasks/linger/install.rake
+homepage: https://github.com/leastbad/linger
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: Provide Devise-style authentication helpers for StimulusReflex
+test_files: []