pretendest 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fee5567af38a736c8cae555f4e67af84010934fe0b802a7f1477df325db12cd6
+  data.tar.gz: e49b7269760c28557c031e8725a8776be0072c8052eb0013c00d98db486dcc67
+SHA512:
+  metadata.gz: 8f6c3d405a29ecc8fc625f3a6e37ca6e527d4013d7bd48fc65a95c3ed92b1c7c81f3b6741eb28b921bac0ef9994beb3e02292c9dd7824c527f356c14483b32bf
+  data.tar.gz: 0c5852cba0b01ba96796ec1c1458e21571a6adb6000cd0ea78ddd6f97b89ec93f616a9d780ba2a5fbbe0a7e710837b738254dee64d0d341eaf800a2c3013bc41

data/CHANGELOG.md

@@ -0,0 +1,58 @@
+## 0.6.0 (2025-04-03)
+
+- Dropped support for Ruby < 3.2 and Rails < 7.1
+
+## 0.5.0 (2023-07-02)
+
+- Dropped support for Ruby < 3 and Rails < 6.1
+
+## 0.4.0 (2022-01-10)
+
+- Dropped support for Ruby < 2.6 and Rails < 5.2
+
+## 0.3.4 (2019-01-31)
+
+- Fixed error with Action Cable and eager loading
+
+## 0.3.3 (2018-09-21)
+
+- Added support for Action Cable
+
+## 0.3.2 (2018-01-21)
+
+- Support for Mongoid `BSON::ObjectId` out of the box
+- Fixed issue with impersonated resource caching
+
+## 0.3.1 (2017-06-18)
+
+- Fixed `stack level too deep` error
+
+## 0.3.0 (2017-06-11)
+
+- Fixed compatibility with Clearance
+- Added support for Rails API
+- Added support for custom primary key
+
+## 0.2.1 (2016-07-07)
+
+- Better error message
+
+## 0.2.0 (2016-07-07)
+
+- Fixed error when `current_user` is overridden in `ApplicationController`
+
+## 0.1.0 (2014-06-23)
+
+- Removed need to call `stop_impersonating_user` before signing out
+
+## 0.0.3 (2013-03-09)
+
+- Added security warning
+
+## 0.0.2 (2013-03-09)
+
+- Ensure user is logged in
+
+## 0.0.1 (2013-03-05)
+
+- First release

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013-2025 Andrew Kane
+
+MIT License
+
+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,214 @@
+# Pretender
+
+As an admin, there are times you want to see exactly what another user sees. Meet Pretender.
+
+- Easily switch between users
+- Minimal code changes
+- Plays nicely with Action Cable and auditing tools
+
+:boom: [Rock on](https://www.youtube.com/watch?v=SBjQ9tuuTJQ)
+
+Pretender is flexible and lightweight - less than 100 lines of code :-)
+
+Works with any authentication system - [Devise](https://github.com/plataformatec/devise), [Authlogic](https://github.com/binarylogic/authlogic), and [Sorcery](https://github.com/Sorcery/sorcery) to name a few.
+
+:tangerine: Battle-tested at [Instacart](https://www.instacart.com/opensource)
+
+[![Build Status](https://github.com/enercoop/pretendest/actions/workflows/build.yml/badge.svg)](https://github.com/enercoop/pretendest/actions)
+
+## Pretendest
+
+Pretendest is a friendly fork of [Pretender](https://github.com/ankane/pretender), with a handful of extra features:
+- An `#impersonating_user?` helper,
+- An option to impersonate a resource by another resource (e.g. a Client impersonated by an Employee).
+
+If you don't need those features, the original Pretender gem is perfectly fine.
+Otherwise, `pretendest` is a drop-in replacement for `pretender`.
+
+## Installation
+
+Add this line to your application’s Gemfile:
+
+```ruby
+gem "pretendest"
+```
+
+And add this to your `ApplicationController`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  impersonates :user
+end
+```
+
+## How It Works
+
+Sign in as another user with:
+
+```
+impersonate_user(user)
+```
+
+The `current_user` method now returns the impersonated user.
+
+You can access the true user with:
+
+```
+true_user
+```
+
+And stop impersonating with:
+
+```ruby
+stop_impersonating_user
+```
+
+### Sample Implementation
+
+Create a controller
+
+```ruby
+class UsersController < ApplicationController
+  before_action :require_admin! # your authorization method
+
+  def index
+    @users = User.order(:id)
+  end
+
+  def impersonate
+    user = User.find(params[:id])
+    impersonate_user(user)
+    redirect_to root_path
+  end
+
+  def stop_impersonating
+    stop_impersonating_user
+    redirect_to root_path
+  end
+end
+```
+
+Add routes
+
+```ruby
+resources :users, only: [:index] do
+  post :impersonate, on: :member
+  post :stop_impersonating, on: :collection
+end
+```
+
+Create an index view
+
+```erb
+<ul>
+  <% @users.each do |user| %>
+    <li>Sign in as <%= button_to user.name, impersonate_user_path(user), data: {turbo: false} %></li>
+  <% end %>
+</ul>
+```
+
+And show when someone is signed in as another user in your application layout
+
+```erb
+<% if impersonating_user? %>
+  You (<%= true_user.name %>) are signed in as <%= current_user.name %>
+  <%= button_to "Back to admin", stop_impersonating_users_path, data: {turbo: false} %>
+<% end %>
+```
+
+## Audits
+
+If you keep audit logs with a library like [Audited](https://github.com/collectiveidea/audited), make sure it uses the **true user**.
+
+```ruby
+Audited.current_user_method = :true_user
+```
+
+## Action Cable
+
+And add this to your `ApplicationCable::Connection`:
+
+```ruby
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+    identified_by :current_user, :true_user
+    impersonates :user
+
+    def connect
+      self.current_user = find_verified_user
+      reject_unauthorized_connection unless current_user
+    end
+
+    private
+
+    def find_verified_user
+      env["warden"].user # for Devise
+    end
+  end
+end
+```
+
+The `current_user` method now returns the impersonated user in channels.
+
+## Configuration
+
+Pretendest is super flexible. You can change the names of methods and even impersonate multiple roles at the same time. Here’s the default configuration.
+
+```ruby
+impersonates :user,
+             method: :current_user,
+             with: ->(id) { User.find_by(id: id) }
+```
+
+Mold it to fit your application.
+
+```ruby
+impersonates :account,
+             method: :authenticated_account,
+             with: ->(id) { EnterpriseAccount.find_by(id: id) }
+```
+
+This creates five methods:
+
+```ruby
+true_account
+impersonate_account
+stop_impersonating_account
+impersonating_account? # Pretender Plus addition
+account_impersonator   # Pretender Plus addition
+```
+
+### Impersonating from another role (Pretender Plus addition)
+
+You can impersonate a role from another role. Consider for instance when Employees are allowed to impersonate Clients:
+
+```ruby
+impersonates :client,
+             impersonator: :employee
+```
+
+In that case, when impersonating:
+- `true_client` returns `nil` (because there is no "true" client),
+- `client_impersonator` returns the `current_employee`. 
+
+## History
+
+View the [changelog](https://github.com/enercoop/pretendest/blob/master/CHANGELOG.md)
+
+## Contributing
+
+Everyone is encouraged to help improve this project. Here are a few ways you can help:
+
+- [Report bugs](https://github.com/enercoop/pretendest/issues)
+- Fix bugs and [submit pull requests](https://github.com/enercoop/pretendest/pulls)
+- Write, clarify, or fix documentation
+- Suggest or add new features
+
+To get started with development:
+
+```sh
+git clone https://github.com/enercoop/pretendest.git
+cd pretendest
+bundle install
+bundle exec rake test
+```

data/lib/pretendest/version.rb

@@ -0,0 +1,3 @@
+module Pretendest
+  VERSION = "0.6.0"
+end

data/lib/pretendest.rb

@@ -0,0 +1,92 @@
+# dependencies
+require "active_support"
+
+# modules
+require_relative "pretendest/version"
+
+module Pretendest
+  class Error < StandardError; end
+
+  module Methods
+    def impersonates(scope = :user, opts = {})
+      impersonated_method = opts[:method] || :"current_#{scope}"
+      impersonate_with = opts[:with] || proc { |id|
+        klass = scope.to_s.classify.constantize
+        primary_key = klass.respond_to?(:primary_key) ? klass.primary_key : :id
+        klass.find_by(primary_key => id)
+      }
+      impersonator = opts[:impersonator] || scope
+      impersonator_method = opts[:impersonator_method] || :"current_#{impersonator}"
+      true_method = :"true_#{scope}"
+      session_key = :"impersonated_#{scope}_id"
+      impersonated_var = :"@impersonated_#{scope}"
+      stop_impersonating_method = :"stop_impersonating_#{scope}"
+
+      # define methods
+      if method_defined?(impersonated_method) || private_method_defined?(impersonated_method)
+        alias_method true_method, impersonated_method
+      else
+        sc = superclass
+        define_method true_method do
+          # TODO handle private methods
+          raise Pretendest::Error, "#{impersonated_method} must be defined before the impersonates method" unless sc.method_defined?(impersonated_method)
+          sc.instance_method(impersonated_method).bind(self).call
+        end
+      end
+      helper_method(true_method) if respond_to?(:helper_method)
+
+      define_method impersonated_method do
+        impersonated_resource = instance_variable_get(impersonated_var) if instance_variable_defined?(impersonated_var)
+
+        if !impersonated_resource && request.session[session_key]
+          # only fetch impersonation if user is logged in
+          # this is a safety check (once per request) so
+          # if a user logs out without session being destroyed
+          # or stop_impersonating_user being called,
+          # we can stop the impersonation
+          if send(impersonator_method)
+            impersonated_resource = impersonate_with.call(request.session[session_key])
+            instance_variable_set(impersonated_var, impersonated_resource) if impersonated_resource
+          else
+            # TODO better message
+            warn "[pretendest] Stopping impersonation due to safety check"
+            send(stop_impersonating_method)
+          end
+        end
+
+        impersonated_resource || send(true_method)
+      end
+
+      define_method :"#{scope}_impersonator" do
+        send(impersonator_method)
+      end
+      helper_method("#{scope}_impersonator") if respond_to?(:helper_method)
+
+      define_method :"impersonate_#{scope}" do |resource|
+        raise ArgumentError, "No resource to impersonate" unless resource
+        raise Pretendest::Error, "Must be logged in to impersonate" unless send(impersonator_method)
+
+        instance_variable_set(impersonated_var, resource)
+        # use to_s for Mongoid for BSON::ObjectId
+        request.session[session_key] = resource.id.is_a?(Numeric) ? resource.id : resource.id.to_s
+      end
+
+      define_method stop_impersonating_method do
+        remove_instance_variable(impersonated_var) if instance_variable_defined?(impersonated_var)
+        request.session.delete(session_key)
+      end
+
+      define_method "impersonating_#{scope}?" do
+        send(impersonated_method) != send(true_method)
+      end
+      helper_method("impersonating_#{scope}?") if respond_to?(:helper_method)
+    end
+  end
+end
+
+ActiveSupport.on_load(:action_controller) do
+  extend Pretendest::Methods
+end
+
+# ActiveSupport.on_load(:action_cable) runs too late with Unicorn
+ActionCable::Connection::Base.extend(Pretendest::Methods) if defined?(ActionCable)

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: pretendest
+version: !ruby/object:Gem::Version
+  version: 0.6.0
+platform: ruby
+authors:
+- Pierre de La Morinerie
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+email: kemenaran@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/pretendest.rb
+- lib/pretendest/version.rb
+homepage: https://github.com/enercoop/pretendest
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Log in as another user in Rails - with extra features
+test_files: []