@@ -37,10 +37,16 @@ const implicit_user_permissions = {
3737
3838
3939/**
40- * The PermissionService class manages the core functionality for handling permissions within the Puter ecosystem.
41- * It provides methods for granting, revoking, and checking permissions for various entities such as users and applications.
42- * This service interacts with the database to store, retrieve, and audit permission changes, and also handles complex permission logic like rewriting, implication, and explosion of permissions.
43- */
40+ * Permission rewriters are used to map one set of permission strings to another.
41+ * These are invoked during permission scanning and when permissions are granted or revoked.
42+ *
43+ * For example, Puter's filesystem uses this to map 'fs:/some/path:mode' to
44+ * 'fs:SOME-UUID:mode'.
45+ *
46+ * A rewriter is constructed using the static method PermissionRewriter.create({ matcher, rewriter }).
47+ * The matcher is a function that takes a permission string and returns true if the rewriter should be applied.
48+ * The rewriter is a function that takes a permission string and returns the rewritten permission string.
49+ */
4450class PermissionRewriter {
4551 static create ( { id, matcher, rewriter } ) {
4652 return new PermissionRewriter ( { id, matcher, rewriter } ) ;
@@ -70,11 +76,17 @@ class PermissionRewriter {
7076
7177
7278/**
73- * The PermissionImplicator class is used to manage implicit permissions.
74- * It defines methods to match and check if a given permission is implicitly granted to an actor.
75- * @class
76- * @name PermissionImplicator
77- */
79+ * Permission implicators are used to manage implicit permissions.
80+ * It defines a method to check if a given permission is implicitly granted to an actor.
81+ *
82+ * For example, Puter's filesystem uses this to grant permission to a file if the specified
83+ * 'actor' is the owner of the file.
84+ *
85+ * An implicator is constructed using the static method PermissionImplicator.create({ matcher, checker }).
86+ * `matcher is a function that takes a permission string and returns true if the implicator should be applied.
87+ * `checker` is a function that takes an actor and a permission string and returns true if the permission is implied.
88+ * The actor and permission are passed to checker({ actor, permission }) as an object.
89+ */
7890class PermissionImplicator {
7991 static create ( { id, matcher, checker } ) {
8092 return new PermissionImplicator ( { id, matcher, checker } ) ;
@@ -108,12 +120,17 @@ class PermissionImplicator {
108120
109121
110122/**
111- * The PermissionExploder class is responsible for expanding permissions into a set of more granular permissions.
112- * It uses a matcher function to determine if a permission should be exploded and an exploder function to perform the expansion.
113- * This class is part of the permission management system, allowing for dynamic and complex permission structures.
114- *
115- * @class PermissionExploder
116- */
123+ * Permission exploders are used to map any permission to a list of permissions
124+ * which are considered to imply the specified permission.
125+ *
126+ * It uses a matcher function to determine if a permission should be exploded
127+ * and an exploder function to perform the expansion.
128+ *
129+ * The exploder is constructed using the static method PermissionExploder.create({ matcher, explode }).
130+ * The `matcher` is a function that takes a permission string and returns true if the exploder should be applied.
131+ * The `explode` is a function that takes an actor and a permission string and returns a list of implied permissions.
132+ * The actor and permission are passed to explode({ actor, permission }) as an object.
133+ */
117134class PermissionExploder {
118135 static create ( { id, matcher, exploder } ) {
119136 return new PermissionExploder ( { id, matcher, exploder } ) ;
@@ -952,14 +969,26 @@ class PermissionService extends BaseService {
952969 }
953970
954971
955- register_rewriter ( translator ) {
956- if ( ! ( translator instanceof PermissionRewriter ) ) {
957- throw new Error ( 'translator must be a PermissionRewriter' ) ;
972+ /**
973+ * Register a permission rewriter. For details see the documentation on the
974+ * PermissionRewriter class.
975+ *
976+ * @param {PermissionRewriter } rewriter - The permission rewriter to register
977+ */
978+ register_rewriter ( rewriter ) {
979+ if ( ! ( rewriter instanceof PermissionRewriter ) ) {
980+ throw new Error ( 'rewriter must be a PermissionRewriter' ) ;
958981 }
959982
960- this . _permission_rewriters . push ( translator ) ;
983+ this . _permission_rewriters . push ( rewriter ) ;
961984 }
962985
986+ /**
987+ * Register a permission implicator. For details see the documentation on the
988+ * PermissionImplicator class.
989+ *
990+ * @param {PermissionImplicator } implicator - The permission implicator to register
991+ */
963992 register_implicator ( implicator ) {
964993 if ( ! ( implicator instanceof PermissionImplicator ) ) {
965994 throw new Error ( 'implicator must be a PermissionImplicator' ) ;
@@ -968,6 +997,12 @@ class PermissionService extends BaseService {
968997 this . _permission_implicators . push ( implicator ) ;
969998 }
970999
1000+ /**
1001+ * Register a permission exploder. For details see the documentation on the
1002+ * PermissionExploder class.
1003+ *
1004+ * @param {PermissionExploder } exploder - The permission exploder to register
1005+ */
9711006 register_exploder ( exploder ) {
9721007 if ( ! ( exploder instanceof PermissionExploder ) ) {
9731008 throw new Error ( 'exploder must be a PermissionExploder' ) ;
0 commit comments