From b6a43cd37cd458ef46700ed45ed2c58cf267f4cd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=9C=A8=20Audrey=20=E2=9C=A8?= <audrey@audreyality.com>
Date: Wed, 2 Jul 2025 15:20:08 -0400
Subject: [PATCH] document auth flows

---
 .../send/send-access/authentication-flow.md   | 75 +++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 apps/web/src/app/tools/send/send-access/authentication-flow.md

diff --git a/apps/web/src/app/tools/send/send-access/authentication-flow.md b/apps/web/src/app/tools/send/send-access/authentication-flow.md
new file mode 100644
index 00000000000..7fa253af3bb
--- /dev/null
+++ b/apps/web/src/app/tools/send/send-access/authentication-flow.md
@@ -0,0 +1,75 @@
+# Send Authentication Flows
+
+In the below diagrams, activations represent client control flow.
+
+## Public Sends
+
+Anyone can access a public send. The token endpoint automatically issues a token. It never issues a challenge.
+
+```mermaid
+sequenceDiagram
+    participant Visitor
+    participant TryAccess as try-access.component
+    participant SendToken as send-token API
+    participant ViewContent as view-content.component
+    participant SendAccess as send-access API
+
+    Visitor->>TryAccess: Navigate to send URL
+    activate TryAccess
+    TryAccess->>SendToken: Request anonymous access token
+    SendToken-->>TryAccess: OK + Security token
+    TryAccess->>ViewContent: Redirect with token
+    deactivate TryAccess
+    activate ViewContent
+    ViewContent->>SendAccess: Request send content (with token and key)
+    SendAccess-->>ViewContent: Return send content
+    ViewContent->>Visitor: Display send content
+    deactivate ViewContent
+```
+
+## Password Protected Sends
+
+Password protected sends redirect to a password challenge prompt.
+
+```mermaid
+sequenceDiagram
+    participant Visitor
+    participant TryAccess as try-access.component
+    participant PasswordAuth as password-authentication.component
+    participant SendToken as send-token API
+    participant ViewContent as view-content.component
+    participant SendAccess as send-access API
+
+    Visitor->>TryAccess: Navigate to send URL
+    activate TryAccess
+    TryAccess->>SendToken: Request anonymous access token
+    SendToken-->>TryAccess: Unauthorized + Password challenge
+    TryAccess->>PasswordAuth: Redirect with send ID and key
+    deactivate TryAccess
+    activate PasswordAuth
+    PasswordAuth->>Visitor: Request password
+    Visitor-->>PasswordAuth: Enter password
+    PasswordAuth->>SendToken: Request access token (with password)
+    SendToken-->>PasswordAuth: OK + Security token
+    deactivate PasswordAuth
+    activate ViewContent
+    PasswordAuth->>ViewContent: Redirect with token and send key
+    ViewContent->>SendAccess: Request send content (with token)
+    SendAccess-->>ViewContent: Return send content
+    ViewContent->>Visitor: Display send content
+    deactivate ViewContent
+```
+
+## Send Access without token
+
+Visiting the view page without a token redirects to a try-access flow, above.
+
+```mermaid
+sequenceDiagram
+    participant Visitor
+    participant ViewContent as view-content.component
+    participant TryAccess as try-access.component
+
+    Visitor->>ViewContent: Navigate to send URL (with id and key)
+    ViewContent->>TryAccess: Redirect to try-access (with id and key)
+```