access_forge 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48aa9fe17d4661aa26bbcbfa0d23881788f5cc56e1e20cf04584991e7d046050
-  data.tar.gz: c4fa5e43b04d69a2f0222988404f1291caa6eb711f4adb5ddc17f33d8c6a62b4
+  metadata.gz: 5ce9503a123b98c43d0627caf65f3de41581b16a41d142b00d3d00d23d5045bb
+  data.tar.gz: fb8a30a4295783dd14bd507a4a8b6c3da67b00128220b13148fe0a6030c49e76
 SHA512:
-  metadata.gz: c0503b9ef7b6d4d60780044947f2e6dee0db5e36b5c40a4815b7101ebe5e88a60139e0547a4e8ff09b42d941bb31eb78c45b5ac64f928f6ccde0db555b2233eb
-  data.tar.gz: c301490d1b7d795ca3676398041dfac4b9b6b6361129f6b4218c36664cdd18bf92d8e6e6f18031dea4f8016753da90a0dac1ccb3163c00c58e61725ba03d81b0
+  metadata.gz: 640ed26fed01e313e9ed8219802dc2b12d83065a22aac5184b03594fad2a1031f1ee3a3a9d04577d4de085d7faf170e677b3c8c69b919715927486394cca09c5
+  data.tar.gz: d52746024392d65f39601b84c42cfd8ed0ed9f6be38b5efe2711f23422745fb3a3540bc3f07c3046a7a28a262c076f0be2db421a2f577168d536859a5efc3b3c

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    access_forge (0.1.0)
+    access_forge (1.0.0)
 
 GEM
   remote: https://rubygems.org/
@@ -49,6 +49,7 @@ GEM
     unicode-display_width (2.5.0)
 
 PLATFORMS
+  aarch64-linux
   x86_64-darwin-20
 
 DEPENDENCIES

data/README.md

@@ -1,34 +1,237 @@
 # AccessForge
 
