docs: add diagram for boarding a plane

1 files changed, 43 insertions, 1 deletions

diff --git a/share/man/ENVOY.md b/share/man/ENVOY.md
index c158f4d..c0b6d02 100644
--- a/share/man/ENVOY.md
+++ b/share/man/ENVOY.md
@@ -83,7 +83,7 @@ understand whether a rigorous authentication and authorization check is
 warranted or not. The passenger is responsible for obtaining a passport,
 boarding pass, bus ticket from trusted and reputable authorities.
 
-```
+```sequence
  +-----------+   +------------+             +-----+
  | Passenger |   | Bus Driver |             | Bus |
  +-----------+   +------------+             +-----+
@@ -116,3 +116,45 @@ carry a token that awards them access to the resource. In this scenario the
 passenger could give the token to someone else (for example a child) so that
 they can access the resource. The security context of this resource does not
 warrant the need for authentication and only requires authorization.
+
+```uml
++-----------+            +----------------+    +----------------+  +-------+
+| Passenger |            | Security Agent |    | Boarding Agent |  | Plane |
++-----------+            +----------------+    +----------------+  +-------+
+   |                              |                    |               |
+   |-- request access to gate  -->|                    |               |
+   |<--- request boarding pass ---|                    |               |
+   |                              |                    |               |
+   |-- present boarding pass ---->|                    |               |
+   |                              |-> validate pass    |               |
+   |<-- allow access to gate -----|                    |               |
+   |                              |                    |               |
+   |-- request access to board plane ----------------->|               |
+   |<--- request passport -----------------------------|               |
+   |-- present passport ------------------------------>|               |
+   |<--- request boarding pass ------------------------|               |
+   |-- present boarding pass ------------------------->|               |
+   |<----- allow access to board plane                 |               |
+   |                              |                    |               |
+   |--- board plane  ------------------------------------------------->|
+```
+
+To board a plane you must pass through more security checks before you can
+access the airplane. That is because flying in an airplane is a high security
+context that requires additional checks to ensure the safety of everyone and the
+risk of allowing access to a bad actor has more severe consequences. To board
+the airplane you must pass through the security checkpoint by presenting a valid
+boarding pass for a flight. This check ensures that we do not allow people into
+the gate that do not have a valid pass. A valid pass is one that hasn't already
+been used, is for a flight that is set to take off in the future and is for a
+known and registered airline. Depending on whether the flight is a domestic or
+international flight the gate may require other forms of proof of access. Once
+the passenger has made it to the gate they are required to provide a passport
+and boarding pass to an airline agent before they are allowed to board the
+aircraft. This ensures that everyone who is aboard the airplane is known ahead
+of time and that known bad actors are not allowed to board the aircraft. The
+airline agent performs an authentication AND authorization check. The airplane
+is a metaphor for a high security context that the operators of the airplane
+understand. The credit card company and each intermediate authority that was
+used to ensure entry do not determine the access controls for gaining entry into
+the plane.