add xmpp page

4 files changed, 74 insertions, 28 deletions

diff --git a/doc/design/assistant.mdwn b/doc/design/assistant.mdwn
index 77e96123d..5a34d4e77 100644
--- a/doc/design/assistant.mdwn
+++ b/doc/design/assistant.mdwn
@@ -11,7 +11,7 @@ and use cases to add. Feel free to chip in with comments! --[[Joey]]
 
 We are, approximately, here:
 
-* Month 4 "cloud": [[!traillink cloud]] [[!traillink transfer_control]]
+* Month 4 "cloud": [[!traillink cloud]] [[!traillink xmpp]] [[!traillink transfer_control]]
 * Month 5 user-driven features (see [[polls]])
 * Months 6-7 "9k bonus round": [[!traillink Android]] [[!traillink partial_content]] [[!traillink leftovers]]
 * Months 8-11: more user-driven features and polishing (see remaining TODO items in all pages above)
diff --git a/doc/design/assistant/cloud.mdwn b/doc/design/assistant/cloud.mdwn
index b815c5d2d..18a1b3e9a 100644
--- a/doc/design/assistant/cloud.mdwn
+++ b/doc/design/assistant/cloud.mdwn
@@ -30,7 +30,7 @@ been a change to Alice's git repo. Then he needs to pull from Alice's git repo,
 or some other repo in the cloud she pushed to. Once both steps are done,
 the assistant will transfer the file from the cloud to Bob.
 
-* dvcs-autosync uses jabber; all repos need to have the same jabber account
+* dvcs-autosync uses xmppp; all repos need to have the same xmpp account
   configured, and send self-messages. An alternative would be to have
   different accounts that join a channel or message each other. Still needs
   account configuration.
@@ -44,32 +44,7 @@ the assistant will transfer the file from the cloud to Bob.
 * pubsubhubbub does not seem like an option; its hubs want to pull down
   a feed over http.
 
-### jabber TODO
-
-* test with big servers, eg google chat
-* Prevent idle disconnection. Probably means sending or receiving pings,
-  but would prefer to avoid eg pinging every 60 seconds as some clients do.
-* Make the git-annex clients invisible, so a user can use their regular
-  account without always seeming to be present when git-annex is logged in.
-  See <http://xmpp.org/extensions/xep-0126.html>
-
-### jabber security
-
-Any data git-annex sends over this XMPP will be visible to the XMPP
-account's buddies, to the XMPP server, and quite likely to other interested
-parties. So it's important to consider the security exposure of using it.
-
-If git-annex sends only a single bit notification, this lets attackers know
-when the user is active and changing files. Although the assistant's other
-syncing activities can somewhat mask this.
-
-As soon as git-annex does anything unlike any other client, an attacker can
-see how many clients are connected for a user, and fingerprint the ones
-running git-annex, and determine how many clients are running git-annex.
-
-If git-annex sent the UUID of the remote it pushed to, this would let
-attackers determine how many different remotes are being used,
-and map some of the connections between clients and remotes.
+See [[xmpp]] for design of git-annex's use of xmpp for notifications.
 
 ## storing git repos in the cloud
 
diff --git a/doc/design/assistant/pairing.mdwn b/doc/design/assistant/pairing.mdwn
index d09c644ee..30b42a2cc 100644
--- a/doc/design/assistant/pairing.mdwn
+++ b/doc/design/assistant/pairing.mdwn
@@ -81,3 +81,4 @@ is escaped before going to the browser.
 
   It should be possible for third parties to tell when pairing is done,
   but it's actually rather hard since they don't necessarily share the secret.
+* Pairing over XMPP.
diff --git a/doc/design/assistant/xmpp.mdwn b/doc/design/assistant/xmpp.mdwn
new file mode 100644
index 000000000..6d5384e43
--- /dev/null
+++ b/doc/design/assistant/xmpp.mdwn
@@ -0,0 +1,70 @@
+The git-annex assistant uses XMPP to communicate between peers that
+cannot directly talk to one-another. A typical scenario is two users
+who share a repository, that is stored in the [[cloud]].
+
+### TODO
+
+* test with big servers, eg google chat
+* Prevent idle disconnection. Probably means sending or receiving pings,
+  but would prefer to avoid eg pinging every 60 seconds as some clients do.
+* Make the git-annex clients invisible, so a user can use their regular
+  account without always seeming to be present when git-annex is logged in.
+  See <http://xmpp.org/extensions/xep-0126.html>
+* webapp configuration
+* After pulling from a remote, may need to scan for transfers, which
+  could involve other remotes (ie, S3). Since the remote client is not able to
+  talk to us directly, it won't be able to upload any new files to us.
+  Need a fast way to find new files, and get them transferring. The expensive
+  transfer scan may be needed to get fully in sync, but is too expensive to
+  run every time this happens.
+
+## design goals
+
+1. Avoid user-visible messages. dvcs-autosync uses XMPP similarly, but
+   sends user-visible messages. Avoiding user-visible messages lets
+   the user configure git-annex to use his existing XMPP account
+   (eg, Google Talk).
+
+2. Send notifications to buddies. dvcs-autosync sends only self-messages,
+   but that requires every node have the same XMPP account configured.
+   git-annex should support that mode, but it should also send notifications
+   to a user's buddies. (This will also allow for using XMPP for pairing
+   in the future.)
+
+3. Don't make account appear active. Just because git-annex is being an XMPP
+   client, it doesn't mean that it wants to get chat messages, or make the
+   user appear active when he's not using his chat program.
+
+## protocol
+
+To avoid relying on XMPP extensions, git-annex communicates
+using presence messages. These always mark it as extended away.
+To this, it adds its own tag as [extended content](http://xmpp.org/rfcs/rfc6121.html#presence-extended).
+The xml namespace is "git-annex" (not an URL because I hate wasting bandwidth).
+
+To indicate it's pushed changes to a git repo, a client uses:
+
+	<git-annex xmlns='git-annex' push="uuid" />
+
+The push attribute can be repeated when the push was sent to multiple repos.
+
+### security
+
+Data git-annex sends over XMPP will be visible to the XMPP
+account's buddies, to the XMPP server, and quite likely to other interested
+parties. So it's important to consider the security exposure of using it.
+
+Even if git-annex sends only a single bit notification, this lets attackers
+know when the user is active and changing files. Although the assistant's other
+syncing activities can somewhat mask this.
+
+As soon as git-annex does anything unlike any other client, an attacker can
+see how many clients are connected for a user, and fingerprint the ones
+running git-annex, and determine how many clients are running git-annex.
+
+If git-annex sent the UUID of the remote it pushed to, this would let
+attackers determine how many different remotes are being used,
+and map some of the connections between clients and remotes.
+
+An attacker could replay push notification messages, reusing UUIDs it's
+observed. This would make clients pull repeatedly, perhaps as a DOS.