Merge pull request #2449 from phenotips/PT-3435

PT-3435: Auditability of permissions and data sharing

components/entity-access-rules/api/pom.xml

@@ -29,7 +29,7 @@
   <name>PhenoTips - Entity access rules - Java APIs</name>
 
   <properties>
-    <coverage.instructionRatio>0.87</coverage.instructionRatio>
+    <coverage.instructionRatio>0.86</coverage.instructionRatio>
   </properties>
 
   <dependencies>

components/entity-access-rules/api/src/main/java/org/phenotips/data/permissions/internal/DefaultEntityAccessHelper.java

@@ -34,6 +34,7 @@
 
 import com.xpn.xwiki.XWiki;
 import com.xpn.xwiki.XWikiContext;
+import com.xpn.xwiki.api.Document;
 import com.xpn.xwiki.doc.XWikiDocument;
 import com.xpn.xwiki.objects.BaseObject;
 
@@ -96,6 +97,23 @@ public String getType(@Nullable EntityReference userOrGroup)
         return UNKNOWN_LABEL;
     }
 
+    @Nonnull
+    @Override
+    public Document getDocument(EntityReference userOrGroup)
+    {
+        if (userOrGroup == null) {
+            return null;
+        }
+        try {
+            XWikiDocument doc = (XWikiDocument) this.bridge.getDocument((DocumentReference) userOrGroup);
+            XWikiContext xcontext = this.xcontextProvider.get();
+            return doc.newDocument(xcontext);
+        } catch (Exception ex) {
+            this.logger.warn("Failed to get user or group document: {}", ex.getMessage(), ex);
+        }
+        return null;
+    }
+
     @Nullable
     @Override
     public String getStringProperty(

components/entity-access-rules/api/src/main/java/org/phenotips/data/permissions/internal/EntityAccessHelper.java

@@ -24,6 +24,7 @@
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
+import com.xpn.xwiki.api.Document;
 import com.xpn.xwiki.doc.XWikiDocument;
 
 /**
@@ -48,6 +49,15 @@ public interface EntityAccessHelper
     @Nonnull
     String getType(@Nullable EntityReference userOrGroup);
 
+    /**
+     * Retrieves the entity document of {@code userOrGroup}.
+     *
+     * @param userOrGroup an {@link EntityReference} object representing a user or a group
+     * @return the {@link Document} of entity
+     */
+    @Nonnull
+    Document getDocument(EntityReference userOrGroup);
+
     /**
      * Gets the string property value given the xwiki {@code doc}, the {@code classReference}, and the
      * {@code propertyName}.

components/entity-access-rules/rest/pom.xml

@@ -29,6 +29,7 @@
   <name>PhenoTips - Entity access rules - REST services</name>
 
   <properties>
+    <checkstyle.suppressions.location>${basedir}/src/checkstyle/checkstyle-suppressions.xml</checkstyle.suppressions.location>
     <!-- Fixme. Coverage. -->
     <coverage.instructionRatio>0.0</coverage.instructionRatio>
   </properties>
@@ -69,6 +70,11 @@
       <artifactId>xwiki-platform-bridge</artifactId>
       <version>${xwiki.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.xwiki.platform</groupId>
+      <artifactId>xwiki-platform-security-api</artifactId>
+      <version>${xwiki.version}</version>
+    </dependency>
     <dependency>
       <groupId>${project.groupId}</groupId>
       <artifactId>phenotips-constants</artifactId>
@@ -79,6 +85,11 @@
       <artifactId>phenotips-entities-api</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>${project.groupId}</groupId>
+      <artifactId>users-api</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>${project.groupId}</groupId>
       <artifactId>xwiki-platform-users-api</artifactId>
@@ -111,6 +122,16 @@
       <artifactId>phenotips-rest-commons</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>${project.groupId}</groupId>
+      <artifactId>family-studies-api</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>${project.groupId}</groupId>
+      <artifactId>patient-data-api</artifactId>
+      <version>${project.version}</version>
+    </dependency>
   </dependencies>
 
   <build>

components/entity-access-rules/rest/src/checkstyle/checkstyle-suppressions.xml

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see http://www.gnu.org/licenses/
+-->
+
+<!DOCTYPE suppressions PUBLIC
+    "-//Puppy Crawl//DTD Suppressions 1.0//EN"
+    "http://www.puppycrawl.com/dtds/suppressions_1_0.dtd">
+
+<suppressions>
+  <suppress checks="ClassFanOutComplexity" files="DefaultDomainObjectFactory.java"/>
+  <suppress checks="CyclomaticComplexity" files="DefaultDomainObjectFactory.java"/>
+</suppressions>

components/entity-access-rules/rest/src/main/java/org/phenotips/data/permissions/rest/DomainObjectFactory.java

@@ -22,6 +22,7 @@
 import org.phenotips.data.permissions.rest.model.CollaboratorRepresentation;
 import org.phenotips.data.permissions.rest.model.CollaboratorsRepresentation;
 import org.phenotips.data.permissions.rest.model.OwnerRepresentation;
+import org.phenotips.data.permissions.rest.model.PrincipalsRepresentation;
 import org.phenotips.data.permissions.rest.model.VisibilityRepresentation;
 import org.phenotips.entities.PrimaryEntity;
 
@@ -73,23 +74,31 @@ public interface DomainObjectFactory
      * Create the REST representation for a list of {@link Collaborator}s, starting from a {@link PrimaryEntity}
      * instance.
      *
-     * @param entity the (list of) collaborators that are attached to this entity record
+     * @param entity to whom the the (list of) collaborators that are attached
      * @param uriInfo the URI information for the rest system and the current request
      * @return a summary of each collaborator on the entity record, or {@code null} if the current user doesn't have
      *         access to the entity or accessing the entity data fails.
      */
-    CollaboratorsRepresentation createCollaboratorsRepresentation(PrimaryEntity entity,
-        UriInfo uriInfo);
+    CollaboratorsRepresentation createCollaboratorsRepresentation(PrimaryEntity entity, UriInfo uriInfo);
 
     /**
      * Create the REST representation for summary of a {@link Collaborator} instance, starting from a
      * {@link PrimaryEntity} and {@link Collaborator} instances.
      *
-     * @param entity to whom the collaborator is attached
      * @param collaborator that is to be represented
      * @return a summary of the collaborator, or {@code null} if the current user doesn't have access to the entity or
      *         accessing the entity data fails.
      */
-    CollaboratorRepresentation createCollaboratorRepresentation(PrimaryEntity entity,
-        Collaborator collaborator);
+    CollaboratorRepresentation createCollaboratorRepresentation(Collaborator collaborator);
+
+    /**
+     * Create the REST representation for a list of principals that have access to the {@link PrimaryEntity}.
+     *
+     * @param entity whose accessers are of interest
+     * @param entityType the type of entity
+     * @param uriInfo the URI information for the rest system and the current request
+     * @return a summary of each principal that has access to the patient record, or {@code null} if the current user
+     *         doesn't have access to the patient or accessing the patient data fails.
+     */
+    PrincipalsRepresentation createPrincipalsRepresentation(PrimaryEntity entity, String entityType, UriInfo uriInfo);
 }

