hubbado-policy 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8338406be7ea8412d5c7d81fee557858ac5327d9f84ef048a662b04f381dcb41
+  data.tar.gz: 4f58a42ba93883f48735ab220f9ff8047f360b41ea9d0a6e35c8c21c9a78318e
+SHA512:
+  metadata.gz: 4e084a506c028722b36741f9d93f0f0cf6385d04c8aedbab34b3053eaaeb804e5734bc93466351f2c4ecfe486ea5763ba6f5ed2700877fbeb445a828eb61e1b2
+  data.tar.gz: 48fc0f6b56cd3dc53da3bc79e73fb9ba41bd35795e3e9da0b3e8b9d82164aafa07cb656047debfb8bcd067ca916b5b84e0e3012cb0bc1497d051ff23d870f480

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.1] - 2025-05-20
+
+Bump because rubygems does not allow repushing the same version even if it is yanked.
+
+## [1.0.0] - 2025-05-20
+
+### Added
+- Initial release of the hubbado-policy gem
+- `Policy` class with DSL for defining authorization rules
+- `Result` class to represent policy outcomes
+- `Scope` class for filtering collections based on permissions
+- Testing support with `Substitute` module for scopes
+- Rails integration via Railtie
+- Full compatibility with the eventide-project/dependency gem
+
+### Documentation
+- Comprehensive README with usage examples
+- Detailed explanations of all major components
+- Rails integration guide
+- Testing instructions and examples

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hubbado
+
+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,404 @@
+# Hubbado Policy
+
+A lightweight, flexible policy framework for Ruby applications that helps you implement authorization logic in a consistent way.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hubbado-policy'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install hubbado-policy
+```
+
+## Overview
+
+Hubbado Policy provides three main components:
+
+1. **Policy** - Defines authorization rules
+2. **Result** - Represents the outcome of policy checks
+3. **Scope** - Filters collections based on authorization rules
+
+## Policy Objects
+
+Policy objects encapsulate authorization logic and determine whether certain actions are permitted for a given user and record combination.
+
+### Basic Usage
+
+```ruby
+class ArticlePolicy < Hubbado::Policy::Base
+  define_policy :view do
+    return permitted if user.admin?
+    
+    if record.published?
+      permitted 
+    else
+      denied(:not_published)
+    end
+  end
+  
+  define_policy :edit do
+    return permitted if user.admin?
+    
+    if record.author == user
+      permitted
+    else
+      denied(:not_author)
+    end
+  end
+end
+
+# Usage
+policy = ArticlePolicy.build(current_user, article)
+
+# Check permissions
+if policy.view?
+  # User can view the article
+end
+
+# Get detailed result object
+result = policy.edit
+if result.permitted?
+  # User can edit
+else
+  # Show error message
+  flash[:error] = result.message
+end
+```
+
+### Policy DSL
+
+The `define_policy` method creates three methods for each policy rule:
+
+1. The base method (e.g., `edit`) that returns a `Result` object
+2. A predicate method (e.g., `edit?`) that returns a boolean
+3. An underlying implementation method
+
+The policy methods support using `return` statements within the block. If a policy method returns `nil` or doesn't explicitly return a `permitted` or `denied` result, it will automatically default to a generic `denied` result. This simplifies policy implementations by not requiring explicit denials for all paths.
+
+```ruby
+define_policy :publish do
+  # Early returns work fine
+  return permitted if user.admin?
+  return denied(:not_verified) unless user.verified?
+
+  # If this evaluates to nil, it automatically becomes a generic denial
+  permitted if record.draft? && record.author == user
+
+  # Reaching the end of the method without returning a result
+  # will also produce a generic denial
+end
+```
+
+### Policy Results
+
+Every policy check returns a `Result` object, which can be either permitted or denied with a specific reason.
+
+```ruby
+# Allow access
+permitted
+
+# Deny access with a reason code
+denied(:not_author)
+
+# Deny with additional data
+denied(:quota_exceeded, data: { limit: 10, usage: 12 })
+```
+
+### Internationalization
+
+Hubbado Policy integrates with I18n for translating error messages:
+
+```ruby
+# config/locales/en.yml
+en:
+  article_policy:
+    not_published: "This article hasn't been published yet"
+    not_author: "Only the author can edit this article"
+  hubbado_policy:
+    errors:
+      denied: "Access denied"
+```
+
+## Result Objects
+
+Result objects represent the outcome of a policy check, containing:
+
+- Permission status (permitted or denied)
+- Reason code for denial
+- Optional additional data
+- I18n integration for error messages
+
+### Usage
+
+```ruby
+result = ArticlePolicy.build(current_user, article).view
+
+if result.permitted?
+  # Proceed with action
+elsif result.denied?
+  # Handle denial
+  error_message = result.message  # Automatically translated
+  additional_data = result.data   # Any extra context provided
+end
+```
+
+### Built-in Methods
+
+- `permitted?` - Returns true if access is allowed
+- `denied?` - Returns true if access is denied
+- `generic_deny?` - Returns true if using the default denial reason
+- `message` - Returns the localized error message
+- `data` - Returns any additional context data
+
+## Scope Objects
+
+Scope objects filter collections based on what a user is authorized to access.
+
+### Basic Usage
+
+```ruby
+class ArticleScope < Hubbado::Policy::Scope
+  def self.default_scope
+    Article.all
+  end
+  
+  def resolve(record, scope, **options)
+    return scope if record.admin?
+    
+    scope.where(published: true).or(scope.where(author_id: record.id))
+  end
+end
+
+# Usage
+visible_articles = ArticleScope.call(current_user)
+```
+
+### Custom Scopes
+
+You can pass custom base scopes:
+
+```ruby
+# Scope only to a specific category
+category_articles = ArticleScope.call(
+  current_user, 
+  Article.where(category_id: params[:category_id])
+)
+
+# Pass additional options
+recent_articles = ArticleScope.call(
+  current_user,
+  Article.all,
+  only_recent: true
+)
+```
+
+### Testing with Substitutes
+
+Scope objects include a Substitute module for testing:
+
+```ruby
+# In your tests
+scope = ArticleScope.new
+scope.extend(Hubbado::Policy::Scope::Substitute)
+scope.result = [article1, article2]
+
+# Now you can assert the scope was called with expected arguments
+scope.call(user)
+assert scope.scoped?(user)
+```
+
+### Using with Eventide Dependency
+
+Hubbado Policy is designed to work seamlessly with the [eventide-project/dependency](https://github.com/eventide-project/dependency) gem. Creating substitutes for testing is as simple as:
+
+```ruby
+# Create a substitute instance of ArticleScope
+article_scope = Dependency::Substitute.build(ArticleScope)
+
+# Configure the result
+article_scope.result = [article1, article2]
+
+# Use in tests
+service = SomeService.new
+service.article_scope = article_scope
+
+# Run the service
+result = service.list_articles(user)
+
+# Verify the scope was called with expected arguments
+assert article_scope.scoped?(user)
+```
+
+This approach makes testing with substitutes straightforward while maintaining all the benefits of dependency injection.
+
+## Dependency Configuration
+
+Policy and Scope objects support the `configure` instance method that can be defined in a subclass. This method is called when the object is initialized and is intended to be used for configuring dependencies.
+
+### Basic Configuration
+
+```ruby
+class ComplexPolicy < HubbadoPolicy::Policy
+  attr_reader :permission_service
+
+  def configure
+    @permission_service = PermissionService.new
+  end
+
+  define_policy :complex_rule do
+    if permission_service.check_permission(user, record)
+      permitted
+    else
+      denied(:no_permission)
+    end
+  end
+end
+```
+
+### Integration with Eventide Dependency
+
+Hubbado Policy is designed to work seamlessly with the [eventide-project/dependency](https://github.com/eventide-project/dependency) gem for dependency management. This provides a powerful way to handle service dependencies in your policies and scopes.
+
+```ruby
+# First, set up your dependencies
+require 'dependency'; Dependency.activate
+require 'hubbado-policy'
+
+class Services
+  dependency :permission_service, PermissionService
+  dependency :audit_logger, AuditLogger
+end
+
+# Then use them in your policy
+class ArticlePolicy < HubbadoPolicy::Policy
+  dependency :permission_service, PermissionService
+  dependency :audit_logger, AuditLogger
+
+  def configure
+    Services.configure(self)
+  end
+
+  define_policy :publish do
+    # Log the attempt
+    audit_logger.log_action("publish_attempt", user: user, record: record)
+
+    # Check permissions
+    if permission_service.can_publish?(user, record)
+      permitted
+    else
+      denied(:cannot_publish)
+    end
+  end
+end
+```
+
+### Benefits of Using Dependency
+
+Using the `dependency` gem with Hubbado Policy offers several advantages:
+
+1. **Clear dependency declaration** - Dependencies are explicitly declared at the class level
+2. **Consistent initialization** - The `configure` method provides a standard place for setting up dependencies
+3. **Testability** - Dependencies can be easily substituted in tests
+4. **Service reuse** - Common services can be configured once and reused across policies and scopes
+
+### Using Dependency with Scopes
+
+The same pattern works for Scope objects:
+
+```ruby
+class ArticleScope < HubbadoPolicy::Scope
+  include Dependency
+
+  dependency :visibility_service, VisibilityService
+
+  def configure
+    Services.configure(self)
+  end
+
+  def self.default_scope
+    Article.all
+  end
+
+  def resolve(record, scope, **options)
+    visibility_service.filter_visible_for(record, scope, **options)
+  end
+end
+```
+
+## Rails Integration
+
+Hubbado Policy includes built-in Rails integration through a Railtie that automatically loads the necessary components and configurations.
+
+### Automatic Loading
+
+When used with Rails, the gem automatically loads its default locale file:
+
+```ruby
+# lib/hubbado/policy/railtie.rb
+module Hubbado
+  module Policy
+    class Railtie < ::Rails::Railtie
+      I18n.load_path << File.expand_path("../../../../config/locales/en.yml", __FILE__)
+    end
+  end
+end
+```
+
+The Railtie is loaded automatically when Rails is detected:
+
+```ruby
+# lib/hubbado-policy.rb
+require "hubbado/policy/railtie" if defined?(Rails::Railtie)
+```
+
+### Recommended Rails Setup
+
+For Rails applications, we recommend organizing your policies in the `app/policies` directory:
+
+```
+app/
+  ├── policies/
+  │   ├── application_policy.rb
+  │   ├── article_policy.rb
+  │   └── user_policy.rb
+  ├── scopes/
+  │   ├── article_scope.rb
+  │   └── user_scope.rb
+  ├── controllers/
+  ├── models/
+  └── ...
+```
+
+You may want to create a base `ApplicationPolicy` that all your policies inherit from:
+
+```ruby
+# app/policies/application_policy.rb
+class ApplicationPolicy < Hubbado::Policy::Base
+  # Common methods for all policies
+end
+```
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/config/locales/en.yml

@@ -0,0 +1,4 @@
+en:
+  hubbado_policy:
+    errors:
+      denied: error denied message

data/hubbado-policy.gemspec

@@ -0,0 +1,35 @@
+Gem::Specification.new do |s|
+  s.name = "hubbado-policy"
+  s.version = "1.0.1"
+  s.summary = "A lightweight, flexible policy framework for Ruby applications"
+
+  s.authors = ["Hubbado Devs"]
+  s.email = ["devs@hubbado.com"]
+  s.homepage = 'https://github.com/hubbado/hubbado-policy'
+  s.license  = "MIT"
+
+  s.metadata["homepage_uri"] = s.homepage
+  s.metadata["source_code_uri"] = s.homepage
+  s.metadata["changelog_uri"] = "#{s.homepage}/blob/master/CHANGELOG.md"
+
+  s.require_paths = ["lib"]
+  s.files = Dir.glob(%w[
+    lib/**/*.rb
+    config/**/*.yml
+    *.gemspec
+    LICENSE*
+    README*
+    CHANGELOG*
+  ])
+  s.platform = Gem::Platform::RUBY
+  s.required_ruby_version = ">= 3.2"
+
+  s.add_runtime_dependency "i18n"
+  s.add_runtime_dependency "evt-casing"
+  s.add_runtime_dependency "evt-record_invocation"
+  s.add_runtime_dependency "evt-template_method"
+
+  s.add_development_dependency "debug"
+  s.add_development_dependency "hubbado-style"
+  s.add_development_dependency "test_bench"
+end

data/lib/hubbado/policy/base.rb

@@ -0,0 +1,78 @@
+module Hubbado
+  module Policy
+    class Base
+      module PolicyDSL
+        def self.included(klass)
+          klass.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          def define_policy(policy, *args, **kwargs, &block)
+            @policies ||= []
+            @policies << policy
+
+            # NOTE: This uses the technique described here so that the block given to
+            # define_policy can have return statements without causing LocalJumpError
+            #   http://blog.jayfields.com/2007/03/ruby-localjumperror-workaround.html
+            define_method policy, &block
+            new_method = instance_method(policy)
+            define_method policy do |*args, **kwargs|
+              new_method.bind(self).call(*args, **kwargs) || denied
+            end
+
+            define_method "#{policy}?" do |*args, **kwargs|
+              send(policy, *args, **kwargs).permitted?
+            end
+          end
+
+          attr_reader :policies
+        end
+      end
+
+      include PolicyDSL
+
+      attr_reader :user, :record
+
+      def self.build(user, record)
+        instance = new(user, record)
+        instance.configure
+        instance
+      end
+
+      # Define this in a subclass if there are dependencies to be configure
+      template_method :configure
+
+      def self.denied(reason = nil, data: nil)
+        reason ||= :denied
+        Result.new(false, reason, i18n_scope: i18n_scope, data: data)
+      end
+
+      def self.permitted
+        Result.new(true, :permitted, i18n_scope: i18n_scope)
+      end
+
+      def self.i18n_scope
+        @i18n_scope ||= Casing::Underscore::String.(name).gsub('/', '.')
+      end
+
+      def initialize(user, record)
+        raise "User not provided" unless user
+
+        @user = user
+        @record = record
+      end
+
+      def ==(other)
+        self.class == other.class && user == other.user && record == other.record
+      end
+
+      def denied(reason = nil, data: nil)
+        self.class.denied(reason, data: data)
+      end
+
+      def permitted
+        self.class.permitted
+      end
+    end
+  end
+end

data/lib/hubbado/policy/railtie.rb

@@ -0,0 +1,7 @@
+module Hubbado
+  module Policy
+    class Railtie < ::Rails::Railtie
+      ::I18n.load_path << ::File.expand_path("../../../../config/locales/en.yml", __FILE__)
+    end
+  end
+end

data/lib/hubbado/policy/result.rb

@@ -0,0 +1,40 @@
+module Hubbado
+  module Policy
+    class Result
+      attr_reader :reason
+      attr_reader :data
+
+      def initialize(permitted, reason, i18n_scope: nil, data: nil)
+        data ||= {}
+        i18n_scope ||= "hubbado_policy"
+
+        @permitted = permitted
+        @reason = reason
+        @i18n_scope = i18n_scope
+        @data = data
+      end
+
+      def permitted?
+        !!@permitted
+      end
+
+      def denied?
+        !@permitted
+      end
+
+      def generic_deny?
+        @reason == :denied
+      end
+
+      def message
+        return if permitted?
+        return ::I18n.t('hubbado_policy.errors.denied') if generic_deny?
+        ::I18n.t(@reason, scope: @i18n_scope)
+      end
+
+      def ==(other)
+        self.class == other.class && permitted? == other.permitted? && @reason == other.reason
+      end
+    end
+  end
+end

data/lib/hubbado/policy/scope.rb

@@ -0,0 +1,50 @@
+module Hubbado
+  module Policy
+    class Scope
+      class << self
+        # Define this in a subclass
+        template_method :default_scope
+      end
+
+      def self.call(record, scope = nil, **options)
+        build.(record, scope, **options)
+      end
+
+      def self.build
+        instance = new
+        instance.configure
+        instance
+      end
+
+      # Define this in a subclass if there are dependencies to be configure
+      template_method :configure
+
+      def call(record, scope = nil, **options)
+        scope ||= self.class.default_scope
+
+        resolve(record, scope, **options)
+      end
+
+      # Implement this in a subclass
+      template_method :resolve do |_record, _scope, **_options|
+        raise MethodMissing
+      end
+
+      module Substitute
+        include RecordInvocation
+
+        attr_writer :result
+
+        record def call(record, scope = nil, **options) = result
+
+        def result
+          @result ||= []
+        end
+
+        def scoped?(record, scope = nil, **options)
+          invoked?(:call, record: record, scope: scope, options: options)
+        end
+      end
+    end
+  end
+end

data/lib/hubbado-policy.rb

@@ -0,0 +1,13 @@
+require "i18n"
+require "casing"
+require "record_invocation"
+require "template_method"; TemplateMethod.activate
+
+I18n.load_path += Dir[File.expand_path("config/locales") + "/*.yml"]
+I18n.default_locale = :en
+
+require "hubbado/policy/railtie" if defined?(Rails::Railtie)
+
+require "hubbado/policy/scope"
+require "hubbado/policy/result"
+require "hubbado/policy/base"

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: hubbado-policy
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Hubbado Devs
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: evt-casing
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: evt-record_invocation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: evt-template_method
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: hubbado-style
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: test_bench
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+email:
+- devs@hubbado.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- config/locales/en.yml
+- hubbado-policy.gemspec
+- lib/hubbado-policy.rb
+- lib/hubbado/policy/base.rb
+- lib/hubbado/policy/railtie.rb
+- lib/hubbado/policy/result.rb
+- lib/hubbado/policy/scope.rb
+homepage: https://github.com/hubbado/hubbado-policy
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hubbado/hubbado-policy
+  source_code_uri: https://github.com/hubbado/hubbado-policy
+  changelog_uri: https://github.com/hubbado/hubbado-policy/blob/master/CHANGELOG.md
+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.6.7
+specification_version: 4
+summary: A lightweight, flexible policy framework for Ruby applications
+test_files: []