access_forge-permissions 0.1.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa5e73556453d6a607b119e7940db5ead024c7c413b4d63e37826f9b0f055656
-  data.tar.gz: cdc6ee945f57ebbe35e285e484291b9a5ab2ffb4608275f3ebecc6c18f4ba671
+  metadata.gz: 19d6c062402c02a718432846522854cdcf43a94573010561b1fb8b5af9da9eb7
+  data.tar.gz: fa77e771842712439cd55f2fc64c0e71447ef078e81612ef1fe7ff3d5bf8246a
 SHA512:
-  metadata.gz: dedbf211e66502050166bcfb00a881b92ef68371d149b16cc1c9484c7597a684a69b4ffe3f87dc575db1338eba805e4a7c09f55fe525a5126afdcb8835141f26
-  data.tar.gz: 32bae7dad9bf20c24b73875d427344c30c414d2d1fee5456ca689c497a67efbb5176b750e12b1e04832ae4e1e14969f94d6bc82894d4ce22041d81047d8b678f
+  metadata.gz: 6f40baae5c31e3aa1fd0c01c197e536835d9d28e7668836da10fe91e90997e3ae825a9ec5140d694e28c31b6b0eb228d08e1f2ce9e4122121feb9e01fc63a76c
+  data.tar.gz: c1549bf8677eab2973aad6a5aae743af225c13f488f682c219e482c7fb8b9b96da8f98d75989aa830dae21c867315759ff3dd578f0a3ca7f4d82599bba25010f

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    access_forge-permissions (0.1.2)
+    access_forge-permissions (1.0.0)
       rails (>= 6.1)
 
 GEM

data/README.md

@@ -1,38 +1,195 @@
 # AccessForge::Permissions
 
-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/permissions`. To experiment with that code, run `bin/console` for an interactive prompt.
+`AccessForge::Permissions` provides a production-ready `PermissionPolicyRule` for **Ruby on Rails** applications using AccessForge.
 
-TODO: Delete this and the text above, and describe your gem
+It introduces a simple, composable way to express permission-based authorization - without imposing a fixed persistence model.
 
-## Installation
+If you are using AccessForge and want permission checks backed by your own data model, this is the first extension you should reach for.
+
+## Philosophy
+
+AccessForge defines how policies are evaluated.
+
+AccessForge::Permissions defines a reusable rule for permission checks.
 
-Add this line to your application's Gemfile:
+This gem deliberately keeps its contract minimal:
 
+If your `User` has a `has_many :permissions` association, `PermissionPolicyRule` will work.
+
+That’s it.
+
+How permissions are assigned - directly, via groups, or through any other structure - is entirely up to you.
+
+## Installation
+
+Add to your Gemfile:
 ```ruby
-gem 'access_forge-permissions'
+gem "access_forge-permissions"
+```
+
+Then:
+```bash
+bundle install
+```
+
+## The Core Rule: `PermissionPolicyRule`
+
+`PermissionPolicyRule` checks whether the current user has a required permission.
+
+It expects:
+* A `User` model
+* A `has_many :permissions` association on that model
+
+Example:
+```
+class User < ApplicationRecord
+  has_many :permissions
+end
+```
+
+Or via has_many :through:
+```
+class User < ApplicationRecord
+  has_many :access_group_users
+  has_many :access_groups, through: :access_group_users
+  has_many :permissions, through: :access_groups
+end
+```
+
+## Usage with AccessForge
+
+Inside your AccessForge policy:
+```
+class EmployeePolicy < AccessForge::Policy
+  def index?
+    authorized?(
+      [ PermissionPolicyRule ],
+      { feature: 'Employees', verb: :read }
+    )
+  end
+end
+```
+
+When evaluated, the rule checks:
+```
+current_user.permissions.exists?({ permissions: { name: "Can #{options[:verb]} #{options[:feature]}" } })
+```
+
+If the permission exists, the rule passes.
+
+If not, authorization fails.
+
+Because it is a rule object, it composes naturally with other AccessForge rules.
+
+## Flexible Data Models
+
+This gem does **not** enforce a particular authorization architecture.
+
+You may:
+* Assign permissions directly to users
+* Implement group-based RBAC
+* Build hierarchical group structures
+* Introduce multi-tenant permission scoping
+* Extend the Permission model with metadata
+
+The only requirement is that the user responds to:
 ```
