From 7b4f0cd5d7f1bb35af50b17f331394b97b39b828 Mon Sep 17 00:00:00 2001
From: Ian Ross <iross@cadasta.org>
Date: Tue, 15 Mar 2016 19:56:10 +0100
Subject: [PATCH] Comments and cleanup

---
 cadasta/config/permissions/data-collector.json  |  5 ++++-
 cadasta/config/permissions/default.json         |  9 ++++++++-
 cadasta/config/permissions/org-admin.json       |  9 +++++++--
 cadasta/config/permissions/project-manager.json |  9 +++++++--
 cadasta/config/permissions/project-user.json    | 13 ++++---------
 cadasta/config/permissions/superuser.json       | 10 ++++++----
 6 files changed, 36 insertions(+), 19 deletions(-)

diff --git a/cadasta/config/permissions/data-collector.json b/cadasta/config/permissions/data-collector.json
index a0b5bed89..b8ed49c40 100644
--- a/cadasta/config/permissions/data-collector.json
+++ b/cadasta/config/permissions/data-collector.json
@@ -1,9 +1,12 @@
 {
   "clause": [
+    // In addition to the permissions provided by the default
+    // policy, data collectors are allowed to manage resources for a
+    // specified project within a specified organization.
     {
       "effect": "allow",
       "action": ["project.resources.*"],
-      "object": ["project/$organization/$project"],
+      "object": ["project/$organization/$project"]
     }
   ]
 }
diff --git a/cadasta/config/permissions/default.json b/cadasta/config/permissions/default.json
index d271fe23a..be1143f4f 100644
--- a/cadasta/config/permissions/default.json
+++ b/cadasta/config/permissions/default.json
@@ -1,21 +1,28 @@
 {
   "clause": [
     {
+      // Any user is allowed to list organizations and create new
+      // ones.
       "effect": "allow",
       "action": ["org.list", "org.create"]
     },
     {
+      // Any user is allowed to view the details of an organization.
       "effect": "allow",
       "action": ["org.view"],
-      "object": ["organization/*"],
+      "object": ["organization/*"]
     },
 
     {
+      // Any user is allowed to list the public projects in an
+      // organization.
       "effect": "allow",
       "action": ["project.list"],
       "object": ["organization/*"]
     },
     {
+      // Any user is allowed to view the details of public projects in
+      // an organization.
       "effect": "allow",
       "action": ["project.view"],
       "object": ["project/*/*"]
diff --git a/cadasta/config/permissions/org-admin.json b/cadasta/config/permissions/org-admin.json
index 0adb292f1..f3bc08a30 100644
--- a/cadasta/config/permissions/org-admin.json
+++ b/cadasta/config/permissions/org-admin.json
@@ -1,15 +1,20 @@
 {
   "clause": [
+    // In addition to the permissions provided by the default
+    // policy, organization administrators are allowed to perform all
+    // organization management actions for a specified organization,
+    // and all project management actions for all projects within a
+    // specified organization.
     {
       "effect": "allow",
       "action": ["org.*", "org.*.*", "project.*", "project.*.*"],
-      "object": ["organization/$organization"],
+      "object": ["organization/$organization"]
     },
 
     {
       "effect": "allow",
       "action": ["project.*", "project.*.*"],
-      "object": ["project/$organization/*"],
+      "object": ["project/$organization/*"]
     }
   ]
 }
diff --git a/cadasta/config/permissions/project-manager.json b/cadasta/config/permissions/project-manager.json
index 6ce3ef7bf..c555b4f0c 100644
--- a/cadasta/config/permissions/project-manager.json
+++ b/cadasta/config/permissions/project-manager.json
@@ -1,14 +1,19 @@
 {
   "clause": [
+    // In addition to the permissions provided by the default
+    // policy, project managers are allowed to perform all project
+    // management actions, except for project archiving and
+    // unarchiving, for a specified project within a specified
+    // organization.
     {
       "effect": "allow",
       "action": ["project.*", "project.*.*"],
-      "object": ["project/$organization/$project"],
+      "object": ["project/$organization/$project"]
     },
     {
       "effect": "deny",
       "action": ["project.archive", "project.unarchive"],
-      "object": ["project/$organization/$project"],
+      "object": ["project/$organization/$project"]
     }
   ]
 }
diff --git a/cadasta/config/permissions/project-user.json b/cadasta/config/permissions/project-user.json
index 029e0b495..6c00659ad 100644
--- a/cadasta/config/permissions/project-user.json
+++ b/cadasta/config/permissions/project-user.json
@@ -1,13 +1,8 @@
 {
   "clause": [
-    {
-      "effect": "allow",
-      "action": ["org.list", "org.create"]
-    },
-    {
-      "effect": "allow",
-      "object": ["organization/*"],
-      "action": ["org.view"]
-    }
+    // Currently, "ordinary" users associated with a project have no
+    // additional permissions over those given to all users.  This may
+    // change in the future.  In particular, project users may be
+    // permitted access to projects that are normally private.
   ]
 }
diff --git a/cadasta/config/permissions/superuser.json b/cadasta/config/permissions/superuser.json
index c3bd95057..c81e7ff99 100644
--- a/cadasta/config/permissions/superuser.json
+++ b/cadasta/config/permissions/superuser.json
@@ -1,5 +1,7 @@
 {
   "clause": [
+    // A superuser is permitted to perform all actions on all entities
+    // within the platform.
     {
       "effect": "allow",
       "action": ["org.*"]
@@ -7,18 +9,18 @@
     {
       "effect": "allow",
       "action": ["org.*", "org.*.*"],
-      "object": ["organization/*"],
+      "object": ["organization/*"]
     },
 
     {
       "effect": "allow",
       "action": ["project.*", "project.*.*"],
-      "object": ["organization/*"],
+      "object": ["organization/*"]
     },
     {
       "effect": "allow",
       "action": ["project.*", "project.*.*"],
-      "object": ["project/*/*"],
+      "object": ["project/*/*"]
     },
 
     {
@@ -28,7 +30,7 @@
     {
       "effect": "allow",
       "action": ["user.*"],
-      "object": ["user/*"],
+      "object": ["user/*"]
     }
   ]
 }