permits 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '081bbbbc6f1e3880c891c01fb9f5a046abb33001d2435ee81075ec7b8144c578'
+  data.tar.gz: 48388184153b9ca8f289dd601f4fcef2f1bbc0de669c8a8a28e7f5a47bfca432
+SHA512:
+  metadata.gz: 9bf6cf28caa90ede7b4ccd5fcfbd55f05a466bdb1ebdda4a38d0ce19a00ce046791ff6f81ae9889277abedff29575afc97552175c0e55a513acb8e31bdf20707
+  data.tar.gz: 6381568c986046227947542c0ad02ea305a325198164c861aae46f5f24ad1735de11b38c2bdf7347e095feeea27d4717d6d67e27658528ce2a8c364c5229b73c

data/README.md

@@ -0,0 +1,105 @@
+# Permits
+`Permits` offers an ActiveRecord-based permissions system for Rails applications, with historic records (via `Timelines::Ephemeral`) and a simple DSL for defining permissions and policies.
+
+## Usage
+### Initialization
+Set up the valid `permits` values (roles/actions/levels):
+```ruby
+# config/initializers/permits.rb
+
+# user levels example
+::Permits.configure do |config|
+  config.permits = %i[admin user super_user]
+end
+
+# user actions example
+::Permits.configure do |config|
+  config.actions = %i[read write destroy]
+end
+
+# mixed example
+::Permits.configure do |config|
+  config.roles = %i[admin super_user read write destroy]
+end
+```
+
+### Creating Permission Record
+Create a `Permission` record to track an `Owner's` access to a selected `Resource`, and define the action/level that the `Owner` is permitted to work with the `Resource`:
+
+Give a `User` permission to do `write` to a certain `Resource`:
+```ruby
+Permits::Permission.create(owner: owner, resource: resource, action: :write)
+```
+
+### Checking Permissions with the default Policy
+The `Permits::Policy::Base` class provides two different class methods for authorizing access:
+- `Permits::Policy::Base.authorize!` will raise an `Permits::Policy::UnauthorizedError` if the `Owner` does not have the required permission
+- `Permits::Policy::Base.authorized?` will return `true` if the `Owner` has the required permission, and `false` if not
+
+
+```ruby
+Permits::Permission.create(owner: owner, resource: resource, action: :write)
+
+Permits::Policy::Base.authorize!(owner, resource, :write) # => true
+Permits::Policy::Base.authorize!(owner, resource, :read) # => Permits::Policy::UnauthorizedError
+Permits::Policy::Base.authorize!(owner, other_resource, :write) # => Permits::Policy::UnauthorizedError
+
+Permits::Policy::Base.authorized?(owner, resource, :write) # => true
+Permits::Policy::Base.authorized?(owner, resource, :read) # => false
+Permits::Policy::Base.authorized?(owner, resource, :write) # => false
+```
+
+### Custom Policies
+You can define custom policies by subclassing `Permits::Policy::Base` and defining an `#{action_name}?` method. Furthermore you can still leverage the `has_action_permissions?` method from the `Base` class to perform the check that they have a suitable `Permission` record while also making additional checks (such as checking they are an Admin, or checking that a resource is active/actionable)
+
+```ruby
+# config/initializers/permits.rb
+::Permits.configure do |config|
+  config.roles = %i[some_action]
+end
+
+# app/models/custom_policy.rb
+class CustomPolicy < Permits::Policy::Base
+  def some_action?
+    owner == resource.owner || owner.admin?
+  end
+
+  def some_action_with_level?
+    owner.admin? && has_action_permissions?(:some_action)
+  end
+end
+
+# irb
+Permits::Permission.create(owner: owner, resource: resource, action: :some_action)
+
+CustomPolicy.authorize!(owner, resource, :some_action)
+CustomPolicy.authorized?(owner, resource, :some_action)
+```
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "permits"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install permits
+```
+
+Install the required files to your project:
+```bash
+$ rails generate permits:install
+```
+
+## Contributing
+Contribution directions go here.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,19 @@
+require 'rake'
+
+begin
+  require 'bundler/setup'
+  Bundler::GemHelper.install_tasks
+rescue LoadError
+  puts 'although not required, bundler is recommended for running the tests'
+end
+
+task default: :spec
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new do |task|
+  task.requires << 'rubocop-performance'
+  task.requires << 'rubocop-rspec'
+end

data/lib/generators/permits/install/USAGE

@@ -0,0 +1,2 @@
+Description:
+    Copies the Database migration file to your application's db/migrate directory.

data/lib/generators/permits/install/install_generator.rb

@@ -0,0 +1,11 @@
+module Permits
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_application_policy
+        template "create_permits_permissions.rb", "db/migrate/#{Time.current.strftime("%Y%m%d%H%M%S")}_create_permits_permissions.rb"
+      end
+    end
+  end
+end

data/lib/generators/permits/install/templates/create_permits_permissions.rb

@@ -0,0 +1,18 @@
+class CreatePermitPermissions < ActiveRecord::Migration[7.1]
+  def change
+    create_table :permits_permissions, id: :uuid do |t|
+      t.string :owner_id, null: false
+      t.string :owner_type, null: false
+      t.string :resource_id, null: false
+      t.string :resource_type, null: false
+      t.string :permits, null: false
+
+      t.datetime :started_at
+      t.datetime :ended_at
+      t.timestamps
+    end
+
+    add_index :permits_permissions, [:owner_id, :owner_type]
+    add_index :permits_permissions, [:resource_id, :resource_type]
+  end
+end

data/lib/permits/permission.rb

@@ -0,0 +1,25 @@
+require "timelines"
+
+module Permits
+  class Permission < ActiveRecord::Base
+    self.table_name = "permits_permissions"
+
+    include ::Timelines::Ephemeral
+    attribute :started_at, default: -> { Time.current }
+
+    belongs_to :owner, polymorphic: true, required: true
+    belongs_to :resource, polymorphic: true, required: true
+
+    validates :owner, presence: true
+    validates :resource, presence: true
+    validate :permits_is_permissable
+
+    def permits_is_permissable
+      return if Permits.config.permits&.include?(permits&.to_sym)
+
+      errors.add(:permits, "is not a valid permits for #{resource.class}")
+    end
+
+    scope :permits_any, -> { all }
+  end
+end

data/lib/permits/policy/base.rb

@@ -0,0 +1,51 @@
+module Permits
+  module Policy
+    class Base
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+      include ActiveModel::Validations
+
+      attribute :owner
+      attribute :resource
+
+      validates :owner, presence: true
+      validates :resource, presence: true
+
+      def self.authorize!(owner, resource, action)
+        policy = new(owner: owner, resource: resource)
+        if policy.authorized?(action)
+          true
+        else
+          raise ::Permits::Policy::UnauthorizedError
+        end
+      end
+
+      def self.authorized?(owner, resource, action)
+        policy = new(owner: owner, resource: resource)
+        policy.authorized?(action)
+      end
+
+      def authorized?(action)
+        return false unless valid?
+
+        if respond_to?("#{action}?")
+          return send("#{action}?")
+        else
+          has_action_permissions?(action)
+        end
+      end
+
+      private
+
+      def has_action_permissions?(action)
+        return false unless owner_permissions.respond_to?("permits_#{action}")
+
+        return owner_permissions.send("permits_#{action}").where(resource: resource).exists?
+      end
+
+      def owner_permissions
+        @owner_permissions ||= ::Permits::Permission.active.where(owner: owner).includes(:resource)
+      end
+    end
+  end
+end

data/lib/permits/policy/unauthorized_error.rb

@@ -0,0 +1,6 @@
+module Permits
+  module Policy
+    class UnauthorizedError < StandardError
+    end
+  end
+end

data/lib/permits/railtie.rb

@@ -0,0 +1,4 @@
+module Permits
+  class Railtie < ::Rails::Railtie
+  end
+end

data/lib/permits/version.rb

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

data/lib/permits.rb

@@ -0,0 +1,23 @@
+require "permits/version"
+require "permits/railtie"
+require "permits/permission"
+require "permits/policy/base"
+require "permits/policy/unauthorized_error"
+require "active_support/configurable"
+
+module Permits
+  include ActiveSupport::Configurable
+
+  class << self
+    def configure
+      yield config
+
+      if config.permits
+        config.permits = config.permits.map!(&:to_sym)
+        config.permits.each do |role|
+          ::Permits::Permission.scope "permits_#{role}", -> { where(permits: role) }
+        end
+      end
+    end
+  end
+end

data/lib/tasks/permits_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :permits do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,171 @@
+--- !ruby/object:Gem::Specification
+name: permits
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Craig Gilchrist
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-10-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  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'
+- !ruby/object:Gem::Dependency
+  name: timelines
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+description: Provides access authorization for owners and resources, via a simple
+  Permission ActiveRecord model and a Policy class.
+email:
+- craig.a.gilchrist@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/generators/permits/install/USAGE
+- lib/generators/permits/install/install_generator.rb
+- lib/generators/permits/install/templates/create_permits_permissions.rb
+- lib/permits.rb
+- lib/permits/permission.rb
+- lib/permits/policy/base.rb
+- lib/permits/policy/unauthorized_error.rb
+- lib/permits/railtie.rb
+- lib/permits/version.rb
+- lib/tasks/permits_tasks.rake
+homepage: https://github.com/Craggar/permits
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Craggar/permits
+  source_code_uri: https://github.com/Craggar/permits
+  changelog_uri: https://github.com/Craggar/permits/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: A User and Role management gem for Rails 7
+test_files: []