docs: extract a page to describe policy and FAQ

4 files changed, 75 insertions, 8 deletions

diff --git a/doc/share/authz/FAQ.md b/doc/share/authz/FAQ.md
new file mode 100644
index 0000000..3d560f1
--- /dev/null
+++ b/doc/share/authz/FAQ.md
@@ -0,0 +1,6 @@
+# Frequently Asked Question (FAQ)
+
+* Q: Are there permissions that do not cascade down the group hierarchy?
+* 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?
diff --git a/doc/share/authz/POLICY.md b/doc/share/authz/POLICY.md
new file mode 100644
index 0000000..30cca5f
--- /dev/null
+++ b/doc/share/authz/POLICY.md
@@ -0,0 +1,51 @@
+# Policy
+
+A policy is a predicate that describes if a subject can perform an action
+against a specific resource.
+
+```ruby
+  policy(:parent) { predicate }
+  policy(:partner) { predicate }
+  policy(:sibling) { predicate }
+  policy(:child) { predicate }
+
+  enable(:permission, on: resource).when { parent | partner }
+```
+
+Authorizaion uses policies to determine if a subject in a specific context is
+authorized to perform an action against a resource.
+
+```ruby
+  def can?(subject, action, resource)
+  end
+```
+
+## Policy Language
+
+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.**
+
+## Example
+
+The following hierarchy will be used as the basis for expression policy.
+
+```ruby
+class Organization
+  has_many :groups
+end
+
+class Group
+  belongs_to :organization
+  has_many :projects
+end
+
+class Project
+  belongs_to :group
+  has_many :issues
+end
+
+class Issue
+end
+```
diff --git a/doc/share/authz/README.md b/doc/share/authz/README.md
index 9638c83..b750481 100644
--- a/doc/share/authz/README.md
+++ b/doc/share/authz/README.md
@@ -9,6 +9,23 @@ identity of subjects and/or groups to which they belong.
 * Relationship-Based Access Control ([ReBAC](./ReBAC.md))
 * Attribute-Based Access Control ([ABAC](./ABAC.md))
 
+## Policy
+
+* [What is a policy?](./POLICY.md)
+* Policy Language Evaluation
+  * Zanzibar
+  * [Dafny](https://dafny.org/)
+  * Cedar
+  * Casbin
+
+Criteria for evaluating policy languages:
+
+* Must be able to model different types of access control models (RBAC, ReBAC, ABAC)
+* Must be able to perform static analysis
+* Must be well supported
+* Must have concise documentation
+* Must provide ability to extend language using Ruby/Golang for describing complex policies.
+
 ## Organizational Hierarchy
 
 How does a permission cascade down a group hierarchy?
@@ -39,15 +56,8 @@ Organization
 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?)
-
 1. Single resource
 1. Nested resources
 1. Individual Attributes on a resource
diff --git a/doc/share/authz/ReBAC.md b/doc/share/authz/ReBAC.md
index ee82ba2..95700c6 100644
--- a/doc/share/authz/ReBAC.md
+++ b/doc/share/authz/ReBAC.md
@@ -98,7 +98,7 @@ parent context.
 
 ## Policy Language
 
-It is desirable to have a policy language for specifying ReBAC policies.
+It is desirable to have a [policy language](./POLICY.md) for specifying ReBAC policies.
 
 A policy language facilitates: