Merge pull request #472 from bento-platform/feat/manager/auth-permiss…

…ions-help

feat(manager): grant creation permissions help text

src/components/manager/access/GrantForm.tsx

@@ -6,6 +6,7 @@ import type { FormInstance, RadioGroupProps, RadioChangeEvent, SelectProps } fro
 import { RESOURCE_EVERYTHING, useOpenIdConfig } from "bento-auth-js";
 
 import MonospaceText from "@/components/common/MonospaceText";
+import { PERMISSIONS_HELP } from "@/modules/authz/help";
 import { useAllPermissions, useGroups } from "@/modules/authz/hooks";
 import type {
   Grant,
@@ -491,24 +492,37 @@ const PermissionsInput = ({ id, value, onChange, currentResource, ...rest }: Per
           const givenBy = pGivenBy[p.id] ?? [];
           const givenByAnother = givenBy.some((g) => checked.includes(g.id));
           const disabled = !permissionCompatibleWithResource(p, currentResource);
+          const help: ReactNode | undefined = PERMISSIONS_HELP[p.id];
           return {
             value: p.id,
             label:
-              !disabled && givenByAnother ? (
+              !!help || (!disabled && givenByAnother) ? (
                 <Popover
                   content={
-                    <span>
-                      Given by:{" "}
-                      {givenBy.map((g, gi) => (
-                        <Fragment key={g.id}>
-                          <MonospaceText>{g.id}</MonospaceText>
-                          {gi !== givenBy.length - 1 ? ", " : ""}
-                        </Fragment>
-                      ))}
-                    </span>
+                    <div style={{ maxWidth: 500 }}>
+                      {!!help && (
+                        <span>
+                          {help}
+                          {givenByAnother && <br />}
+                        </span>
+                      )}
+                      {givenByAnother && (
+                        <span>
+                          <strong>Given by:</strong>{" "}
+                          {givenBy.map((g, gi) => (
+                            <Fragment key={g.id}>
+                              <MonospaceText>{g.id}</MonospaceText>
+                              {gi !== givenBy.length - 1 ? ", " : ""}
+                            </Fragment>
+                          ))}
+                        </span>
+                      )}
+                    </div>
                   }
                 >
-                  <MonospaceText style={{ textDecoration: "underline", color: "#999" }}>{p.verb}</MonospaceText>
+                  <MonospaceText style={{ textDecoration: "underline", ...(givenByAnother ? { color: "#999" } : {}) }}>
+                    {p.verb}
+                  </MonospaceText>
                 </Popover>
               ) : (
                 <MonospaceText>{p.verb}</MonospaceText>

src/modules/authz/help.tsx

@@ -0,0 +1,119 @@
+import type { ReactNode } from "react";
+import { Typography } from "antd";
+import {
+  analyzeData,
+  createDataset,
+  createNotifications,
+  createProject,
+  deleteData,
+  deleteDataset,
+  deleteDropBox,
+  deleteProject,
+  deleteReferenceMaterial,
+  downloadData,
+  editDataset,
+  editPermissions,
+  editProject,
+  exportData,
+  ingestData,
+  ingestDropBox,
+  ingestReferenceMaterial,
+  queryData,
+  queryDatasetLevelBoolean,
+  queryDatasetLevelCounts,
+  queryProjectLevelBoolean,
+  queryProjectLevelCounts,
+  viewDropBox,
+  viewNotifications,
+  viewPermissions,
+  viewRuns,
+} from "bento-auth-js";
+
+export const PERMISSIONS_HELP: Record<string, ReactNode> = {
+  // data
+  [queryData]: "Whether the subject can access data records for the resource, e.g. phenotypic metadata, experiments.",
+  [downloadData]:
+    "Whether the subject can download data files associated with the resource, e.g., download VCFs and other " +
+    "experiment results.",
+  [deleteData]: "Whether the subject can delete data from the resource, e.g., clearing all variants.",
+  [ingestData]: "Whether the subject can ingest new data into the resource, e.g., adding new biosamples.",
+  [analyzeData]: <strong>CURRENTLY UNUSED.</strong>,
+  [exportData]: <strong>CURRENTLY UNUSED.</strong>,
+
+  // dataset
+  [editDataset]:
+    "Whether the subject can edit datasets (title, description, provenance metadata) in the specified node/project " +
+    "resource.",
+  [createDataset]: "Whether the subject can create datasets in the specified node/project resource.",
+  [deleteDataset]:
+    "Whether the subject can delete datasets from the specified node/project resource. This in turn deletes data " +
+    "inside the dataset.",
+
+  // dataset_level_boolean
+  [queryDatasetLevelBoolean]:
+    "Whether the subject can see low-count-censored yes/no answers about the data at the dataset level. The " +
+    "low-count threshold is controlled by the resource's discovery configuration file.",
+
+  // dataset_level_counts
+  [queryDatasetLevelCounts]:
+    "Whether the subject can see low-count-censored count answers about the data at the dataset level. The low-count " +
+    "threshold is controlled by the resource's discovery configuration file.",
+
+  // drop_box
+  [viewDropBox]:
+    "Whether the subject can see the instance-wide drop box (staging area) for files. This permission is only valid " +
+    "for the Everything resource.",
+  [ingestDropBox]: "Whether the subject can upload files / create folders in the drop box.",
+  [deleteDropBox]: "Whether the subject can delete files / folders from the drop box.",
+
+  // notifications
+  [viewNotifications]:
+    "Whether the subject can view notifications. Currently, this only works on the instance level; any " +
+    "project/dataset context is ignored.",
+  [createNotifications]: <strong>CURRENTLY UNUSED.</strong>,
+
+  // permissions
+  [viewPermissions]: "Whether the subject can view permissions on this resource, or any given sub-resource.",
+  [editPermissions]: (
+    <>
+      Whether the subject can edit permissions which apply to only this resource, or any sub-resources. For example, a
+      user with the <Typography.Text code={true}>edit:permissions</Typography.Text> permission on just a specific
+      dataset cannot edit grants for the project which contains this dataset.
+    </>
+  ),
+
+  // private_portal
+  "view:private_portal": (
+    <>
+      <strong>LEGACY PERMISSION.</strong> Whether the subject can view the private data portal, as well as POSSIBLY
+      SENSITIVE data in services which have not been converted to the new Bento authorization system.
+    </>
+  ),
+
+  // project
+  [editProject]:
+    "Whether the subject can edit details about the project: title, description, and other provenance metadata.",
+  [createProject]: "Whether the subject can create a new project in the instance.",
+  [deleteProject]: "Whether the subject can delete a project from the instance.",
+
+  // project_level_boolean
+  [queryProjectLevelBoolean]:
+    "Whether the subject can see low-count-censored yes/no answers about the data at the project level. The " +
+    "low-count threshold is controlled by the project/instance's discovery configuration file.",
+
+  // project_level_counts
+  [queryProjectLevelCounts]:
+    "Whether the subject can see low-count-censored count answers about the data at the project level. The low-count " +
+    "threshold is controlled by the project/instance's discovery configuration file.",
+
+  // reference_material
+  [ingestReferenceMaterial]:
+    "Whether the subject can ingest reference material (genomes, genome features) into the instance. Note that any " +
+    "reference material ingested is public, and available to anyone including anonymous users.",
+  [deleteReferenceMaterial]:
+    "Whether the subject can delete reference material (genomes, genome features) from the instance.",
+
+  // runs
+  [viewRuns]:
+    "Whether the subject can view workflow runs. Currently only works when applied to the Everything resource!",
+};