From a255b3693ea5e752b10d616da66431b7b2ff4515 Mon Sep 17 00:00:00 2001
From: Jean-Paul Calderone <exarkun@twistedmatrix.com>
Date: Fri, 1 Oct 2021 11:52:30 -0400
Subject: [PATCH] add protocol sequence diagrams for zkap purchase and use
---
.gitlab-ci.yml | 2 +-
docs.nix | 2 -
docs/default.nix | 2 +
docs/docs.nix | 20 ++++
docs/source/conf.py | 4 +-
docs/source/dev/README.rst | 113 ++++++++++++++++++++--
docs/source/dev/architecture-overview.dot | 17 +++-
privatestorageio.nix | 19 ----
8 files changed, 147 insertions(+), 32 deletions(-)
delete mode 100644 docs.nix
create mode 100644 docs/default.nix
create mode 100644 docs/docs.nix
delete mode 100644 privatestorageio.nix
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index d6b06fae..8ef000d0 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -8,7 +8,7 @@ default:
docs:
stage: "build"
script:
- - "nix-build docs.nix"
+ - "nix-build docs"
- "cp --recursive --no-preserve=mode result/docs/. docs/build/"
artifacts:
paths:
diff --git a/docs.nix b/docs.nix
deleted file mode 100644
index 4c8b230a..00000000
--- a/docs.nix
+++ /dev/null
@@ -1,2 +0,0 @@
-{ pkgs ? import ./nixpkgs-2105.nix { } }:
-pkgs.callPackage ./privatestorageio.nix { }
diff --git a/docs/default.nix b/docs/default.nix
new file mode 100644
index 00000000..488a7493
--- /dev/null
+++ b/docs/default.nix
@@ -0,0 +1,2 @@
+{ pkgs ? import ../nixpkgs-2105.nix { } }:
+pkgs.callPackage ./docs.nix { }
diff --git a/docs/docs.nix b/docs/docs.nix
new file mode 100644
index 00000000..03ac07df
--- /dev/null
+++ b/docs/docs.nix
@@ -0,0 +1,20 @@
+{ stdenv, lib, graphviz, plantuml, python3, sphinx }:
+let
+ pyenv = python3.withPackages (ps: [ ps.sphinx ps.sphinxcontrib_plantuml ]);
+in
+stdenv.mkDerivation rec {
+ version = "0.0";
+ name = "privatestorageio-${version}";
+ src = lib.cleanSource ../.;
+
+ phases = [ "unpackPhase" "buildPhase" ];
+
+ depsBuildBuild = [
+ graphviz
+ plantuml
+ ];
+
+ buildPhase = ''
+ ${pyenv}/bin/sphinx-build -W docs/source $out/docs
+ '';
+}
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 66aa921e..747a90a8 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -20,7 +20,7 @@
# -- Project information -----------------------------------------------------
project = 'PrivateStorageio'
-copyright = '2019, PrivateStorage.io, LLC'
+copyright = '2021, PrivateStorage.io, LLC'
author = 'PrivateStorage.io, LLC'
# The short X.Y version
@@ -38,8 +38,10 @@ release = '0.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
+
extensions = [
"sphinx.ext.graphviz",
+ "sphinxcontrib.plantuml",
]
# Add any paths that contain templates here, relative to this directory.
diff --git a/docs/source/dev/README.rst b/docs/source/dev/README.rst
index 14d2de31..19940b80 100644
--- a/docs/source/dev/README.rst
+++ b/docs/source/dev/README.rst
@@ -57,14 +57,115 @@ To update the channel, the script will need to be updated,
along with the filenames that have the channel in them.
-Architecture overview
----------------------
-
-.. graphviz:: architecture-overview.dot
-
+Interactions
+------------
+
+Storage-Time Purchase (ie Payment)
+``````````````````````````````````
+
+.. uml::
+
+ actor User as User
+ participant GridSync
+ participant ZKAPAuthorizer
+ database ZKAPAuthzDB as "ZKAPAuthorizer"
+ participant Browser
+ participant PaymentServer as "Payment Server"
+ database PaymentServerDB as "Payment Server"
+ participant WebServer as "Web Server"
+ participant Stripe
+
+ User -> GridSync : buy storage-time
+ activate User
+ GridSync -> GridSync : generate voucher
+ GridSync -> ZKAPAuthorizer : redeem voucher
+ activate ZKAPAuthorizer
+ ZKAPAuthorizer -> ZKAPAuthzDB : store voucher
+ ZKAPAuthorizer -> GridSync : acknowledge
+ GridSync -> Browser : open payment page
+
+ loop until redeemed
+ GridSync -> ZKAPAuthorizer : query voucher state
+ ZKAPAuthorizer -> GridSync : not paid
+ end
+
+ Browser -> WebServer : request payment form
+ WebServer -> Browser : payment form
+ Browser -> User : Payment form displayed
+ activate User
+ User -> Browser : Submit payment details
+ Browser -> Stripe : Submit payment details
+
+ alt payment details accepted
+ Stripe -> Browser : details okay, return card token
+ Browser -> PaymentServer : create charge using card token
+ PaymentServer -> Stripe : charge card using token
+ note left: the user has now paid for the service
+ Stripe -> PaymentServer : acknowledge
+ PaymentServer -> PaymentServerDB : store voucher paid state
+ else payment details rejected
+ Stripe -> Browser : payment failure
+ end
+
+ Browser -> User : payment processing results displayed
+ deactivate User
+
+ group repeat for each redemption group
+ ZKAPAuthorizer -> ZKAPAuthzDB : generate and store random tokens
+ ZKAPAuthorizer -> PaymentServer : redeem voucher with blinded tokens
+ PaymentServer -> ZKAPAuthorizer : return signatures for blinded tokens
+ ZKAPAuthorizer -> ZKAPAuthzDB : store unblinded signatures for tokens
+ note right: the user has now been authorized to use the service
+ end
+ deactivate ZKAPAuthorizer
+
+ loop until redeemed
+ GridSync -> ZKAPAuthorizer : query voucher state
+ ZKAPAuthorizer -> GridSync : fully redeemed
+ end
+
+ GridSync -> User : storage-time available displayed
+ deactivate User
+
+Storage-Time Spending (ie Use)
+``````````````````````````````
+
+.. uml::
+
+ participant MagicFolder
+ participant TahoeLAFS as "Tahoe-LAFS"
+ participant ZKAPAuthorizer
+ database ZKAPAuthzDB as "ZKAPAuthorizer"
+ participant StorageNode as "Storage Node"
+ participant SpendingService as "Spending Service"
+
+ MagicFolder -> TahoeLAFS : store some data
+ activate MagicFolder
+
+ TahoeLAFS -> ZKAPAuthorizer : store some data
+ activate TahoeLAFS
+
+ loop until tokens accepted
+ ZKAPAuthorizer <- ZKAPAuthzDB : load some tokens
+ ZKAPAuthorizer -> StorageNode : store some data using these tokens
+ StorageNode -> SpendingService : spend these tokens
+
+ alt spent tokens
+ SpendingService -> StorageNode: already spent, rejected
+ StorageNode -> ZKAPAuthorizer: already spent, rejected
+ else fresh tokens
+ SpendingService -> StorageNode: spent, allowed
+ StorageNode -> ZKAPAuthorizer: data stored
+ ZKAPAuthorizer -> ZKAPAuthzDB: discard spent tokens
+ end
+
+ ZKAPAuthorizer -> TahoeLAFS: data stored
+ deactivate TahoeLAFS
+ TahoeLAFS -> MagicFolder: data stored
+ deactivate MagicFolder
+ end
.. include::
../../../morph/grid/local/README.rst
.. _Nix: https://nixos.org/nix
-
diff --git a/docs/source/dev/architecture-overview.dot b/docs/source/dev/architecture-overview.dot
index cc95fbb7..925305b5 100644
--- a/docs/source/dev/architecture-overview.dot
+++ b/docs/source/dev/architecture-overview.dot
@@ -6,23 +6,34 @@ digraph subscriptions {
rankdir=LR
GridSync [label="GridSync", shape=circle]
Browser [label="Browser", shape=circle]
- TahoeLAFS [label="Tahoe-LAFS", shape=circle]
+ ZKAPAuthorizer [label="ZKAPAuthorizer", shape=circle]
}
-
subgraph cluster_pscontrolled {
label = "PrivateStorage.io Operated"
rankdir = TB
PSWebServer [label="PrivateStorage.io Web Server", shape=box]
SubscriptionConfigWHPeer [label="Subscription Config Wormhole Peer", shape=box]
PaymentServer [label="Payment Server", shape=box]
- SATIssuer [label="SAT Issuer", shape=box]
PSStorageGrid [label="PrivateStorage.io Storage Grid", shape=box]
}
User [label="User", shape=egg]
Stripe [label="Stripe", shape=pentagon]
+ User -> GridSync [label="1. Initiate ZKAP Purchase", fontcolor=red, color=red]
+ GridSync -> GridSync [label="2. Generate random voucher", fontcolor=blue, color=blue]
+ GridSync -> ZKAPAuthorizer [label="3. Redeem voucher", fontcolor=brown, color=brown]
+
+ GridSync -> Browser [label="4. Open payment window", fontcolor=gold3, color=gold3]
+ User -> Browser [label="5. Enter payment info", fontcolor=blue, color=blue]
+ Browser -> Stripe [label="6. Submit payment form", fontcolor=brown, color=brown]
+ Stripe -> Browser [label="7. Payment ok", fontcolor=black, color=black]
+ Stripe -> PaymentServer [label="8. Payment notification", fontcolor=magenta, color=magenta]
+
+ ZKAPAuthorizer -> PaymentServer [label="9. Redeem voucher", ]
+
+
User -> PSWebServer [label="1. Get wormhole code", fontcolor=red, color=red]
PSWebServer -> User [label="2. 7-petulant-banana", fontcolor=blue, color=blue]
User -> GridSync [label="3. 7-petulant-banana", fontcolor=brown, color=brown]
diff --git a/privatestorageio.nix b/privatestorageio.nix
deleted file mode 100644
index cde46b16..00000000
--- a/privatestorageio.nix
+++ /dev/null
@@ -1,19 +0,0 @@
-{ stdenv, lib, graphviz, python3Packages }:
-stdenv.mkDerivation rec {
- version = "0.0";
- name = "privatestorageio-${version}";
- src = lib.cleanSource ./.;
-
- depsBuildBuild = [
- graphviz
- ];
-
- buildPhase = ''
- ${python3Packages.sphinx}/bin/sphinx-build -W docs/source docs/build
- '';
-
- installPhase = ''
- mkdir $out
- mv docs/build $out/docs
- '';
-}
--
GitLab