add telehash design page; update roadmap

1 files changed, 60 insertions, 0 deletions

diff --git a/doc/design/assistant/telehash.mdwn b/doc/design/assistant/telehash.mdwn
new file mode 100644
index 000000000..8abbba158
--- /dev/null
+++ b/doc/design/assistant/telehash.mdwn
@@ -0,0 +1,60 @@
+[Telehash](http://telehash.org/) for secure P2P communication between
+git-annex (assistant) repositories.
+
+## telelhash implementation status
+
+* node.js version seems most complete
+* C version currently lacks channel support and seems buggy (13 Jan 2014)
+* No pure haskell implementation of telelhash v2. There was one of
+  telehash v1 (even that seems incomplete). I have pinged its author
+  to see if he anticipates updating it.
+* Rapid development, situation may change in a month or 2.
+
+## implementation basics
+
+* Add a telehash.log that maps between uuid and telehash address.
+* On startup, assistant creates a new telehash keypair if not already
+  present; stores this locally and generates a telehash address from it,
+  stored in telehash.log.
+* Use telehash for notifications of changes to the repository
+* Do git push over telehash. (Pretty easy, may need rate limiting in
+  situations involving relays.)
+* Remove git push over XMPP (which has several problems including
+  XMPP being an unreliable transport, requiring a separate XMPP account per
+  repo, and XMPP not being end-to-end encrypted)
+
+## telehash address discovery
+
+* Easy way is any set of repos that are already connected can communicate
+  them via telehash.log.
+* Local pairing can be used for telehash address discovery. Could be made
+  to work without ssh (with content transfer over telehash discussed
+  below).
+* XMPP pairing can also be used for telehash address discovery. (Note that
+  MITM attacks are possible.) Is it worth keeping XMPP in git-annex just
+  for this?
+* Telelhash addresses of repoitories can be communicated out of band (eg,
+  via an OTR session or gpg signed mail), and pasted into the webapp to
+  initiate a repository pairing that then proceeds entirely over telehash.
+  Once both sides do this, the pairing can proceed automatically.
+
+## content transfer over telehash
+
+* In some circumstances, it would be ok to do annexed content transfer
+  over telehash.  
+  Need to check if there are MTU problems with large data bodies in
+  telelhash messages.  
+  Probably not when a bridge is being used, due to required rate
+  limiting in bridging over telehash. Cloud transfer remotes still needed for
+  those situations.
+* On a LAN, telehash can be used to determine the current local IP address
+  of another computer on the LAN. The 2 could then determine if either uses
+  ssh and if so use regular git-annex-shell for transfers. Or could do
+  annexed content transfer directly over telelhash.
+
+## generic git-remote-telehash
+
+This might turn out to be easy to split off from git-annex, so `git pull`
+and `git push` can be used at the command line to access telehash remotes.
+Allows using general git entirely decentralized and with end-to-end
+encryption.