simple_authorize 0.1.0 → 1.0.1

data/README.md

@@ -1,32 +1,44 @@
 # SimpleAuthorize
 
-[![Gem Version](https://badge.fury.io/rb/simple_authorize.svg)](https://badge.fury.io/rb/simple_authorize)
+[![Gem Version](https://img.shields.io/gem/v/simple_authorize.svg)](https://rubygems.org/gems/simple_authorize)
 [![Ruby](https://github.com/scottlaplant/simple_authorize/workflows/Ruby/badge.svg)](https://github.com/scottlaplant/simple_authorize/actions)
+[![Downloads](https://img.shields.io/gem/dt/simple_authorize.svg)](https://rubygems.org/gems/simple_authorize)
 
 SimpleAuthorize is a lightweight, powerful authorization framework for Rails that provides policy-based access control without external dependencies. Inspired by Pundit, it offers a clean API for managing permissions in your Rails applications.
 
 ## Features
 
-- 🔒 **Policy-Based Authorization** - Define authorization rules in dedicated policy classes
-- 🎯 **Scope Filtering** - Automatically filter collections based on user permissions
-- 🔑 **Role-Based Access** - Built-in support for role-based authorization
-- 🚀 **Zero Dependencies** - No external gems required (only Rails)
-- ✅ **Strong Parameters Integration** - Automatically build permitted params from policies
-- 🧪 **Test Friendly** - Easy to test policies in isolation
-- 📝 **Rails Generators** - Quickly scaffold policies for your models
+- **Policy-Based Authorization** - Define authorization rules in dedicated policy classes
+- **Scope Filtering** - Automatically filter collections based on user permissions
+- **Role-Based Access** - Built-in support for role-based authorization
+- **Zero Dependencies** - No external gems required (only Rails)
+- **Strong Parameters Integration** - Automatically build permitted params from policies
+- **Test Friendly** - Easy to test policies in isolation
+- **Rails Generators** - Quickly scaffold policies for your models
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Install the gem directly:
+
+```bash
+gem install simple_authorize
+```
+
+Or add this line to your application's Gemfile:
 
 ```ruby
 gem 'simple_authorize'
 ```
 
-And then execute:
+Then execute:
 
 ```bash
 bundle install
+```
+
+After installation, run the generator to set up your application:
+
+```bash
 rails generate simple_authorize:install
 ```
 
@@ -47,7 +59,17 @@ end
 
 ### 2. Create a Policy
 
-Create a policy class for your model in `app/policies/`:
+Generate a policy for your model using the generator:
+
+```bash
+rails generate simple_authorize:policy Post
+```
+
+This creates:
+- `app/policies/post_policy.rb` - Policy class with CRUD methods
+- `test/policies/post_policy_test.rb` - Test file (or spec file with `--spec`)
+
+Or create a policy class manually in `app/policies/`:
 
 ```ruby
 # app/policies/post_policy.rb
@@ -197,6 +219,181 @@ def post_params
 end
 ```
 
+## Generators
+
+SimpleAuthorize provides Rails generators to quickly scaffold policies:
+
+### Install Generator
+
+```bash
+rails generate simple_authorize:install
+```
+
+Creates:
+- `config/initializers/simple_authorize.rb` - Configuration file
+- `app/policies/application_policy.rb` - Base policy class
+
+### Policy Generator
+
+```bash
+rails generate simple_authorize:policy Post
+```
+
+Creates:
+- `app/policies/post_policy.rb` - Policy with CRUD methods and scope
+- `test/policies/post_policy_test.rb` - Minitest tests
+
+**Options:**
+- `--spec` - Generate RSpec tests instead of Minitest
+- `--skip-test` - Skip test file generation
+
+**Examples:**
+
+```bash
+# Generate policy with RSpec tests
+rails generate simple_authorize:policy Post --spec
+
+# Generate policy without tests
+rails generate simple_authorize:policy Post --skip-test
+
+# Generate namespaced policy
+rails generate simple_authorize:policy Admin::Post
+```
+
+## Configuration
+
+SimpleAuthorize can be configured in `config/initializers/simple_authorize.rb`:
+
+### Policy Caching
+
+Enable policy caching to improve performance by caching policy instances per request:
+
+```ruby
+SimpleAuthorize.configure do |config|
+  config.enable_policy_cache = true
+end
+```
+
+**How it works:**
+- Policy instances are cached for the duration of a single request
+- Cache is automatically scoped by user, record, and policy class
+- Each unique combination gets its own cached instance
+- Cache is automatically cleared between requests
+- Particularly useful in views where the same policy may be checked multiple times
+
+**Example performance impact:**
+
+```erb
+<!-- Without caching: Creates 3 separate PostPolicy instances -->
+<% if policy(@post).update? %>
+  <%= link_to "Edit", edit_post_path(@post) %>
+<% end %>
+<% if policy(@post).destroy? %>
+  <%= link_to "Delete", post_path(@post) %>
+<% end %>
+<% if policy(@post).publish? %>
+  <%= link_to "Publish", publish_post_path(@post) %>
+<% end %>
+
+<!-- With caching: Reuses the same PostPolicy instance -->
+```
+
+**Testing:**
+Use `clear_policy_cache` or `reset_authorization` to clear the cache in tests:
+
+```ruby
+test "multiple checks use cached policy" do
+  SimpleAuthorize.configure { |config| config.enable_policy_cache = true }
+
+  policy1 = policy(@post)
+  policy2 = policy(@post)
+  assert_same policy1, policy2  # Same instance
+
+  clear_policy_cache
+  policy3 = policy(@post)
+  refute_same policy1, policy3  # New instance after clearing
+end
+```
+
+### Instrumentation & Audit Logging
+
+SimpleAuthorize emits `ActiveSupport::Notifications` events for all authorization checks, perfect for security auditing, debugging, and monitoring:
+
+```ruby
+# Subscribe to authorization events
+ActiveSupport::Notifications.subscribe("authorize.simple_authorize") do |name, start, finish, id, payload|
+  duration = finish - start
+
+  Rails.logger.info({
+    event: "authorization",
+    user_id: payload[:user_id],
+    action: payload[:query],
+    resource: "#{payload[:record_class]}##{payload[:record_id]}",
+    authorized: payload[:authorized],
+    duration_ms: (duration * 1000).round(2)
+  }.to_json)
+end
+
+# Subscribe to policy scope events
+ActiveSupport::Notifications.subscribe("policy_scope.simple_authorize") do |name, start, finish, id, payload|
+  Rails.logger.info("Policy scope applied for #{payload[:scope]} by user #{payload[:user_id]}")
+end
+```
+
+**Event Payloads:**
+
+Authorization events (`authorize.simple_authorize`):
+- `user`: Current user object
+- `user_id`: User ID
+- `record`: The record being authorized
+- `record_id`: Record ID
+- `record_class`: Record class name
+- `query`: Authorization method called (e.g., "update?")
+- `policy_class`: Policy class used
+- `authorized`: Boolean result
+- `error`: Exception if authorization failed
+- `controller`: Controller name (if available)
+- `action`: Action name (if available)
+
+Policy scope events (`policy_scope.simple_authorize`):
+- `user`: Current user object
+- `user_id`: User ID
+- `scope`: The scope being filtered
+- `policy_scope_class`: Scope class used
+- `error`: Exception if scope failed
+- `controller`: Controller name (if available)
+- `action`: Action name (if available)
+
+**Use Cases:**
+- Security auditing and compliance
+- Debugging authorization issues
+- Monitoring authorization performance
+- Sending failed authorization attempts to security services
+- Tracking which users access sensitive resources
+
+**Disable instrumentation** (if needed for performance in specific scenarios):
+
+```ruby
+SimpleAuthorize.configure do |config|
+  config.enable_instrumentation = false
+end
+```
+
+### Other Configuration Options
+
+```ruby
+SimpleAuthorize.configure do |config|
+  # Custom error message for unauthorized access
+  config.default_error_message = "Access denied!"
+
+  # Custom redirect path for unauthorized users
+  config.unauthorized_redirect_path = "/access-denied"
+
+  # Custom method to get current user (default: current_user)
+  config.current_user_method = :authenticated_user
+end
+```
+
 ## Advanced Features
 
 ### Headless Policies
@@ -284,7 +481,7 @@ end
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Comparison with Pundit
 
@@ -316,6 +513,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Credits
 
-Created by Scott LaPlant
-
-Inspired by [Pundit](https://github.com/varvet/pundit) by Elabs
+SimpleAuthorize is heavily inspired by [Pundit](https://github.com/varvet/pundit) by Elabs. We're grateful to the Pundit team for pioneering this authorization pattern.

data/SECURITY.md

@@ -0,0 +1,77 @@
+# Security Policy
+
+## Supported Versions
+
+We release patches for security vulnerabilities. Currently supported versions:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.0.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+We take the security of SimpleAuthorize seriously. If you discover a security vulnerability, please report it privately.
+
+### How to Report
+
+**Please DO NOT open a public GitHub issue for security vulnerabilities.**
+
+Please report security vulnerabilities to: **simpleauthorize@gmail.com**
+
+Alternatively, you can use GitHub's private vulnerability reporting feature (see "Security" tab in the repository).
+
+### What to Include
+
+Please include the following information in your report:
+
+- Type of vulnerability (e.g., authorization bypass, XSS, injection)
+- Full paths of source files related to the vulnerability
+- The location of the affected source code (tag/branch/commit or direct URL)
+- Step-by-step instructions to reproduce the issue
+- Proof-of-concept or exploit code (if possible)
+- Impact of the issue, including how an attacker might exploit it
+
+### Response Timeline
+
+- **Initial Response**: Within 48 hours of receiving your report
+- **Status Update**: Within 5 business days with an initial assessment
+- **Fix Timeline**: Critical vulnerabilities will be addressed within 30 days
+- **Disclosure**: We will coordinate with you on the disclosure timeline
+
+### Security Update Process
+
+1. We will confirm the vulnerability and determine its severity
+2. We will develop and test a fix
+3. We will release a new version with the security patch
+4. We will publish a security advisory with details after the fix is released
+5. We will credit you for the discovery (unless you prefer to remain anonymous)
+
+## Security Best Practices
+
+When using SimpleAuthorize in your application:
+
+1. **Always verify authorization**: Use `verify_authorized` in controllers to ensure authorization is checked
+2. **Secure policy defaults**: The default Policy class denies all actions - only permit what's necessary
+3. **Test your policies**: Write comprehensive tests for all authorization logic
+4. **Keep updated**: Regularly update to the latest version to get security patches
+5. **Review policies**: Periodically audit your policy classes for authorization holes
+
+## Known Security Considerations
+
+### Authorization Bypass Prevention
+
+- Always call `authorize` before performing sensitive actions
+- Use `skip_authorization` explicitly and only when intentional
+- Be careful with `headless_policy` - ensure proper authorization for non-resource actions
+
+### Scope Security
+
+- Always use `policy_scope` to filter collections
+- Don't rely solely on view-level hiding - enforce at the data layer
+- Test scope filtering with different user roles
+
+## Dependencies
+
+SimpleAuthorize has minimal dependencies (only Rails/ActiveSupport). We monitor our dependencies for security vulnerabilities and update promptly.
+

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

@@ -4,6 +4,7 @@ require "rails/generators"
 
 module SimpleAuthorize
   module Generators
+    # Rails generator to install SimpleAuthorize configuration and base policy
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 

data/lib/generators/simple_authorize/install/templates/simple_authorize.rb

@@ -13,4 +13,12 @@ SimpleAuthorize.configure do |config|
 
   # Custom redirect path for unauthorized access (default: uses referrer or root_path)
   # config.unauthorized_redirect_path = "/unauthorized"
+
+  # Enable policy caching for performance optimization (default: false)
+  # When enabled, policy instances are cached per request, scoped by user, record, and policy class
+  # config.enable_policy_cache = true
+
+  # Enable instrumentation for authorization events (default: true)
+  # When enabled, emits ActiveSupport::Notifications events for all authorization checks
+  # config.enable_instrumentation = true
 end

data/lib/generators/simple_authorize/policy/policy_generator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module SimpleAuthorize
+  module Generators
+    # Rails generator to create a policy class for a model
+    class PolicyGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a SimpleAuthorize policy class for a model"
+
+      argument :name, type: :string, required: true, banner: "ModelName"
+
+      class_option :spec, type: :boolean, default: false, desc: "Generate RSpec test file instead of Minitest"
+      class_option :skip_test, type: :boolean, default: false, desc: "Skip generating test file"
+
+      def create_policy_file
+        template "policy.rb.tt", File.join("app/policies", class_path, "#{file_name}_policy.rb")
+      end
+
+      def create_test_file
+        return if options[:skip_test]
+
+        if options[:spec]
+          template "policy_spec.rb.tt", File.join("spec/policies", class_path, "#{file_name}_policy_spec.rb")
+        else
+          template "policy_test.rb.tt", File.join("test/policies", class_path, "#{file_name}_policy_test.rb")
+        end
+      end
+
+      private
+
+      def policy_class_name
+        "#{class_name}Policy"
+      end
+
+      def model_class_name
+        class_name
+      end
+
+      def model_instance_name
+        file_name
+      end
+
+      def namespaced_policy_class
+        if class_path.empty?
+          policy_class_name
+        else
+          "#{class_path.map(&:camelize).join("::")}::#{policy_class_name}"
+        end
+      end
+    end
+  end
+end

data/lib/generators/simple_authorize/policy/templates/policy.rb.tt

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+<% if class_path.any? -%>
+module <%= class_path.map(&:camelize).join('::') %>
+<% end -%>
+  class <%= policy_class_name %> < ApplicationPolicy
+    def index?
+      false
+    end
+
+    def show?
+      false
+    end
+
+    def create?
+      false
+    end
+
+    def update?
+      false
+    end
+
+    def destroy?
+      false
+    end
+
+    def permitted_attributes
+      []
+    end
+
+    class Scope < ApplicationPolicy::Scope
+      def resolve
+        scope.all
+      end
+    end
+  end
+<% if class_path.any? -%>
+end
+<% end -%>

data/lib/generators/simple_authorize/policy/templates/policy_spec.rb.tt

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+<% if class_path.any? -%>
+module <%= class_path.map(&:camelize).join('::') %>
+<% end -%>
+  RSpec.describe <%= policy_class_name %>, type: :policy do
+    subject(:policy) { described_class.new(user, <%= model_instance_name %>) }
+
+    let(:user) { User.new }
+    let(:<%= model_instance_name %>) { <%= model_class_name %>.new }
+
+    describe "#index?" do
+      it "denies access by default" do
+        expect(policy).not_to permit_action(:index)
+      end
+
+      # TODO: Add your authorization logic tests
+    end
+
+    describe "#show?" do
+      it "denies access by default" do
+        expect(policy).not_to permit_action(:show)
+      end
+
+      # TODO: Add your authorization logic tests
+    end
+
+    describe "#create?" do
+      it "denies access by default" do
+        expect(policy).not_to permit_action(:create)
+      end
+
+      # TODO: Add your authorization logic tests
+    end
+
+    describe "#update?" do
+      it "denies access by default" do
+        expect(policy).not_to permit_action(:update)
+      end
+
+      # TODO: Add your authorization logic tests
+    end
+
+    describe "#destroy?" do
+      it "denies access by default" do
+        expect(policy).not_to permit_action(:destroy)
+      end
+
+      # TODO: Add your authorization logic tests
+    end
+
+    describe "#permitted_attributes" do
+      it "returns empty array by default" do
+        expect(policy.permitted_attributes).to eq([])
+      end
+
+      # TODO: Add your permitted attributes tests
+    end
+
+    describe "Scope" do
+      subject(:scope) { <%= namespaced_policy_class %>::Scope.new(user, <%= model_class_name %>.all) }
+
+      it "returns all records by default" do
+        # TODO: Add your scope tests
+        expect(scope.resolve).to eq(<%= model_class_name %>.all)
+      end
+    end
+  end
+<% if class_path.any? -%>
+end
+<% end -%>

data/lib/generators/simple_authorize/policy/templates/policy_test.rb.tt

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+<% if class_path.any? -%>
+module <%= class_path.map(&:camelize).join('::') %>
+<% end -%>
+  class <%= policy_class_name %>Test < ActiveSupport::TestCase
+    def setup
+      @user = User.new
+      @<%= model_instance_name %> = <%= model_class_name %>.new
+    end
+
+    test "index?" do
+      policy = <%= namespaced_policy_class %>.new(@user, @<%= model_instance_name %>)
+
+      # TODO: Add your authorization logic tests
+      refute policy.index?
+    end
+
+    test "show?" do
+      policy = <%= namespaced_policy_class %>.new(@user, @<%= model_instance_name %>)
+
+      # TODO: Add your authorization logic tests
+      refute policy.show?
+    end
+
+    test "create?" do
+      policy = <%= namespaced_policy_class %>.new(@user, @<%= model_instance_name %>)
+
+      # TODO: Add your authorization logic tests
+      refute policy.create?
+    end
+
+    test "update?" do
+      policy = <%= namespaced_policy_class %>.new(@user, @<%= model_instance_name %>)
+
+      # TODO: Add your authorization logic tests
+      refute policy.update?
+    end
+
+    test "destroy?" do
+      policy = <%= namespaced_policy_class %>.new(@user, @<%= model_instance_name %>)
+
+      # TODO: Add your authorization logic tests
+      refute policy.destroy?
+    end
+
+    test "scope" do
+      # TODO: Add your scope tests
+      # For example:
+      # scope = <%= namespaced_policy_class %>::Scope.new(@user, <%= model_class_name %>.all)
+      # assert_equal expected_records, scope.resolve
+    end
+
+    test "permitted_attributes" do
+      policy = <%= namespaced_policy_class %>.new(@user, @<%= model_instance_name %>)
+
+      # TODO: Add your permitted attributes tests
+      assert_equal [], policy.permitted_attributes
+    end
+  end
+<% if class_path.any? -%>
+end
+<% end -%>

data/lib/simple_authorize/configuration.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SimpleAuthorize
+  # Configuration options for SimpleAuthorize
   class Configuration
     # Default error message shown to users when not authorized
     attr_accessor :default_error_message
@@ -14,11 +15,31 @@ module SimpleAuthorize
     # Custom redirect path for unauthorized access
     attr_accessor :unauthorized_redirect_path
 
+    # Enable policy caching for performance optimization (opt-in)
+    attr_accessor :enable_policy_cache
+
+    # Enable instrumentation for authorization events (default: true)
+    attr_accessor :enable_instrumentation
+
+    # Include detailed error information in API responses (default: false)
+    attr_accessor :api_error_details
+
+    # Enable I18n support for error messages (default: false)
+    attr_accessor :i18n_enabled
+
+    # I18n scope for translations (default: 'simple_authorize')
+    attr_accessor :i18n_scope
+
     def initialize
       @default_error_message = "You are not authorized to perform this action."
       @auto_verify = false
       @current_user_method = :current_user
       @unauthorized_redirect_path = nil
+      @enable_policy_cache = false
+      @enable_instrumentation = true
+      @api_error_details = false
+      @i18n_enabled = false
+      @i18n_scope = "simple_authorize"
     end
   end