1 files changed, 40 insertions, 15 deletions

diff --git a/src/fields/util.ts b/src/fields/util.ts
index a62795e64..cf8e730fd 100644
--- a/src/fields/util.ts
+++ b/src/fields/util.ts
@@ -115,6 +115,7 @@ export function OVERRIDE_ACL(val: boolean) {
     _overrideAcl = val;
 }
 
+// playground mode allows the user to add/delete documents or make layout changes without them saving to the server
 let playgroundMode = false;
 
 export function togglePlaygroundMode() {
@@ -125,12 +126,27 @@ export function getPlaygroundMode() {
     return playgroundMode;
 }
 
+// the list of groups that the current user is a member of 
 let currentUserGroups: string[] = [];
 
+// called from GroupManager once the groups have been fetched from the server
 export function setGroups(groups: string[]) {
     currentUserGroups = groups;
 }
 
+/**
+ * These are the various levels of access a user can have to a document.
+ * 
+ * Admin: a user with admin access to a document can remove/edit that document, add/remove/edit annotations (depending on permissions), as well as change others' access rights to that document.
+ * 
+ * Edit: a user with edit access to a document can remove/edit that document, add/remove/edit annotations (depending on permissions), but not change any access rights to that document.
+ * 
+ * Add: a user with add access to a document can add documents/annotations to that document but cannot edit or delete anything.
+ * 
+ * View: a user with view access to a document can only view it - they cannot add/remove/edit anything.
+ * 
+ * None: the document is not shared with that user.
+ */
 export enum SharingPermissions {
     Admin = "Admin",
     Edit = "Can Edit",
@@ -139,18 +155,21 @@ export enum SharingPermissions {
     None = "Not Shared"
 }
 
+/**
+ * Calculates the effective access right to a document for the current user.
+ */
 export function GetEffectiveAcl(target: any, in_prop?: string | symbol | number): symbol {
     if (in_prop === UpdatingFromServer || target[UpdatingFromServer]) return AclAdmin;
 
     if (target[AclSym] && Object.keys(target[AclSym]).length) {
 
+        // if the current user is the author of the document / the current user is a member of the admin group
         if (target.__fields?.author === Doc.CurrentUserEmail || target.author === Doc.CurrentUserEmail || currentUserGroups.includes("admin")) return AclAdmin;
 
+        // if the ACL is being overriden or the property being modified is one of the playground fields (which can be freely modified)
         if (_overrideAcl || (in_prop && DocServer.PlaygroundFields?.includes(in_prop.toString()))) return AclEdit;
 
         let effectiveAcl = AclPrivate;
-        let aclPresent = false;
-
         const HierarchyMapping = new Map<symbol, number>([
             [AclPrivate, 0],
             [AclReadonly, 1],
@@ -160,19 +179,26 @@ export function GetEffectiveAcl(target: any, in_prop?: string | symbol | number)
         ]);
 
         for (const [key, value] of Object.entries(target[AclSym])) {
+            // there are issues with storing fields with . in the name, so they are replaced with _ during creation
+            // as a result we need to restore them again during this comparison.
             if (currentUserGroups.includes(key.substring(4)) || Doc.CurrentUserEmail === key.substring(4).replace("_", ".")) {
-                if (HierarchyMapping.get(value as symbol)! >= HierarchyMapping.get(effectiveAcl)!) {
-                    aclPresent = true;
+                if (HierarchyMapping.get(value as symbol)! > HierarchyMapping.get(effectiveAcl)!) {
                     effectiveAcl = value as symbol;
-                    if (effectiveAcl === AclEdit) break;
+                    if (effectiveAcl === AclAdmin) break;
                 }
             }
         }
-        return aclPresent ? effectiveAcl : AclEdit;
+        return effectiveAcl;
     }
     return AclAdmin;
 }
-
+/**
+ * Recursively distributes the access right for a user across the children of a document and its annotations.
+ * @param key the key storing the access right (e.g. ACL-groupname)
+ * @param acl the access right being stored (e.g. "Can Edit")
+ * @param target the document on which this access right is being set
+ * @param inheritingFromCollection whether the target is being assigned rights after being dragged into a collection (and so is inheriting the ACLs from the collection)
+ */
 export function distributeAcls(key: string, acl: SharingPermissions, target: Doc, inheritingFromCollection?: boolean) {
 
     const HierarchyMapping = new Map<string, number>([
@@ -185,32 +211,31 @@ export function distributeAcls(key: string, acl: SharingPermissions, target: Doc
 
     const dataDoc = target[DataSym];
 
+    // if it is inheriting from a collection, it only inherits if A) the key doesn't already exist or B) the right being inherited is more restrictive
     if (!inheritingFromCollection || !target[key] || HierarchyMapping.get(StrCast(target[key]))! > HierarchyMapping.get(acl)!) target[key] = acl;
 
     if (dataDoc && (!inheritingFromCollection || !dataDoc[key] || HierarchyMapping.get(StrCast(dataDoc[key]))! > HierarchyMapping.get(acl)!)) {
         dataDoc[key] = acl;
 
+        // maps over the children of the document
         DocListCast(dataDoc[Doc.LayoutFieldKey(dataDoc)]).map(d => {
             if (d.author === Doc.CurrentUserEmail && (!inheritingFromCollection || !d[key] || HierarchyMapping.get(StrCast(d[key]))! > HierarchyMapping.get(acl)!)) {
-                distributeAcls(key, acl, d);
-                d[key] = acl;
+                distributeAcls(key, acl, d, inheritingFromCollection);
             }
             const data = d[DataSym];
             if (data && data.author === Doc.CurrentUserEmail && (!inheritingFromCollection || !data[key] || HierarchyMapping.get(StrCast(data[key]))! > HierarchyMapping.get(acl)!)) {
-                distributeAcls(key, acl, data);
-                data[key] = acl;
+                distributeAcls(key, acl, data, inheritingFromCollection);
             }
         });
 
+        // maps over the annotations of the document
         DocListCast(dataDoc[Doc.LayoutFieldKey(dataDoc) + "-annotations"]).map(d => {
             if (d.author === Doc.CurrentUserEmail && (!inheritingFromCollection || !d[key] || HierarchyMapping.get(StrCast(d[key]))! > HierarchyMapping.get(acl)!)) {
-                distributeAcls(key, acl, d);
-                d[key] = acl;
+                distributeAcls(key, acl, d, inheritingFromCollection);
             }
             const data = d[DataSym];
             if (data && data.author === Doc.CurrentUserEmail && (!inheritingFromCollection || !data[key] || HierarchyMapping.get(StrCast(data[key]))! > HierarchyMapping.get(acl)!)) {
-                distributeAcls(key, acl, data);
-                data[key] = acl;
+                distributeAcls(key, acl, data, inheritingFromCollection);
             }
         });
     }