CloudServices/Notifications/Specification/ClientAgent

The Client Agent supports an RPC-like API which allows clients to register themselves with the notification service, as well as create and remove subscriptions to web app notifications.

Scenarios

New (Potentially First) Client

1. Client registers with Client Agent

   C: POST /1.0/new_queue HTTP/1.1
   C: Authorization: Basic BASE64==
   

2. Client agent generates Client ID (CID), creates User Exchange if necessary, creates and binds Client Queue CID, returns CID to Client.

   S: HTTP/1.1 200 OK
   S:
   S: {"host":"amqp.services.mozilla.com",
       "port":5672,
       "queue_id": "ASCII (max 255 chars)"}
   

3. Client records CID.
4. Client fetches notifications/subscriptions WBO from Sync, decrypts with sync key. This returns the following (encrypted) JSON:

   { "T in Base64": {
       "app_name": "GMail", 
       "app_host": "mail.google.com", 
       "app_account": "sdasilva@gmail.com",  // Optional
       "key": "BASE64=="
     },
     "T2 in Base64": {...}
   }
   

New Subscription

1. Client generates symmetric key K = 256 random bits AES and and token T = 256 random bits.
2. Client registers token T with Client Agent.

   C: POST /1.0/new_subscription HTTP/1.1
   C: Authorization: Basic BASE64==
   C:
   C: {"token": "BASE64=="}
   

3. Client Agent subscribes User Exchange to token T.

   S: HTTP/1.1 200 OK
   

4. Client uploads new notifications/subscriptions WBO to Sync.
5. Client passes key K, token T, and POST Office URL to web app.

Terminate Subscription

1. Client tells Client Agent to remove subscription with specified token T.

   C: POST /1.0/remove_subscription HTTP/1.1
   C: Authorization: Basic BASE64==
   C: 
   C: {"token": "T in Base 64"}
   

2. Client Agent removes binding T from User Exchange.

   S: HTTP/1.1 200 OK
   

Broadcast to Other Clients

1. Client broadcasts message to other clients of the authorized user. The format is very similar to that of the POST Office API.

   C: POST /1.0/broadcast HTTP/1.1
   C: Authorization: Basic BASE64==
   C: 
   C: {
        "body": "{\"IV\":\"IV in Base 64\",...",
        "HMAC": "BASE64=="
      }
   S: HTTP/1.1 200 OK
   

2. Body is a JSON serialization of:

   { 
     "timestamp": ######## (in seconds UTC), // Optional,
     "ttl": ######## (in seconds), // Optional
     "ciphertext": "BASE64==",
     "IV": "BASE64==",
   }
   

3. Ciphertext is the payload encrypted using AES-256-CBC and base-64 encoded. For an example of what payloads would look like, see Broadcast Messages
4. Client Agent routes the notifications to the appropriate user exchange.

Broadcast Messages

Each broadcast message is encrypted and contained entirely within the "ciphertext" attribute of the message body. The following is a list of the type of broadcast messages supported by browser clients.

Send Tab To Client

Copies a tab from one client and sends it to another client.

{
  "type": "send_tab",
  "client_id": "BASE64==", // Sync client ID
  "url": "...",
  // OPTIONAL: Implement either one of the following fields to transfer tab history and form data
  "moztabinfo": "{Serialized Tab State}" // Value returned by nsISessionStore.getTabState()
  "tabinfo": [{"url":"...", "title":"...", "formdata":"..."}] // Generic format (STILL NEEDS SPECING)
}

Note that this message is broadcasted, so the "client_id" field must be compared against the client's own ID to make sure the message was intended for it.

Sync Now

Send a message to clients indicating that important data has been synced, and so all clients should sync ASAP.

{
  "type": "sync_now",
  "sender_id": "BASE64==", // Sync client ID of client who sent this message
  "engines": ["bookmarks", "tabs", ...] // Optional list of engines to sync
}