+user.permissions
+```
+
+This design keeps your authorization model:
+* Explicit
+* Evolvable
+* Aligned with your domain
+
+## Access Group Generator
+
+To help you get started, this gem includes a generator that creates a conventional group-based permission structure.
+
+Run:
+```bash
+rails generate access_forge:access_groups
+```
+
+This creates:
+* AccessGroup
+* AccessGroupUser
+* AccessGroupPermission
+* Permission
+
+Along with their corresponding migrations.
+
+The generated structure provides:
+* Many-to-many Users ↔ AccessGroups
+* Many-to-many AccessGroups ↔ Permissions
+* A `has_many :permissions, through:` setup on `User`
 
-And then execute:
+You are free to modify or extend these models after generation.
 
-    $ bundle
+The generator exists for convenience - not constraint.
 
-Or install it yourself as:
+## Why This Design?
 
-    $ gem install access_forge-permissions
+Many authorization libraries tightly couple:
+* Policy logic
+* Persistence model
+* DSL assumptions
 
-## Usage
+`AccessForge::Permissions` intentionally separates these concerns.
+* AccessForge evaluates policies.
+* PermissionPolicyRule checks permissions.
+* Your application owns the data model.
 
-TODO: Write usage instructions here
+This separation provides:
+* Architectural control
+* Testable rule objects
+* Clear domain boundaries
+* Long-term flexibility
+
+## When to Use This Extension
+
+Use `AccessForge::Permissions` if:
+* You want permission-based authorization
+* You prefer explicit policy objects over implicit callbacks
+* You want full control over your persistence model
+* You are building a system where authorization must evolve over time
+
+## Relationship to AccessForge
+
+AccessForge is a controller-oriented policy engine built for experienced Rails developers who value architectural control.
+
+`AccessForge::Permissions` is the first official extension — providing a clean, composable permission rule that integrates seamlessly into the core engine.
+
+Together they provide:
+* Explicit controller authorization
+* Composable rule objects
+* Flexible persistence strategies
+* Clear separation of concerns
 
 ## 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 release a new version:
+1. Update the version number in `version.rb`
+2. Run:
+```
+bundle exec rake release
+```
 
-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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+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-permissions. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub:
+
+[https://github.com/CodeTectonics/access_forge-permissions](https://github.com/CodeTectonics/access_forge-permissions).
+
+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-permissions/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -40,4 +197,5 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the AccessForge::Permissions project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/access_forge-permissions/blob/master/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-permissions/blob/main/CODE_OF_CONDUCT.md).
+

data/access_forge-permissions.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.authors = ["Mark Harbison"]
   spec.email = ["mark@tyne-solutions.com"]
 
-  spec.summary = "A persistence-backed AccessForge implementation for permission based authorisation."
-  spec.description = "A persistence-backed AccessForge implementation for permission based authorisation."
+  spec.summary = "The official permission layer for AccessForge."
+  spec.description = "The official permission layer for AccessForge."
   spec.homepage = "https://github.com/CodeTectonics/access_forge-permissions"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.2.0"

data/lib/access_forge/permissions/version.rb

@@ -1,5 +1,5 @@
 module AccessForge
   module Permissions
-    VERSION = "0.1.2"
+    VERSION = "1.0.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: access_forge-permissions
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Mark Harbison
@@ -66,8 +66,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.21'
-description: A persistence-backed AccessForge implementation for permission based
-  authorisation.
+description: The official permission layer for AccessForge.
 email:
 - mark@tyne-solutions.com
 executables: []
@@ -127,7 +126,7 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: A persistence-backed AccessForge implementation for permission based authorisation.
+summary: The official permission layer for AccessForge.
 test_files:
 - spec/access_forge/permissions_spec.rb
 - spec/spec_helper.rb