docs: add a diagram of boarding a bus

1 files changed, 34 insertions, 0 deletions

diff --git a/share/man/ENVOY.md b/share/man/ENVOY.md
index 3f610df..c158f4d 100644
--- a/share/man/ENVOY.md
+++ b/share/man/ENVOY.md
@@ -82,3 +82,37 @@ and the operator of the API understand the security context the best. They
 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.
+
+```
+ +-----------+   +------------+             +-----+
+ | Passenger |   | Bus Driver |             | Bus |
+ +-----------+   +------------+             +-----+
+   |                    |                      |
+   |-- request access -->                      |
+   |                    |                      |
+   |<- request ticket --|                      |
+   |                    |                      |
+   |-- present ticket --> authorize (bus #, expiration, fake/legit?)
+   |                    |                      |
+   |<--- grant access --|                      |
+   |                    |                      |
+   |--- board bus ---------------------------->|
+
+--------------------------------------------------------
+   |<--- deny access --|
+```
+
+The Bus # indicates the canonical identifier for the resource and
+this is similar to accessing a resource exposed via a REST/GraphQL
+API. The expiration check ensures that the same token cannot be re-used
+indefinitely and that the access granted by the ticket is limited in
+scope to prevent abuse of the resource and this is similar to ensuring
+that a JWT cannot be used indefinitely. The check to make sure that the
+ticket is legitimate and issued from a trusted authority is similar to
+a digital signature check. In this example, the bus driver does not need to
+authenticate the passenger by verifying that they are who they say they are. The
+bus driver does not care. The bus driver only cares about whether or not they
+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.