start a feature list for new versions of the filecap format

[Imported from Trac: page NewCapDesign, version 1]

NewCapDesign.md

@@ -0,0 +1,85 @@
+# Goals for new filecaps
+
+This is a place to record desiderata for the next version of our
+mutable/immutable filecaps. Many of the design requirements are spread out
+across separate tickets: this page is here to consolidate them. We should not
+release a new filecap format without checking it against everything on this
+list.
+
+Ticket #432 was the starting point: it contained a list of features.
+
+## make them real URIs
+
+Kevin Reid points out that the Tahoe calls URIs are not actually URIs (in the
+established sense). To make them real, we need to:
+
+ * make then start with `x-tahoe:` or `tahoe:`, register `tahoe:`
+   with IANA (#418)
+ * understand how URI/URL/URNs are built, decide about hierarchical segments
+   vs non-hierarchical segments. What's magical about a leading double-slash?
+   Do we need one?
+
+## other features
+
+ * Enable convenient cut-and-paste. If caps are too long they'll wrap in
+   email. If they contain lots of word-breaking characters then you have to
+   drag after you've double clicked (this is probably ok). If the word-broken
+   sections are small and at the beginning or end then you have to be very
+   precise about that drag. The best design would be a single short
+   non-word-breaking string. The next best will be to have a large
+   non-word-breaking string at the start and end, with smaller segments (if
+   necessary) in the middle.
+ * Usable in a browser. Specifically, it should be easy to actually use a
+   filecap that you get in email or IM, and many email/IM clients will look
+   for http URLs and make them clickable. If tahoe filecaps start with
+   `http:`, then they'll be made clickable. This is at odds with the
+   IANA-friendly `tahoe:` prefix. Clients may make `tahoe:` URIs
+   clickable too (I've seen them make other letters-than-colon strings
+   clickable, even when the letters are not "http"), so perhaps a reasonable
+   solution is to provide an OS-level URI handler for the `tahoe:`
+   scheme, which could embed the filecap in an http URL and submit it to a
+   webbrowser (i.e. when you click on `tahoe:foo`, a helper program is
+   launched with `tahoe:foo`, and that in turn launches your web browser
+   with `<http://localhost:8123/foo>`). (#52)
+ * Self-identifying. It should be visually clear what sort of filecap the
+   string represents: read-write or read-only, mutable-or-immutable,
+   file-or-directory. This is especially important when sharing tahoe objects
+   over out-of-band channels like IM and email: it should be easy for the
+   user to tell whether they're giving away readonly access or read-write
+   access. We've considered prefixes like `DWM..` for "Directory
+   Writeable Mutable" and `FRI..` for "File Readonly Immutable". If these
+   are jammed against the (base62) crypto bits it may be difficult to tell
+   where the prefix ends and the crypto bits begin (`FRIDWM...`).
+  * in addition, tahoe URIs should be distinguishable from local filenames by
+    a CLI tool, so that `tahoe cp $CAP local/foo.txt` is unambiguous.
+    (unfortunately, the current practice of using "tahoe:" as a default alias
+    name collides with this badly, but perhaps if the new URIs include the
+    double-slash, this won't be a problem:
+    `tahoe cp tahoe://CAP local/foo.txt` copies from a specific URI,
+    while `tahoe cp tahoe:blah local/foo.txt` copies from a child of
+    the "tahoe:" alias).
+  * I'd like to make it easy to layer uses on top of one another: since
+    directories are just a specific way of interpreting the contents of a
+    (mutable) file, let's make the directory cap be closely related to the
+    underlying filecap. For example, if we end up using
+    `tahoe://MR/cryptobits` to describe a read-only mutable file
+    referenced by "cryptobits", then we could use
+    `tahoe://D/MR/cryptobits` for the directory that uses it as a backing
+    store. The rule would be that `tahoe://D/$A` would be handled by
+    fetching `tahoe://$A` and then interpreting its contents as a
+    directory structure. Then reading immutable-dirnodes (#607) would be
+    trivial. Another way to think about this is that if our filecaps were
+    verbose s-expressions, these caps could be expressed as "(readonly
+    (mutable cryptobits))" and "(directory (readonly (mutable cryptobits)))".
+ * provide for verifycaps, repaircaps, and traversalcaps. Repaircaps in
+   particular may require a grant of storage authority, which might entail a
+   cap format that can accept arbitrary extra non-hierarchical fields.
+   Appendcaps or "drop-box" writecaps might fall into this same space.
+ * provide ciphertext access. Reading from a verifycap should give you
+   ciphertext. It should be possible to upload ciphertext directly.
+ * provide for a grid-identifier, possibly on the MSB end, e.g.
+   `tahoe://grid1234/IR/cryptobits`. Perhaps let some contexts define a
+   "default grid id", such that `tahoe://IR/cryptobits` is expanded to
+   mean `tahoe://grid1234/IR/cryptobits`. Something like
+   `tahoe://grid1234/D/MR/cryptobits` should reference
+   `tahoe://grid1234/MR/cryptobits`. (#403)