docs: describe PaC

2 files changed, 38 insertions, 18 deletions

diff --git a/doc/share/authz/POLICY.md b/doc/share/authz/POLICY.md
index 2511d67..eccf362 100644
--- a/doc/share/authz/POLICY.md
+++ b/doc/share/authz/POLICY.md
@@ -1,24 +1,14 @@
 # Policy
 
-A policy is a predicate that describes if a subject can perform an action
-against a specific resource.
+> Policy is a planned system of rules and guidelines that directs users and automation to execute within purposeful boundaries.
 
-```ruby
-  policy(:parent) { predicate }
-  policy(:partner) { predicate }
-  policy(:sibling) { predicate }
-  policy(:child) { predicate }
-
-  enable(:permission, on: resource).when { parent | partner }
-```
+The parts of a policy include:
 
-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
-```
+* name: used to label the policy for future reference
+* purpose: the reason this policy exists
+* situation: the context in which the policy will be used
+* rules: individual controls or prescribed behaviours;
+* actions: action taken if a policy rule is violated
 
 ## Policy Language
 
@@ -27,7 +17,35 @@ 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.**
 
+### Policy as Code (PaC)
 
+These are policies that are written, stored, managed and interpreted as code
+artifacts.
+
+> A policy engine is a program or process that is able to ingest
+> machine-readable policies and apply them to a particular problem domain to
+> constrain the behaviour of network resources.
+
+PaC policy engine characteristics:
+
+* Ingeting machine-readable policies (PaC)
+* Applying policies to specific problem domains (data)
+* Constraining behaviors (outcomes)
+
+
+```plaintext
+ ----------
+ | Policy |---------             A
+ ----------        |            / \
+                   V           /   \
+ --------       ---------     /     \     --------------     --------
+ | Data |------>| Input |--->< match >--->| Evaluation |--->( Outcom )
+ --------       ---------     \     /     --------------     --------
+                   A           \   /
+ ---------         |            \ /
+ | Query |----------             V
+ ---------
+```
 
 ## Security Context/Scope
 
@@ -64,3 +82,4 @@ end
 
 * [Zanzibar](./ZANZIBAR.md)
 * [Dafny](https://dafny.org)
+* [Policy as Code by Jimmy Ray](https://learning.oreilly.com/library/view/policy-as-code/)
diff --git a/doc/share/authz/README.md b/doc/share/authz/README.md
index d99f1a6..b052ea8 100644
--- a/doc/share/authz/README.md
+++ b/doc/share/authz/README.md
@@ -22,9 +22,10 @@ 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 be actively supported
 * Must have concise documentation
 * Must provide ability to extend language using Ruby/Golang for describing complex policies.
+* Must have a compatible license that permits the way that we can use it.
 
 Ideally, we must be able to model the following relationships: