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. 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 202 ACCEPTED
   

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.