[Imported from Trac: page AccountingDesign, version 9]

AccountingDesign.md

@@ -200,7 +200,7 @@ representation would probably be fairly compact too.
 ### Pet Name Table
 
 The "Usage/Aggregator" component (described below) can display a "pet name"
-along with each key, to make the results more meaningful ("Bob using 73MB"
+along with each key, to make the results more meaningful ("Bob is using 73MB"
 instead of "pubkey j7sta2uvcr345znqwfwlxitnii is using 73MB"). This is more
 likely to be used by the friendnet case than the commercial grid (in which
 this functionality will most likely exist in an external database). The "pet
@@ -266,3 +266,80 @@ process again with a new signed request message. If they experience
 `AuthorityExpiredError` during the login process, then part of their
 certificate chain may have expired.
 
+== Typical Delegation Patterns ==
+
+We've identified 5 kinds of point-to-point delegation operations, described
+[DelegationOperations here]. Types 1, 2, and 3 involve creating a new
+certificate (authorizing some private key to perform some set of operations).
+Type 4 involves giving a public key to someone else and having them start
+accepting requests that are signed by the corresponding private key.
+
+In the friend-net use case, we expect that type-4 delegation will be used
+everywhere. When Alice sets up a storage server and wants to let Bob start
+using it, Bob will give her a public key, and Alice will drop that public key
+into her server's config with a note that says "accept requests that are
+signed by the corresponding private key". If Bob also wants Alice to be able
+to use his storage space ("reciprocity"), then Alice will give a public key
+to Bob.
+
+In the commercial grid case, we want to achieve some isolation between
+clients and servers: we will be adding new clients and servers constantly,
+and it is important that configuring both is cheap. Requiring a client update
+for every new server (or a server update for every new client) is
+unacceptable. So in this case, we define an "Account Manager", with its own
+private key. We use type-4 delegation to have all storage servers delegate
+authority to the account manager (by dropping the AM's pubkey in the new
+storage server's cert-roots directory). We then use type 1 (or 2 or 3)
+delegation to grant authority to the clients: the AM signs a certificate that
+names each client's public key, and gives that certificate to the client:
+this certificate is called their "membership card". Each client, when it
+needs to upload a file, will then send their membership card and a signed
+request to the storage servers.
+
+== User Experience ==
+
+Since Alice (who is running the storage server in our example) is who starts
+with full authority over that storage server, we would like the act of
+delegating authority to Bob to be expressed with a message from Alice to Bob
+(and not the other way around). Since the most likely form of delegation
+(type 1) involves a public key being sent in the opposite directory, we need
+to define a user-friendly command that can establish a communication channel
+for the two nodes to achieve the desired delegation.
+
+So Alice will type `tahoe invite Bob`, and her node will create an
+Invitation object for Bob. This object is single-use, persistent (until
+claimed), and remembers the pet name "Bob". It gets an unguessable swissnum,
+and the command then emits a FURL that references this object. Alice sends
+the invitation FURL to Bob via any convenient secure channel.
+
+Once Bob has received the invitation, he pastes it into an invocation of
+`tahoe accept-invitation Alice` (where "Alice" is his pet name for the
+person who sent him this invitation. Bob's node will then contact the
+Invitation object and claim it by sending Bob's public key to Alice. Alice's
+node will add Bob's public key in her root-certs directory, allowing Bob to
+use storage space on Alice's server. Her node will also record "Bob" as the
+pet name associated with this pubkey, so that her Usage display will report
+the usage of Bob instead of the less-useful "pubkey
+j7sta2uvcr345znqwfwlxitnii".
+
+The default friend-net behavior is reciprocity, so unless this is disabled in
+the command arguments, the Invitation process will also deliver Alice's
+pubkey into Bob's root-certs list, and add "Alice" and her key to Bob's
+pet-name table.
+
+Other material may be exchanged during the invitation process. A pair of new
+Tahoe directories can be established as an "inbox/outbot" pair, to let Alice
+and Bob exchange files securely (associated with the pre-established
+petnames). A FURL referencing an arbitrary object can be established for
+later expansion use (perhaps to enable real-time communication): while not
+useful in the current release, by establishing one during the initial
+invite/accept process, later releases will be able to build upon this secure
+reference.
+
+All CLI tools should have web-form equivalents, which will probably require
+that a set of authority-bearing non-file-related web pages must be defined.
+The easiest way to accomplish this is to have an unguessable "control URL",
+stored in NODEDIR/private/control.url, and put all these authority-bearing
+pages (with "Invite" buttons, etc) as children of the control URL. The user
+would run "tahoe show-control-url" (or "tahoe webopen control-url" or
+something) to access it.