docs: add notes on ABAC and weakness of RBAC

7 files changed, 166 insertions, 99 deletions

diff --git a/doc/share/authz/ABAC.md b/doc/share/authz/ABAC.md
index bfe14041..ed6e4ada 100644
--- a/doc/share/authz/ABAC.md
+++ b/doc/share/authz/ABAC.md
@@ -6,10 +6,44 @@
 > (RBAC) using appropriate attributes such as access control lists, security
 > labels and roles respectively. [5]
 
+ABAC has been studied for a long time and many different formal models have been
+proposed.
+
+ABAC is a logical access control model that is distinguishable because it
+controls access to objects by evaluating rules against the attributes of
+entities (subject and object), operations, and the environment relevant to a
+request.
+
+As new subjects join the organization, rules and objects do not need to be
+modified. As long as the subject is assigned the attributes necessary for access
+to the required objects, no modifications to existing rules or object attributes
+are required.
+
+There can be three types of attributes:
+
+1. Atomic-values or single valued attribute:
+1. Set-valued or multi-valued attribute:
+1. Structured Attribute:
+
+Attributes can be either:
+
+* Entity Attribute: a thing that can be distinctly identified.
+* Non-entity Attribute: whose range is not defined on the set of entities in the
+  system.
+
+The range of an attribute is bounded or not:
+
+* Finite Domain Attribute: Range of this attribute type is a finite set of
+  attribute value.
+* Infinite Domain Attribute: Range of this attribute type is a countably
+  infinite set of attribute values.
+
 ## See Also
 
 * [Classifying and Comparing Attribute-Based and Relationship-Based Access Control][5]
 * [A Capability-based Distributed Authorization System to Enforce Context-aware Permission Sequences][6]
+* [Guide to Attribute Based Access Control (ABAC) Definition and Considerations][7]
 
 [5]: https://dl.acm.org/doi/pdf/10.1145/3029806.3029828
 [6]: https://dl.acm.org/doi/pdf/10.1145/3532105.3535014
+[7]: https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-162.pdf
diff --git a/doc/share/authz/DESIGN.md b/doc/share/authz/DESIGN.md
new file mode 100644
index 00000000..8bf53475
--- /dev/null
+++ b/doc/share/authz/DESIGN.md
@@ -0,0 +1,61 @@
+# Design
+
+## Current
+
+## Proposed
+
+### Option 1
+
+| 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": {
+    "read": [
+      "gid://app/Organization/1/Group/1/Project/1/*",
+      "gid://app/Organization/1/Group/1/Project/2/*",
+      "gid://app/Organization/1/Group/2/Project/3"
+    ]
+  }
+}
+```
+
+### Option 2
+
+Encode access and scope directly into the name of the permission.
+
+| permission                                                               | description                                         |
+| ----------                                                               | -----------                                         |
+| `read:organization:1`                                                    | Can read Org 1 resource                             |
+| `read:organization:1:*`                                                  | Can read every resource below Org 1 hierarchy       |
+| `read:organization:1:group:*`                                            | Can read Group 1 resource                           |
+| `read:organization:1:group:1:*`                                          | Can read every resource below Group 1 hierarchy     |
+| `read:organization:1:group:1:project:1`                                  | Can read project 1                                  |
+| `read:project:1`                                                         | Can read project 1 resource (short circuit example) |
+| `read:organization:1:group:1:attributes[]=name&attributes[]=description` | Can read name and description of Group 1 resource   |
+
+Example:
+
+```json
+{
+  "sub": "gid://User/17",
+  "scope": [
+    "read:organization:1:group:1:project:1:*",
+    "read:organization:1:group:1:project:2:*",
+    "read:organization:1:group:2:project:3"
+  ]
+}
+```
diff --git a/doc/share/authz/FAQ.md b/doc/share/authz/FAQ.md
index 3d560f1f..8e73beb2 100644
--- a/doc/share/authz/FAQ.md
+++ b/doc/share/authz/FAQ.md
@@ -4,3 +4,30 @@
 * Q: How do we define the scope of a permission? (hierarchical?)
 * Q: What is the unique identifier for each security principal across service boundaries? (i.e. bigint, ulid, uuid, email)
 * Q: What permissions do each of the standard roles have today?
+* Q: 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
+```
+
+* Q: If a user has a membership at `Group A`, does the permissions associated with that
+membership cascade down to `Group Aa` and `Group Aaa`?
diff --git a/doc/share/authz/POLICY.md b/doc/share/authz/POLICY.md
index 39a1128e..207c1cc3 100644
--- a/doc/share/authz/POLICY.md
+++ b/doc/share/authz/POLICY.md
@@ -27,6 +27,12 @@ A policy language facilitates:
 1. the specification of composite policies, which in turn forms the basis of trust delegation.
 1. **the static analysis of policies and system configuration.**
 
+## Security Context/Scope
+
+1. Single resource
+1. Nested resources
+1. Individual Attributes on a resource
+
 ## Example
 
 The following hierarchy will be used as the basis for expression policy.
