Merge pull request #60 from tkhq/update-docs-policy-clarifications

updating some language/diagrams around policies and email recovery

docs/getting-started/email-recovery.md

@@ -28,10 +28,15 @@ Once a user receives a recovery email, recovery credential _decryption_ needs to
 
 ## Authorization
 
-Authorization for email recovery is based on our usual activity authorization: our [policy engine](../policy-management/Policy-overview.md) controls who can and cannot execute recovery-related activities.
-* `ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY` can be performed by the root user or by any user in an organization if authorized by policy. The activity can target any user in this organization **or any sub-organization user**. The activity will fail if a parent user tries to initiate recovery for a sub-organization which has [opted out of email recovery](#opting-out-of-email-recovery).
+Authorization for email recovery is based on our usual activity authorization: our [policy engine](../policy-management/Policy-overview.md) controls who can and cannot execute recovery-related activities. 
+* `ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY` can be performed by the root user or by any user in an organization if authorized by policy. The activity can target **any user** in this organization **or any sub-organization user**. The activity will fail if a parent user tries to initiate recovery for a sub-organization which has [opted out of email recovery](#opting-out-of-email-recovery).
 * `ACTIVITY_TYPE_RECOVER_USER` should be signed by the recovery credential sent via email. Even if not explicitly allowed by policy, a user is always able to add credentials to their own user. This includes adding a new authenticator when authenticated with a recovery credential. In other words, no special policy is needed to make this work: users are able to recover out-of-the-box.
 
+<p style={{textAlign: 'center'}}>
+    <img src="/img/diagrams/email_recovery_authorization.png" width="500" height="200"/>
+</p>
+
+
 Important note: recovery credentials automatically expire after **30 minutes** and are overridden when multiple `INIT_USER_EMAIL_RECOVERY` activities target the same user. Only the most recent recovery credential is valid.
 
 ## Email recovery in your sub-organizations

docs/policy-management/Policy-overview.md

@@ -30,14 +30,16 @@ All policies defined within an Organization are evaluated on each request. The i
 1. If a quorum of root users takes the action, the final outcome is `OUTCOME_ALLOW`
 2. Else if any applicable policy has `EFFECT_DENY`, the final outcome is `OUTCOME_DENY`. This is also referred to as "explicit deny."
 3. Else if at least one applicable policy has `EFFECT_ALLOW`, then the final outcome is `OUTCOME_ALLOW`
-4. Else the final outcome is `OUTCOME_DENY`. This is also referred to as "implicit deny."
+4. Else the final outcome is `OUTCOME_DENY`. This is also referred to as "implicit deny." In cases of conflicts, `EFFECT_DENY` always wins.
 
 Stated differently:
 
 <p style={{textAlign: 'center'}}>
   <img src="/img/diagrams/policy_overview.png" alt="policy_overview" width="500px" />
 </p>
 
-- Root users bypass any policies
-- Otherwise, all actions on Turnkey are implicitly denied by default. They have to be explicitly allowed by a policy.
-- In cases of conflicts, `EFFECT_DENY` always wins
+Almost all actions on Turnkey are implicitly denied by default. There are a few exceptions, however: 
+- Root users bypass any policies.
+- All users have implicit GET (read) permissions in their own Organization and any associated Sub-Organizations. 
+- All users have implicit permission to change their own credentials.
+- All users have implicit permission to approve an activity if they were included in consensus (i.e., a user specified as part of the consensus required to approve a SIGN_TRANSACTION activity does not need separate, explicit permission to sign transactions).