ActiveSecurity

---

• ⚙️ Ruby >= 2.7, plus JRuby and Truffleruby, but only non-EOL Rubies are officially supported
• ⚙️ Rails >= 7.0 (actually, it only requires activerecord)

	Project	bundle add active_security
1️⃣	name, license, docs, standards
2️⃣	version & activity
3️⃣	maintenance & linting
4️⃣	testing
5️⃣	coverage & security
6️⃣	resources
7️⃣	... 💖	💻 🌏

Install the gem and add to the application's Gemfile by executing:

$ bundle add active_security

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install active_security

All documentation is in the source so check there if the following is not enough.

To use ActiveSecurity in your ActiveRecord models, you must first either extend or include the ActiveSecurity module (it makes no difference), then invoke the {ActiveSecurity::Base#active_security active_security} method to configure your desired options:

class Foo < ActiveRecord::Base
  include ActiveSecurity
  active_security :use => {finders: {default_finders: :restricted}, scoped: {scope: :bar_id}}
end

The most important option is :use, which you use to tell ActiveSecurity which addons it should use. See the documentation for {ActiveSecurity::Base#active_security} for a list of all available addons, or skim through the rest of the docs to get a high-level overview.

A note about single table inheritance (STI): you must extend ActiveSecurity in all classes that participate in STI, both your parent classes and their children.

By default the :restricted plugin is the only one configured, and the restricted scope must be explicitly added to every query. This is the simplest way to use ActiveSecurity. But it is messy, and laborious. It will ensure that finds are executed within a where scope:

class User < ActiveRecord::Base
  extend ActiveSecurity
end

User.restricted.find(1)                       # blows up, because no scope
User.where(name: "Bart").restricted.find(1)   # returns the user

The problem with the above approach is that a naked find (User.find(1)) still works, and is just as insecure as before. The :finders plugin fixes this problem, so you don't need to add restricted everywhere.

class User < ActiveRecord::Base
  extend ActiveSecurity
  active_security use: {finders: {default_finders: :restricted}}
end

User.find(1)                                 # blows up, because no scope
User.where(name: "Bart").find(1)             # returns the user
User.where(name: "Bart").restricted.find(1)  # also returns the user

Here's a basic config.

class Post < ActiveRecord::Base
  extend ActiveSecurity
  active_security use: :finders
end

Now let's get crazy secure!

When given the optional block, this method will yield the class's instance of {ActiveSecurity::Configuration} to the block before evaluating other arguments, so configuration values set in the block may be overwritten by the arguments. This order was chosen to allow passing the same proc to multiple models, while being able to override the values it sets. Here is a contrived example:

$active_security_config_proc = Proc.new do |config|
  config.use :finders
end

class Foo < ActiveRecord::Base
  extend ActiveSecurity
  active_security &$active_security_config_proc
end

class Bar < ActiveRecord::Base
  extend ActiveSecurity
  active_security &$active_security_config_proc
end

However, it's usually better to use {ActiveSecurity.defaults} for this:

ActiveSecurity.defaults do |config|
  config.use :finders, default_finders: :restricted
end

class Foo < ActiveRecord::Base
  extend ActiveSecurity
end

class Bar < ActiveRecord::Base
  extend ActiveSecurity
end

In general you should use the block syntax either because of your personal aesthetic preference, or because you need to share some functionality between multiple models that can't be well encapsulated by {ActiveSecurity.defaults}.

When calling this method without a block, you may set the hash options in any order, so long as they either have no dependencies, or are coupled with their respective module.

Here's an example that configures every plugin:

class Person < ActiveRecord::Base
  active_security use: {
    finders: {default_finders: :restricted},
    scoped: {scope: :name},
    privileged: {}
  }
end

Person.find(1)                                 # blows up, because no scope
Person.where(name: "Bart").find(1)             # returns the person
Person.where(age: 29).find(1)                  # blows up, because name scope wasn't used
Person.where(age: 29).privileged.find(1)       # returns the person, because privileged
Person.where(name: "Bart").restricted.find(1)  # also returns the person, because name scope used

However, when using block-style invocation, be sure to call ActiveSecurity::Configuration's {ActiveSecurity::Configuration#use use} method prior to the associated configuration options, because it will include modules into your class, and these modules in turn may add required configuration options to the @active_security_configuration's class:

class Person < ActiveRecord::Base
  active_security do |config|
    # This will work
    config.use :scoped
    config.scope = "family_id"
  end
end

class Person < ActiveRecord::Base
  active_security do |config|
    # This will fail
    config.scope = "family_id"
    config.use :scoped
  end
end

Because :use can accept a name or a Module, {ActiveSecurity.defaults defaults} can be a convenient place to set up behavior common to all classes using ActiveSecurity. You can include any module, or more conveniently, define one on-the-fly. For example, let's say you want to globally override the error that is raised when no scope is used:

ActiveSecurity.defaults do |config|
  config.use :finders
  config.use Module.new {
    def self.setup(model_class)
      model_class.instance_eval do
        relation.class.send(:prepend, RaiseOverride)
        model_class.singleton_class.send(:prepend, RaiseOverride)
      end

      association_relation_delegate_class = model_class.relation_delegate_class(::ActiveRecord::AssociationRelation)
      association_relation_delegate_class.send(:prepend, RaiseOverride)
    end

    module RaiseOverride
      def raise_if_not_scoped
        puts "My errors are better than yours"
        raise StandardError, "Calm Down"
      end
    end
  }
end

The basic compatibility matrix:

appraisal install
appraisal rake test

Sometimes also:

BUNDLE_GEMFILE=gemfiles/vanilla.gemfile appraisal update

NOTE: This results in bad paths to the gemspec. gemspec path: "../../" needs to be replaced with gemspec path: "../" in each Appraisal gemfile.

Everyone interacting in this project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

This Library adheres to Semantic Versioning 2.0.0. Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions.

To get a better understanding of how SemVer is intended to work over a project's lifetime, read this article from the creator of SemVer:

• "Major Version Numbers are Not Sacred"

As a result of this policy, you can (and should) specify a dependency on these libraries using the Pessimistic Version Constraint with two digits of precision.

For example:

spec.add_dependency("active_security", "~> 1.0")

The gem is available as open source under the terms of the MIT License . See LICENSE.txt for the official Copyright Notice.

• Copyright (c) 2024 Peter H. Boling of Rails Bling