caber 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf2b829a8c4545b9421f75c2dc2fbf08bbfa45e03dc01d6cc14cd9bc91c742ff
-  data.tar.gz: 66c199b0d561879e11467ba60723a7d5489c5e1824961a41a2497bb4e64654ac
+  metadata.gz: 71093a528267100a6e810a9906de6dc3bde29357d54f9b4557926c0d9ce5852b
+  data.tar.gz: cdcfda7d716bc8e5f9fd307d803ce8eba968477e724a872e03f8e088c02da0a5
 SHA512:
-  metadata.gz: fb15e64a7fe5ba982b6d55eea3be6d7294f4064f1bb3b31641bc9577b36e3eafd2767442dcf4b287d6382aaf1fd0a26868fccb169a4c11dd436c4d217612eb0a
-  data.tar.gz: f1503f5ed8203e44b807529bc9028bc961437d6d684f11017e43536422a8dddcf06bf1e2f680116c7696d2ecc4983dee7eddfef7f19b440d112a4a36aee863d9
+  metadata.gz: 47d31508f48f5390523980e2507e6654412f4eca34e5af152cbb704fb4b7b72a35020189edf1afe41e04db3f88cd080f69f815a0546578e1719734c88a147b06
+  data.tar.gz: 2b48730f693d2ca3425ae70d2df0f950dfaa6dc24a353cbcba06bd08696772ed3cf3c668b2cce7c28e2b99d536ef87ac79ba76adb342fc03e4d6bccd164f4f73

data/README.md

@@ -37,13 +37,21 @@ end
 Now you're ready to grant some permissions! To give someone permission on something:
 
 ```
-document.grant_permission_to :view, user
+document.grant_permission_to "viewer", user
 ```
 
 You can query permissions in both directions:
 ```
-document.grants_permission_to? :view, user
-user.has_permission_to? :view, document
+document.grants_permission_to? "viewer", user
+user.has_permission_on? "viewer", document
+```
+
+You can also check more than one permission at once by passing an array.
+The check will be positive if *either* are granted:
+
+```
+document.grants_permission_to? ["viewer", "editor"], user
+user.has_permission_on? ["viewer", "editor"], document
 ```
 
 ### Global permissions
@@ -51,7 +59,68 @@ user.has_permission_to? :view, document
 To grant or query permissions globally (for instance, for a public view permission), you can use a `nil` subject:
 
 ```
-document.grant_permission_to :view, nil
+document.grant_permission_to "viewer", nil
+```
+
+### Relationships
+
+In order to query lists of available objects, subjects need to be told what types they can be granted permission on. For each type, after including `Caber::Subject`, call `can_have_permissions_on` with the ActiveRecord class you want to be able to get lists of. `permitted_*` relationships are then automatically added for that type:
+
+```
+class User < ApplicationRecord
+  include Caber::Subject
+  can_have_permissions_on Document
+end
+
+user.permitted_documents
+# => all documents with any granted permission
+
+user.permitted_documents.with_permission "viewer"
+# => all documents that the user has viewer permission on
+
+user.permitted_documents.with_permission ["viewer", "editor"]
+# => all documents that the user has viewer or editor permission on
+
+```
+
+The inverse relationship is also possible by specifying `can_grant_permissions_to` on objects:
+
+```
+class Document < ApplicationRecord
+  include Caber::Object
+  can_grant_permissions_to User
+end
+
+document.permitted_users
+# => all users with any permission
+
+document.permitted_users.with_permission "viewer"
+# => all users with viewer permission
+
+document.permitted_users.with_permission ["viewer", "editor"]
+# => all users with viewer or editor permission
+
+```
+
+### Revoking permissions
+
+You can revoke some or all permissions from a user:
+
+```
+# Remove a specific permission
+document.revoke_permission("viewer", user)
+
+# Remove all permissions from a user
+document.revoke_all_permissions(user)
+```
+
+### Finding objects
+
+You can get lists of objects that a user has some permission on:
+
+```
+Document.granted_to "viewer", user
+# => All the documents that user has "viewer" permission on
 ```
 
 ## Development
@@ -67,3 +136,12 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/manyfo
 ## Code of Conduct
 
 Everyone interacting in the Caber project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/manyfold3d/caber/blob/master/CODE_OF_CONDUCT.md).
+
+## Acknowledgements
+
+This gem was created as part of [Manyfold](https://manyfold.app), with funding from [NGI0 Entrust](https://nlnet.nl/entrust), a fund established by [NLnet](https://nlnet.nl) with financial support from the European Commission's [Next Generation Internet](https://ngi.eu) program.
+
+[<img src="https://nlnet.nl/logo/banner.png" alt="NLnet foundation logo" width="20%" />](https://nlnet.nl)
+[<img src="https://nlnet.nl/image/logos/NGI0_tag.svg" alt="NGI Zero Logo" width="20%" />](https://nlnet.nl/entrust)
+
+Name: `"ReBAC".downcase.reverse`

data/app/models/concerns/caber/object.rb

@@ -2,6 +2,20 @@ module Caber::Object
   extend ActiveSupport::Concern
 
   included do
+    has_many :caber_relations, as: :object, class_name: "Caber::Relation", dependent: :destroy
+    scope :with_permission, ->(permission) { where("caber_relations.permission": permission) }
+
+    def self.can_grant_permissions_to(model)
+      has_many :"permitted_#{model.name.pluralize.parameterize}", through: :caber_relations, source: :subject, source_type: model.name
+    end
+
+    scope :granted_to, ->(permission, subject) {
+                         includes(:caber_relations).where(
+                           "caber_relations.subject_id": subject.id,
+                           "caber_relations.subject_type": subject.class.name,
+                           "caber_relations.permission": permission
+                         )
+                       }
   end
 
   def grant_permission_to(permission, subject)
@@ -11,4 +25,12 @@ module Caber::Object
   def grants_permission_to?(permission, subject)
     Caber::Relation.where(object: self, subject: [subject, nil], permission: permission).present?
   end
+
+  def revoke_permission(permission, subject)
+    Caber::Relation.where(object: self, subject: subject, permission: permission).destroy_all
+  end
+
+  def revoke_all_permissions(subject)
+    Caber::Relation.where(object: self, subject: subject).destroy_all
+  end
 end

data/app/models/concerns/caber/subject.rb

@@ -2,6 +2,12 @@ module Caber::Subject
   extend ActiveSupport::Concern
 
   included do
+    has_many :caber_relations, as: :subject, class_name: "Caber::Relation", dependent: :destroy
+    scope :with_permission, ->(permission) { where("caber_relations.permission": permission) }
+
+    def self.can_have_permissions_on(model)
+      has_many :"permitted_#{model.name.pluralize.parameterize}", through: :caber_relations, source: :object, source_type: model.name
+    end
   end
 
   def has_permission_on?(permission, object)

data/lib/caber/version.rb

@@ -1,3 +1,3 @@
 module Caber
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: caber
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - James Smith
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-28 00:00:00.000000000 Z
+date: 2024-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails