capability based permission manager

1 files changed, 25 insertions, 0 deletions

diff --git a/include/PermissionsManager.h b/include/PermissionsManager.h
index 6d79642..65c00e5 100644
--- a/include/PermissionsManager.h
+++ b/include/PermissionsManager.h
@@ -14,6 +14,7 @@
 namespace nt
 {
     /**
+     * @class Capability-based permission manager
      * @brief Evaluates connection claims and object permissions.
      *
      * Permission checks are intentionally separated from lookup. The object
@@ -40,6 +41,30 @@ namespace nt
          * It is still undecided whether this should run on every attempt to get
          * hold of an object, since that might produce significant overhead.
          *
+         * Note that the permissions systems also rely on objects with capabilities,
+         * so imagining the case a view (ephemeral relation) is created based on 
+         * 3 other stored relations, while you can access the view, you cannot directly
+         * access the other 3 relations. You need explicit permission to create a handle
+         * on the others.
+         * 
+         * Here's an example tree:
+         * /system
+         *     /multigroups
+         *         /coffee_shop
+         *             /relations
+         *                 /user {type : stored}
+         *                 /order {type : stored}
+         *                 /user_and_order {type : ephemeral; deps = [/system/multigroups/coffee_shop/relations/users, /system/multigroups/coffee_shop/relations/orders]}
+         *     /users
+         *         /peter
+         *             /permissions
+         *                 /multigroups/coffee_shop/relations/user_and_order {descriptor : [read]}
+         *         /paul
+         *             /permissions
+         *                 /multigroups/coffee_shop/relations/user {descriptor : [write, read]}
+         * 
+         * Meaning that `peter` has access to read the `user_and_order` ephemeral relation, but cannot open a handle on `user` and `order`.
+         * 
          * @param object Object being accessed.
          * @param connection_context Connection metadata for the caller.
          * @return True when access is allowed.