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.

Scenario 1: 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": {...}
   }
   

Scenario 2: 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": "T in Base 64"}
   

3. Client Agent subscribes User Exchange to token T.

   S: HTTP/1.1 200 OK
   

4. Client uploads new notifications/subscriptions WBO to Sync (see Scenario 1, Step 4).
5. Client passes key K, token T, and POST Office URL to web app (see Scenario Alpha).

Scenario 3: 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
   

Scenario 4: 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 with the client key using AES-256-CBC and base64 encoded. For example:

   {
    "type":"send_tab",
    "client_id":"base64url==", // Sync client ID
    "url":"...",
   // implement either one of the following fields to transfer tab history and form data
    "moztabinfo":{serialized tab info}                           // optional
    "tabinfo":[{"url":"...", "title":"...", "formdata":"..."}]   // optional
   }
   

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 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": "...",
// implement either one of the following fields to transfer tab history and form data
 "moztabinfo": {serialized tab info}                           // optional
 "tabinfo": [{"url":"...", "title":"...", "formdata":"..."}]   // optional (still needs specing)
}

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 sender
}