sequence diagrams: registration, upload, and list (#119)

* sequence diagrams: registration, upload, and list

* add todos file for sequences

spec/sequences/participants.md

@@ -0,0 +1,31 @@
+## Participants
+
+### Alice
+
+Normal human. Uses web browser to run recipe sharing app, and upload recipes and photos.
+
+### Biometric
+
+Manages non-extractable keypairs via touch / face ID or other factor.
+
+### Email Client
+
+We link the DID to your account by clicking a link sent to your email address.
+
+### AppUI
+
+A recipe app front-end, displays recipes and photos of recipes, allows creating and sharing new ones. Could be web or mobile app.
+
+### Keyring
+
+Signing engine using Alice's private keys stored on Alice's biometric device, managed via the keyring website origin, and accessed via web browser. 
+
+> (Some Keyring stuff in here is w3up client... we should probably split them accurately to reflect the real thing.) --- @jchris
+
+### AppServer
+
+Traditonal web2 architecture. Maybe it's lambdas or an app server.
+
+### Storage
+
+The web3.storage service, w3up and w3access APIs.

spec/sequences/registration.md

@@ -0,0 +1,81 @@
+Regisitration is different depending on whether the app implements user-pays or app-pays storage payment models.
+
+# Payment models
+
+The two basic models are **user pays** and **app pays**. One is low-commitment for the developer, the other is invisible to the user. More nuanced hybrid models are also possible.
+
+## User pays (transparent to developer)
+
+In the default case, when a developer adds w3ui components to their application, the user is prompted to create a new (or link to an existing) account with web3.storage, where uploads are stored. When the user exceeds free plan usage, they will be prompted to provide a payment method.
+
+### Registration on first run (user pays)
+
+```mermaid
+sequenceDiagram
+    participant Biometric
+    participant Email Client
+    participant AppUI
+    participant Keyring
+    participant AppServer
+    participant Storage
+    
+    Note over AppServer, Storage: "The Cloud"
+    Note over Biometric, Keyring: Alice's  Device
+    Note over Biometric: Biometric <br>is optional
+    
+    AppUI ->> AppServer: Fetch web UI
+    AppServer -->> AppUI: HTML content
+    Note over AppUI: Running app
+    
+    AppUI ->> Keyring: Create DID
+    Keyring ->> Biometric: New key please
+    Note over Biometric: Scan face or <br>thumb and generate <br>private key.
+    Biometric -->> Keyring: Here's a ref to it
+    Note over Keyring: Collect email
+    Keyring ->> Storage: Link this email to this DID
+    Storage ->> Email Client: Send email with validation link
+    Email Client -->> Storage: Alice clicks the validation link
+    Storage -->> Keyring: Your DID is linked to your email, <br>choose from these accounts or create a new one
+    Note over Keyring: Choose account
+    Keyring -->> AppUI: Your DID can upload now
+    Note over AppUI: Store DID in session<br>Should this be earlier?
+```
+
+> The word "account" in the "Choose account" box is confusing. Since your billing account (email-level grouping) can have very many of these (roughly one per app). And your keyring identity can have access to these namespaces without paying for them. So maybe we call them "buckets" or "containers" or "apps" or "namespaces". Maybe they are the same thing we give w3names to? --- @jchris 
+
+## App pays (transparent to user)
+
+This assumes the App Server has already established a Storage account, and has access to private key signing capabilities (perhaps via an embedded web3.storage keyring). The servers's account will delegate access to user DIDs.
+
+### Registration on first run (app pays)
+
+
+```mermaid
+sequenceDiagram
+    participant Biometric
+    participant AppUI
+    participant Keyring
+    participant AppServer
+    
+    Note over AppServer: "The Cloud"
+    Note over Biometric, Keyring: Alice's  Device
+    Note over Biometric: Biometric <br>is optional
+    
+    AppUI ->> AppServer: Fetch web UI
+    AppServer -->> AppUI: HTML content
+    Note over AppUI: Running app
+    
+    AppUI ->> Keyring: Create DID
+    Keyring ->> Biometric: New key please
+    Note over Biometric: Scan face or <br>thumb and generate <br>private key.
+    Biometric -->> Keyring: Here's a ref to it
+    Keyring -->> AppUI: Here is an unlinked DID
+    AppUI ->> AppServer: Please delegate storage access to this DID 
+    Note over AppServer: Validate user session<br>& sign delegation
+    AppServer -->> AppUI: Here's a delegation so your DID can upload now
+        Note over AppUI: Store DID in session<br>Should this be earlier?
+    
+```
+
+> It might make sense to detail out the AppServer interactions with the AppServer Keyring. Currently the details on the app server delegation are elided.
+

spec/sequences/todo.md

@@ -0,0 +1,5 @@
+# Sequences to add coverage for
+
+* Flow for the app server registering the app account
+* Flow for the app server to list users uploads in app-pays mode
+* Session re-establishment flows for when delegations expire

spec/sequences/upload-and-list.md

@@ -0,0 +1,76 @@
+Upload and list are basically the same regardless of which payment model is used.
+
+## Same flow whether app or user pays
+
+Once the AppUI has established a valid delegation for uploading, the upload logic proceeds the same no matter which payment model is in use.
+
+> In the below it starts to seem like maybe instead of Keyring we should be talking about w3up client... @jchris
+
+### Upload with valid delegation
+
+This will be the same both when the user pays, and in the case where the user's DID has a valid delegation allowing it to upload to the app's account.
+
+```mermaid
+sequenceDiagram
+    participant Biometric
+    participant AppUI
+    participant Keyring
+    participant AppServer
+    participant Storage
+    
+    Note over AppServer, Storage: "The Cloud"
+    Note over Biometric, Keyring: Alice's  Device
+    Note over Biometric: Biometric <br>is optional
+    
+    AppUI ->> AppServer: Fetch web UI
+    AppServer -->> AppUI: HTML content  
+    Note over AppUI: Running app
+
+AppUI ->> Keyring: Upload this file
+Keyring ->> Biometric: Sign this invocation
+Note over Biometric: Just sign, no scan.
+Biometric -->> Keyring: Here's the signature
+loop for chunk in file
+    Keyring ->> Storage: Please run this upload invocation
+    Storage -->> Keyring: OK, use these upload params
+    Keyring ->> Storage: PUT the chunk
+end
+Keyring -->> AppUI: CID for uploaded file
+Note right of AppUI: Remainder is optional
+AppUI ->> AppServer: This CID is my recipe image
+Note over Storage: In the app pays model<br>the AppServer can query<br>Storage to list uploads
+AppServer -->> AppUI: ACK, I'll remember that
+
+```
+
+Note that in the server-pays model there will be other ways for the server to query user-saved data, so the user may not need to tell the server about their uploaded CID directly.
+
+
+### List uploads with valid delegation
+
+
+
+```mermaid
+sequenceDiagram
+    participant Biometric
+    participant AppUI
+    participant Keyring
+    participant AppServer
+    participant Storage
+    
+    Note over AppServer, Storage: "The Cloud"
+    Note over Biometric, Keyring: Alice's  Device
+    Note over Biometric: Biometric <br>is optional
+    
+    AppUI ->> AppServer: Fetch web UI
+    AppServer -->> AppUI: HTML content  
+    Note over AppUI: Running app
+
+AppUI ->> Keyring: List my uploads
+Keyring ->> Biometric: Sign this invocation
+Note over Biometric: Just sign, no scan.
+Biometric -->> Keyring: Here's the signature
+Keyring ->> Storage: Invoke this upload listing
+Storage -->> Keyring: Here's the list of uploads
+
+```