From d27a02c53b244c84dfaacb42f03d3fc61209bb29 Mon Sep 17 00:00:00 2001
From: mo khan <mo@mokhan.ca>
Date: Mon, 26 May 2025 12:14:31 -0600
Subject: docs: add a diagram of boarding a bus

---
 share/man/ENVOY.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

(limited to 'share')

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.
-- 
cgit v1.2.3