[Imported from Trac: page AccountingDesign, version 3]

AccountingDesign.md

@@ -33,6 +33,9 @@ if) we actually need them to be completed:
    6d. helper: clients enable the helper to upload files for them
  7. auditing: who owns this share, how did they get permission to upload it
  8. reconcilliation / garbage collection : which shares does Bob own?
+ 9. measure traffic: how many bytes did Bob upload or download (as opposed to
+    how much is he currently storing)
+
 
 ## Immediate Goals
 
@@ -49,3 +52,69 @@ We've established a smaller set of goals for the next few releases:
 
  * next after that
    * more generalized delegation
+
+## Design Overview
+
+As touched upon in source:docs/proposed/accounts-pubkey.txt (and
+source:docs/proposed/accounts-introducer.txt), each share on a storage server
+is kept alive (in a garbage-collection sense) by one or more "leases", and
+each lease is assigned to a given "account"/"user"/"owner". The server has an
+imaginary "lease table" (imaginary in the snese that it is not actually
+implemented as a giant table: instead the data is broken up into more
+efficient/robust pieces). This two-dimensional lease table has Storage Index
+along one axis, and Account on the other, and each cell of the table
+represents a potential lease.
+
+Each account-owner gets control over their column of the table: they can add
+leases to existing shares, upload new shares (which immediately acquire new
+leases), cancel their lease on a share (possibly causing the share to be
+garbage-collected), or get a list of all of their leases (for
+reconcilliation).
+
+Some clients may be "super-powered", meaning that they may have the authority
+to affect more than one row of the table. It may be necessary to give a
+Repairer this sort of authority to let it keep files alive when the original
+uploading client is not participating in the maintenance process. POLA
+dictates that we try to avoid needing this sort of authority inflation, so
+superpower delegation is just a fallback plan.
+
+The admin of each storage server decides their own policy by configuring
+their server with various certificates and public keys: fundamentally,
+storage authority originates with the server, and is delegated outwards to
+the clients. Clients are configured with certificates and private keys that
+allow them to use some portion of the server's authority.
+
+Each time a client uploads a file (or otherwise makes use of storage
+authority), they must demonstrate their authority to each server, through a
+negotiation protocol. The `client.upload()` API will be modified to
+accept a new argument, tenatively named "cred=", that represents this
+authority. The webapi will also acquire such an argument, allowing the HTTP
+client to pass its authority to the webapi server so the server can perform
+the upload.
+
+# Design Pieces
+
+* Add cred= to upload API
+  * client.upload() needs a cred= argument
+  * the webapi PUT/POST commands need a cred= argument
+  * the javascript-based webfront program (used by allmydata.com) needs cred
+  * the human-oriented "wui" needs a way (cookies? sessions?) to express
+    storage authority
+
+* Define how to configure clients with their storage authority
+
+* define how to create these credentials
+  * certificate-signing tools
+  * "tahoe sign" subcommand
+
+* define how to configure servers with their certificates
+* changes to Introduction
+  * advertise accepted pubkeys in the storage-v2 announcements?
+* changes to peer selection
+* furlification process, persistence/optimization
+* label format: how should leases be labeled
+* usage-table management: databases, size totals, what to store in each lease
+* Usage/Aggregator service
+  * web interface
+  * petname database / display
+