diff --git a/doc/share/authz/RBAC.md b/doc/share/authz/RBAC.md
index e2514365..cbf05e03 100644
--- a/doc/share/authz/RBAC.md
+++ b/doc/share/authz/RBAC.md
@@ -65,6 +65,33 @@ reason, the practical approach is for transactions to be certified and
 trusted. If transactions must be trusted then _access control can be incorporated
 directly into each transaction_.
 
+RBAC makes a decision based on the subject's association with a role. RBAC does
+not easily support multi-factor decisions. RBAC role assignments tend to be
+based upon more static organizational positions, presenting challenges in
+certain RBAC architectures where dynamic access control decisions are required
+(.e.g. `CI_JOB_TOKEN`). Trying to implement these kidns of access control
+decisoins would require the creation of numerous roles that are ad hoc and
+limited in membership, leading to what is often termed "role explosion".
+
+ABAC avoids the need for explicit authorizations to be directly assigned to
+individual subjects prior to a request to perform an operation on the object.
+
+> ABAC: An access control method where subject requests to perform operations on
+> objets are granted or denied based on assigned attributes of the subject,
+> assigned attributes of the object, environment conditions, and a set of
+> policies that are specified in terms of those attributes and conditions.
+
+* Attributes: characteristics of the subject, object, or environment conditions.
+* Subject: is a human or or non-person entity (NPE) that issues access requests
+  to perform operations on objects.
+* Object: a system resource for which access is managed by the ABAC system
+* Operation: is the execution of a function at the request of a subject upon an
+  object. (e.g. read, write, edit, delete, copy, execute and modify)
+* Policy: is the representation of rules or relationships that makes it possible
+  to determine if a requested access should be allowed.
+* Environment conditions: operational or situational context in which the access
+  request occurs.
+
 ## See also
 
 * [Role-Based Access Controls](https://csrc.nist.gov/files/pubs/conference/1992/10/13/rolebased-access-controls/final/docs/ferraiolo-kuhn-92.pdf)
diff --git a/doc/share/authz/README.md b/doc/share/authz/README.md
index 7ab81669..d99f1a67 100644
--- a/doc/share/authz/README.md
+++ b/doc/share/authz/README.md
@@ -28,103 +28,10 @@ Criteria for evaluating policy languages:
 
 Ideally, we must be able to model the following relationships:
 
-* `user-to-resource`
-* `resource-to-resource`
+| type                   | required     |
+| ----                   | --------     |
+| `user-to-resource`     | required     |
+| `resource-to-resource` | required     |
+| `user-to-user`         | not required |
 
-Note that `user-to-user` relationships are not currently represented in the existing access control model.
-
-## Organizational 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`?
-
-## Scope
-
-1. Single resource
-1. Nested resources
-1. Individual Attributes on a resource
-
-### Current:
-
-### Desired:
-
-#### Option 1
-
-| 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": {
-    "read": [
-      "gid://app/Organization/1/Group/1/Project/1/*",
-      "gid://app/Organization/1/Group/1/Project/2/*",
-      "gid://app/Organization/1/Group/2/Project/3"
-    ]
-  }
-}
-```
-
-#### Option 2
-
-Encode access and scope directly into the name of the permission.
-
-| permission                                                               | description                                         |
-| ----------                                                               | -----------                                         |
-| `read:organization:1`                                                    | Can read Org 1 resource                             |
-| `read:organization:1:*`                                                  | Can read every resource below Org 1 hierarchy       |
-| `read:organization:1:group:*`                                            | Can read Group 1 resource                           |
-| `read:organization:1:group:1:*`                                          | Can read every resource below Group 1 hierarchy     |
-| `read:organization:1:group:1:project:1`                                  | Can read project 1                                  |
-| `read:project:1`                                                         | Can read project 1 resource (short circuit example) |
-| `read:organization:1:group:1:attributes[]=name&attributes[]=description` | Can read name and description of Group 1 resource   |
-
-Example:
-
-```json
-{
-  "sub": "gid://User/17",
-  "scope": [
-    "read:organization:1:group:1:project:1:*",
-    "read:organization:1:group:1:project:2:*",
-    "read:organization:1:group:2:project:3"
-  ]
-}
-```
+Note: `user-to-user` relationships are not in the current access control model.
diff --git a/doc/share/authz/ReBAC.md b/doc/share/authz/ReBAC.md
index 17d51a2e..9202e0c4 100644
--- a/doc/share/authz/ReBAC.md
+++ b/doc/share/authz/ReBAC.md
@@ -42,6 +42,11 @@ is fundamental to ReBAC (e.g. friend of friend).
 Recently, researchers have proposed extended ReBAC models applicable to other
 computing systems beyond OSNs.
 
+Most ReBAC models consider `user-to-user` and possibly `user-to-resource`
+relationshps. Very few consider `resource-to-resource` relationships. Models
+that consider `resource-to-resource` relationships typically do so through
+users.
+
 ## Access Control Policies
 
 Let `U` be the set of all users in the system.