components/entity-access-rules/rest/src/main/java/org/phenotips/data/permissions/rest/PrincipalsResource.java

@@ -0,0 +1,62 @@
+/*
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see http://www.gnu.org/licenses/
+ */
+package org.phenotips.data.permissions.rest;
+
+import org.phenotips.data.permissions.rest.model.PrincipalsRepresentation;
+import org.phenotips.rest.ParentResource;
+import org.phenotips.rest.Relation;
+import org.phenotips.rest.RequiredAccess;
+
+import org.xwiki.component.annotation.Role;
+import org.xwiki.stability.Unstable;
+
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+/**
+ * Resource for retrieving information about principals that have access to the entity record, in bulk, where entity is
+ * identified by entity record's internal PhenoTips identifier.
+ *
+ * @version $Id$
+ * @since 1.4
+ */
+@Unstable("New API introduced in 1.4")
+@Role
+@Path("/{entity-type}/{entity-id}/permissions/principals")
+@Relation("https://phenotips.org/rel/principals")
+@ParentResource(PermissionsResource.class)
+public interface PrincipalsResource
+{
+    /**
+     * Retrieve information about users or groups that have any access to the entity record. If the indicated entity
+     * record doesn't exist, or if the user sending the request doesn't have the right to view the target entity record,
+     * an error is returned.
+     *
+     * @param entityType the type of entity (either "patients" or "families")
+     * @param entityId internal identifier of a entity record
+     * @return REST representation of a collection of principals
+     */
+    @GET
+    @Produces(MediaType.APPLICATION_JSON)
+    @RequiredAccess("view")
+    PrincipalsRepresentation getPrincipals(@PathParam("entity-type") String entityType,
+        @PathParam("entity-id") String entityId);
+}

components/entity-access-rules/rest/src/main/java/org/phenotips/data/permissions/rest/internal/DefaultCollaboratorResourceImpl.java

@@ -166,7 +166,7 @@ private CollaboratorRepresentation createCollaboratorRepresentation(PrimaryEntit
 
         for (Collaborator collaborator : entityAccess.getCollaborators()) {
             if (collaboratorReference.equals(collaborator.getUser())) {
-                return this.factory.createCollaboratorRepresentation(entity, collaborator);
+                return this.factory.createCollaboratorRepresentation(collaborator);
             }
         }
         // same here