caber 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf2b829a8c4545b9421f75c2dc2fbf08bbfa45e03dc01d6cc14cd9bc91c742ff
-  data.tar.gz: 66c199b0d561879e11467ba60723a7d5489c5e1824961a41a2497bb4e64654ac
+  metadata.gz: 32626bb698069dab3797b3fe532bce89def4fc6a91c0662e030b93df58c7b0c4
+  data.tar.gz: 999efb197f1567376feb709b6d2e77d83d2d4d0f79e42ecdae8c7e2429997f9d
 SHA512:
-  metadata.gz: fb15e64a7fe5ba982b6d55eea3be6d7294f4064f1bb3b31641bc9577b36e3eafd2767442dcf4b287d6382aaf1fd0a26868fccb169a4c11dd436c4d217612eb0a
-  data.tar.gz: f1503f5ed8203e44b807529bc9028bc961437d6d684f11017e43536422a8dddcf06bf1e2f680116c7696d2ecc4983dee7eddfef7f19b440d112a4a36aee863d9
+  metadata.gz: 67c2028ca5dd0aead722b9ea20961c41e2fe8fe6733c4b68b732f08f4292b32b568ac7f3b6e49d0f30168b01cc7c78ff457f319410c7e504856640c57800c605
+  data.tar.gz: 868d630bf81d19a45b9ff058cdac098ccb6115f985e1a9c0426e30243ed6b36e8dbf2b16b3da1a68e889906d2b571cf1aed9beac62ed9ce4940f6ee638cec7a9

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,9 +59,62 @@ 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)
+```
+
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
@@ -67,3 +128,10 @@ 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)

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

@@ -2,6 +2,12 @@ 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
   end
 
   def grant_permission_to(permission, subject)
@@ -11,4 +17,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.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: caber
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.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