doc: split access control docs into separate files

1 files changed, 46 insertions, 145 deletions

diff --git a/doc/share/authz/README.md b/doc/share/authz/README.md
index aea6db1..9638c83 100644
--- a/doc/share/authz/README.md
+++ b/doc/share/authz/README.md
@@ -5,141 +5,9 @@
 Access Controls provide a means of restricting access to objects based on the
 identity of subjects and/or groups to which they belong.
 
-### Role-Based Access Control (RBAC)
-
-Assigns permissions to roles, which are collections of permissions related to specific job functions.
-
-This style of access control aligns with how humans organize themselves within
-organizations by assigning job functions to roles. This model is simple and
-aligns well with how humans operate within their job function.
-
-This model also helps to align security objectives with higher level
-organizational policy (.e.g. ethics, privacy, administration). This type of
-model requires centralized control and enforcement.
-
-> The act of granting membership and specifying transactions for a role is loosely
-> analogous to the process of clearing users (granting membership) and the
-> labeling (associate operation sensitivities) of objects ... - Role-Based Access Controls by Ferraiolo, Kuhn Et el.
-
-> A role can be thought of as a set of transactions that a user or set of users
-> can perform within the context of an organization. - Role-Based Access Controls by Ferraiolo, Kuhn Et el.
-
-Roles are group oriented and they provide a means of naming and describing
-many-to-many relationships between individuals and rights.
-
-1. For each subject, the active role is the one that the subject is currently using:
-
-    ```
-    AR(s: subject) = { the active role for subject s}.
-    ```
-
-2. Each subject may be authorized to perform one or more roles:
-
-    ```
-    RA(s: subject) = { authorized roles for subject s }.
-    ```
-
-3. Each role may be authorized to perform one or more transactions:
-
-    ```
-    TA(r: role) = { transactions authorized for role r}.
-    ```
-
-4. Subjets may execute transactions. The predicate `exec(s,t)` is true if
-   subject `s` can execute transaction `t` at the current time, otherwise it is
-   false:
-
-    ```
-    exec(s :subject, t: tran) = true iff subject `s` can execute transaction `t`
-    ```
-
-Three basic rules are required:
-
-1. Role assignment: A subject can execute a transaction only if the subject has
-   selected or been assigned a role
-2. Role authorization: A subject's active role must be authorized for the
-   subject
-3. Transaction authorization: A subject can execute a transaction only if the
-   transaction is authorized for the subject's active role
-
-Another user of RBAC is to support integrity. One aspect of integrity is a
-requirement that data and processes be modified only in authorized ways by
-authorized users.
-
-The problem of determining whether data have been modified only in authorized
-ways can be as complex as the transaction that did the modification. For this
-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_.
-
-#### 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)
-
-### Relationship-Based Access Control (ReBAC)
-
-> Authorization decisions are based on the relationship between the resource owner
-> and the resource accessor in a social network maintained by the protection
-> system.
-
-A Social Network System (SNS) maintains a social network for at least two reason:
-
-1. It is used by the users to navigate the information space of the system
-2. The social network is used as a basis for formulating the access control
-   policies of user contributed resources.
-
-Access Control Paradigm:
-
-1. the explicit tracking of one or more social networks by the protection system
-1. the expression of access control policies in terms of the relationship
-   between the resource owner and the resource accessor
-
-Suited for domains in which relationship and authorization decisions are from
-the structure of trust that is inherent in the application domain rather than
-subjective assessment of users.
-
-It is more natural to base authz decisions on whether the resource owner and
-accessor are in a particular kind of relationship.
-
-In a standard RBAC system, when a permission `p` is assigned to role `R`, we are
-essentially formulating the following policy: `grant p to user u if R(u)`.
-
-PriMA is another recently proposed privacy protection mechanism for SNSs.
-
-Policy
-
-Let `U` be the set of all users in the system.
-Accesses are directed against resources. A resource may represent one or more
-objects or certain system operations. Let `R` be the set of resources protected
-by the SNS. A typical member of `R` is denoted by `r`.
-
-Assocated with every access request are therefore the following:
-
-* a protected resource that is being accessed
-* the owner of that resource
-* the accessor of that resource who requests access.
-
-Owner of a resource implies that the accessor must be in a specific kind of
-relationship with the owner in order be granted. Huh?
-
-Associated with every resource is an `access control policy`.
-Policy is modeled as a ternary predicate: `U x U x G(U, I) => {0, 1}`.
-
-A protection system N is a 7-tuple (I, U, R, C, C0, policy, owner) where:
-
-* `I` is the set of relation identifiers (See my question in the README about resource identifiers in our system)
-* `U` is a finite set of users in the system
-* `R` is a finite set of resources to be protected by the system.
-* `C` is a _infinite_ universe of `access contexts`.
-  * `C0` is the root context. (* Could this be the root `Organization` that a `User` belongs to?)
-* `R => PP(U, I)` assigns a policy predicate to every resource in the system. (This means that every resource is addressable through a universal identifier, right? Goodbye `bigint`? Yay!)
-* `owner: R -> U` is a function that assigns an owner to every resource in the system.
-
-References
-
-* [Relationship-Based Access Control: Protection Model and Policy Language by Philip W. L. Fong](https://cspages.ucalgary.ca/~pwlfong/Pub/codaspy2011.pdf)
-
-### Attribute-Based Access Control (ABAC)
+* Role-Based Access Control ([RBAC](./RBAC.md))
+* Relationship-Based Access Control ([ReBAC](./ReBAC.md))
+* Attribute-Based Access Control ([ABAC](./ABAC.md))
 
 ## Organizational Hierarchy
 
@@ -173,17 +41,22 @@ 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?
-
+* 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?)
+* Q: How do we define the scope of a permission? (hierarchical?)
 
-Current:
+1. Single resource
+1. Nested resources
+1. Individual Attributes on a resource
 
-Desired:
+### Current:
+
+### Desired:
+
+#### Option 1
 
 | permission | scope                                                                         | description                                         |
 | ---------- | -----                                                                         | -----------                                         |
@@ -202,11 +75,39 @@ The following example allows the subject of the token to read all of the descend
 ```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": [
-    "gid://app/Organization/1/Group/1/Project/1/*",
-    "gid://app/Organization/1/Group/1/Project/2/*",
-    "gid://app/Organization/1/Group/2/Project/3"
+    "read:organization:1:group:1:project:1:*",
+    "read:organization:1:group:1:project:2:*",
+    "read:organization:1:group:2:project:3"
   ]
 }
 ```
-