doc: write up some ideas around how authz works vs desired

1 files changed, 70 insertions, 0 deletions

diff --git a/doc/share/authz/README.md b/doc/share/authz/README.md
new file mode 100644
index 0000000..6e3cc30
--- /dev/null
+++ b/doc/share/authz/README.md
@@ -0,0 +1,70 @@
+# Authz
+
+## Hierarchy
+
+How does a permission cascade down a group hierarchy?
+
+```
+Organization
+  Group A
+    * Roles
+      * Developer
+      * Maintainer
+      * Custom A
+        * base: developer
+        * permissions:
+          * admin_vulnerability: true
+            * read_vulnerability: true (implicitly)
+      * Custom B
+        * base: maintainer
+        * permissions:
+          * Doesn't really matter because Maintainer has all the permissions available via a custom role. <- Fact check this
+    Group Aa
+      Project Aa1
+      Project Aa2
+    Group Aaa
+      Project Aaa1
+      Project Aaa2
+```
+
+If a user has a membership at `Group A`, does the permissions associated with that
+membership cascade down to `Group Aa` and `Group Aaa`?
+
+## Permissions
+
+Q: What permissions do each of the standard roles have today?
+Q: Are there permissions that do not cascade down the group hierarchy?
+
+
+## Scope
+
+Q: How do we define the scope of a permission? (hierarchical?)
+
+Current:
+
+Desired:
+
+| permission | scope                                                                         | description                                         |
+| ---------- | -----                                                                         | -----------                                         |
+| `read`     | `gid://app/Organization/1`                                                    | Can read Org 1 resource                             |
+| `read`     | `gid://app/Organization/1/*`                                                  | Can read every resource below Org 1 hierarchy       |
+| `read`     | `gid://app/Organization/1/Group/1`                                            | Can read Group 1 resource                           |
+| `read`     | `gid://app/Organization/1/Group/1/*`                                          | Can read every resource below Group 1 hierarchy     |
+| `read`     | `gid://app/Organization/1/Group/1/Project/1`                                  | Can read project 1                                  |
+| `read`     | `gid://app/Project/1`                                                         | Can read project 1 resource (short circuit example) |
+| `read`     | `gid://app/Organization/1/Group/1?attributes[]=name&attributes[]=description` | Can read name and description of Group 1 resource   |
+
+Example:
+
+The following example allows the subject of the token to read all of the descendant resources of `Project 1` and `Project 2` and it can read `Project 3`.
+
+```json
+{
+  "sub": "gid://User/17",
+  "scope": [
+    "gid://app/Organization/1/Group/1/Project/1/*",
+    "gid://app/Organization/1/Group/1/Project/2/*",
+    "gid://app/Organization/1/Group/2/Project/3"
+  ]
+}
+```