-TODO: Delete this and the text below, and describe your gem
+AccessForge is a controller-oriented authorization engine with composable rule objects for Ruby on Rails.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/access_forge`. To experiment with that code, run `bin/console` for an interactive prompt.
+It provides:
+* Convention-based policy resolution
+* Action-oriented authorization methods
+* Composable, reusable policy rules
+* A clean extension surface for custom authorization strategies
 
-## Installation
+AccessForge treats authorization as an application concern at the controller boundary — explicit, testable, and decoupled from persistence.
+
+## Why AccessForge?
+
+AccessForge is designed around three principles:
+1. Authorization decisions occur at the controller boundary.
+2. Authorization should be explicit per action.
+3. Authorization logic should be reusable and composable.
+
+Rather than embedding complex logic directly inside policy methods, AccessForge encourages the use of Policy Rule classes — small, focused, testable units of authorization behavior.
+
+This keeps policies readable while allowing authorization strategies to evolve independently.
+
+## Design Philosophy
+
+AccessForge separates policy orchestration from authorization strategy.
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+It does not impose a persistence model or assume how permissions are stored. Instead, it provides a composable rule system that allows you to implement your own authorization strategy.
 
-Install the gem and add to the application's Gemfile by executing:
+Authorization strategies such as group-based RBAC can be implemented via extension gems without modifying your policies.
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+Policies remain stable. Strategies remain replaceable.
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+## Installation
+
+Add this line to your application's Gemfile:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+gem 'access_forge'
+```
+
+Then execute:
+```bash
+bundle install
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+### Step 1: Enable policy resolution in your controllers
+
+Include `AccessForge::ControllerHelpers` to enable convention-based policy resolution:
+
+```
+class ApplicationController < ActionController::API
+  include AccessForge::ControllerHelpers
+end
+```
+
+### Step 2: Register the authorization hook
+
+Register the `authorize_user!` hook to enforce authorization before each action:
+
+```
+class ApplicationController < ActionController::API
+  include AccessForge::ControllerHelpers
+
+  before_action :authorize_user!
+end
+```
+
+### Step 3: Define your policy classes
+
+AccessForge resolves policy classes using controller naming conventions.
+
+For example:
+* `EmployeesController` → `EmployeePolicy`
+
+Policies should inherit from `AccessForge::Policy`, either directly or via an application-level base policy.
+
+```
+class ApplicationPolicy < AccessForge::Policy
+end
+
+class EmployeePolicy < ApplicationPolicy
+end
+```
+
+If you need to override the default resolution behavior, you may define #policy_class in your controller:
+
+```
+class EmployeesController < ApplicationController
+  def policy_class
+    DifferentPolicy
+  end
+end
+```
+
+### Step 4: Implement policy methods
+
+For each controller action, AccessForge calls the corresponding predicate method on the policy.
+
+For example:
+* `show` → `show?`
+* `create` → `create?`
+
+Each method should return `true` or `false`.
+
+A false result will prevent the action from being performed and return a 401 response. A true result allows execution to proceed.
+
+```
+class EmployeePolicy < ApplicationPolicy
+  def index?
+    true
+  end
+
+  def create?
+    false
+  end
+end
+```
+
+If multiple actions share identical logic, you may use:
+* `can_read?` for `index` and `show`
+* `can_write?` for `create`, `update`, and `destroy`
+
+```
+class EmployeePolicy < ApplicationPolicy
+  def can_read?
+    true
+  end
+
+  def can_write?
+    false
+  end
+end
+```
+
+### Step 5: Extract reusable logic with Policy Rules
+
+Up until now, authorization logic has lived directly inside policy methods.
+
+For reusable or cross-cutting logic, AccessForge provides Policy Rules.
+
+Policy Rules allow authorization behavior to be extracted, composed, and reused across policies without coupling policies to persistence or infrastructure concerns.
+
+`AccessForge::Policy` exposes an `authorized?` helper:
+
+```
+authorized?(rules, options = {})
+```
+
+* `rules` — an array of Policy Rule classes
+* `options` — optional parameters passed to each rule
+
+If any rule returns `true`, authorization succeeds.
+
+AccessForge includes two default rules:
+* `OpenPolicyRule` — always grants access
+* `ClosedPolicyRule` — always denies access
+
+```
+module AccessForge
+  class OpenPolicyRule
+    def self.authorized?(_user, _controller, _options)
+      true
+    end
+  end
+
+  class ClosedPolicyRule
+    def self.authorized?(_user, _controller, _options)
+      false
+    end
+  end
+end
+```
+
+You may define custom rules:
+
+```
+class PermissionPolicyRule
+  def self.authorized?(user, _controller, options)
+    permission_name = "Can #{options[:verb]} #{options[:feature]}"
+    user.permissions.exists?({ permissions: { name: permission_name } })
+  end
+end
+
+class EmployeePolicy < ApplicationPolicy
+  def index?
+    authorized?(
+      [ PermissionPolicyRule ],
+      { feature: 'Employees', verb: :read }
+    )
+  end
+end
+```
+
+This approach keeps policy classes focused while allowing authorization strategies to scale independently.
+
+## Extensions
+
+AccessForge is designed to be extended.
+
+Official and third-party extensions may provide:
+* Persistence-backed authorization strategies
+* RBAC implementations
+* Alternative rule sets
+* Integration layers
+
+Because policies depend only on rule interfaces, new strategies can be introduced without rewriting existing policies.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repository:
+```
+bin/setup
+rake spec
+```
 
-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 release a new version:
+1. Update the version number in `version.rb`
+2. Run:
+```
+bundle exec rake release
+```
+
+This will tag the release, push commits, and publish the gem to RubyGems.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/access_forge. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/access_forge/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub:
+
+[https://github.com/CodeTectonics/access_forge](https://github.com/CodeTectonics/access_forge).
+
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/CodeTectonics/access_forge/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -36,4 +239,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the AccessForge project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/access_forge/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the AccessForge project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/CodeTectonics/access_forge/blob/main/CODE_OF_CONDUCT.md).

data/access_forge.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |s|
   s.authors = ["Mark Harbison"]
   s.email = ["mark@tyne-solutions.com"]
 
-  s.summary = "A simple, extendable authorization framework for Ruby on Rails applications."
-  s.description = "A simple, extendable authorization framework for Ruby on Rails applications."
+  s.summary = "Controller-oriented authorization with composable rule objects."
+  s.description = "Controller-oriented authorization with composable rule objects."
   s.homepage = "https://github.com/CodeTectonics/access_forge"
   s.license = "MIT"
   s.required_ruby_version = ">= 2.6.0"

data/lib/access_forge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AccessForge
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: access_forge
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Mark Harbison
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-28 00:00:00.000000000 Z
+date: 2026-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -52,7 +52,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.7'
-description: A simple, extendable authorization framework for Ruby on Rails applications.
+description: Controller-oriented authorization with composable rule objects.
 email:
 - mark@tyne-solutions.com
 executables: []
@@ -106,10 +106,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.21
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: A simple, extendable authorization framework for Ruby on Rails applications.
+summary: Controller-oriented authorization with composable rule objects.
 test_files:
 - spec/closed_policy_rule_spec.rb
 - spec/dummy/dummy_controller.rb