Secure WebSocket connection with cookie authentication (#621)

This PR adds the support of cookie when using the websocket protocol. To do that, when Kuzzle cookieAuth option is true, Kuzzle will call the method enableCookieSupport from the given protocol. When called, this method will throw if outside the browser or if cookie are not supported by the protocol, otherwise this will change how the protocol behave.

For the HTTP protocol it's simple, when enableCookieSupport is called, the protocol will be changing if the request are made with withCredentials set to true or false depending if he should be able to receive cookies.

For the Websocket protocol, this is a bit more complex, when enableCookieSupport is called, the protocol, will be creating a instance of the HTTP Protocol, with the same option (host, port, ssl, ...) as the websocket protocol, after that, when a request auth:login, auth:logout or auth:refreshToken is made, the protocol will use the HTTP Protocol instead of the websocket client to make the request.
[ex: auth:login request is made -> websocket closes the connection -> then send the request with the http protocol -> when a response is received it reopens the connection -> then resolve the request]

Author: Shiranuit

doc/7/core-classes/kuzzle/constructor/index.md

@@ -36,20 +36,20 @@ It can be one of the following available protocols:
 
 Kuzzle SDK instance options.
 
-| Property               | Type<br/>(default)               | Description                                                              |
-| ---------------------- | -------------------------------- | ------------------------------------------------------------------------ |
-| `autoQueue`            | <pre>boolean</pre><br/>(`false`) | Automatically queue all requests during offline mode                     |
-| `autoReplay`           | <pre>boolean</pre><br/>(`false`) | Automatically replay queued requests on a `reconnected` event            |
-| `autoResubscribe`      | <pre>boolean</pre><br/>(`true`)  | Automatically renew all subscriptions on a `reconnected` event           |
-| `cookieAuth`           | <pre>boolean</pre><br/>(`false`) | Uses cookie to store token                                         |
-| `eventTimeout`         | <pre>number</pre><br/>(`200`)    | Time (in ms) during which a similar event is ignored                     |
-| `deprecationWarning`   | <pre>boolean</pre><br />(`true`) | Show deprecation warning in development (hidden either way in production)|
-| `offlineMode`          | <pre>string</pre><br/>(`manual`) | Offline mode configuration. Can be `manual` or `auto`                    |
-| `queueTTL`             | <pre>number</pre><br/>(`120000`) | Time a queued request is kept during offline mode, in milliseconds       |
-| `queueMaxSize`         | <pre>number</pre><br/>(`500`)    | Number of maximum requests kept during offline mode                      |
-| `replayInterval`       | <pre>number</pre><br/>(`10`)     | Delay between each replayed requests, in milliseconds                    |
-| `tokenExpiredInterval` | <pre>number</pre><br/>(`1000`)   | Time (in ms) during which a TokenExpired event is ignored                |
-| `volatile`             | <pre>object</pre><br/>(`{}`)     | Common volatile data, will be sent to all future requests                |
+| Property               | Type<br/>(default)               | Description                                                                                         |
+| ---------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `autoQueue`            | <pre>boolean</pre><br/>(`false`) | Automatically queue all requests during offline mode                                                |
+| `autoReplay`           | <pre>boolean</pre><br/>(`false`) | Automatically replay queued requests on a `reconnected` event                                       |
+| `autoResubscribe`      | <pre>boolean</pre><br/>(`true`)  | Automatically renew all subscriptions on a `reconnected` event                                      |
+| `cookieAuth`           | <pre>boolean</pre><br/>(`false`) | Uses cookie to store token, this option set `offlineMode` to `auto` and `autoResubscribe` to `true` |
+| `deprecationWarning`   | <pre>boolean</pre><br />(`true`) | Show deprecation warning in development (hidden either way in production)                           |
+| `eventTimeout`         | <pre>number</pre><br/>(`200`)    | Time (in ms) during which a similar event is ignored                                                |
+| `offlineMode`          | <pre>string</pre><br/>(`manual`) | Offline mode configuration. Can be `manual` or `auto`                                               |
+| `queueTTL`             | <pre>number</pre><br/>(`120000`) | Time a queued request is kept during offline mode, in milliseconds                                  |
+| `queueMaxSize`         | <pre>number</pre><br/>(`500`)    | Number of maximum requests kept during offline mode                                                 |
+| `replayInterval`       | <pre>number</pre><br/>(`10`)     | Delay between each replayed requests, in milliseconds                                               |
+| `tokenExpiredInterval` | <pre>number</pre><br/>(`1000`)   | Time (in ms) during which a TokenExpired event is ignored                                           |
+| `volatile`             | <pre>object</pre><br/>(`{}`)     | Common volatile data, will be sent to all future requests                                           |
 
 ## Return
 

doc/7/protocols/websocket/introduction/index.md

@@ -23,3 +23,28 @@ This application-level PING has been especially added for web browsers, which do
 When run in a browser, our Javascript SDK uses that feature for its keep-alive mechanism: a message will periodically be sent to Kuzzle in the form `"{"p":1}"` through websocket.
 That message will call a response from Kuzzle in the form `"{"p":2}"` for the SDK to keep the connection alive.
 
+### Cookie Authentication
+
+Kuzzle supports cookie authentications, meaning that when using this SDK in a browser, you can ask Kuzzle to return authentication tokens in secure cookies, handled by browsers. This means that, when using that option, browser clients will never have access to said tokens, preventing a few common attacks.
+The support for cookie authentication can be enabled, using the [cookieAuth](/sdk/js/7/core-classes/kuzzle/constructor) option at the SDK initialization.
+
+When you enable the [cookieAuth](/sdk/js/7/core-classes/kuzzle/constructor) option, it changes the way the websocket protocol behaves when you're sending requests that should otherwise return authentication tokens in their response payload.
+
+When a request susceptible of changing an authentication cookie is about to be sent, the WebSocket Protocol send it using the [HTTP Protocol](/sdk/js/7/protocols/http/introduction) instead, to allow browsers to apply the received cookie. 
+
+If a new cookie is received from Kuzzle that way, the WebSocket connection is automatically renewed.
+
+::: info
+Cookies can only be applied to WebSocket connections during the connection handshake (upgrade from HTTP to WebSocket), and they stay valid as long as the connection is active, and as long as the cookie hasn't expired. 
+:::
+
+![websocket cookie authentication](./websocket-cookie-authentication.png)
+
+Here is a list of controller's actions that are affected by this behavior, when the [cookieAuth](/sdk/js/7/core-classes/kuzzle/constructor) option is enabled:
+- [auth:login](/sdk/js/7/controllers/auth/login)
+- [auth:logout](/sdk/js/7/controllers/auth/logout)
+- [auth:refreshToken](/sdk/js/7/controllers/auth/refresh-token)
+
+::: info
+The behaviors described above are automatically handled by the SDK, you do not need to implement this yourself.
+:::

doc/7/protocols/websocket/introduction/websocket-cookie-authentication.png

@@ -170,17 +170,17 @@ export class Kuzzle extends KuzzleEventEmitter {
        * If set to `auto`, the `autoQueue` and `autoReplay` are also set to `true`
        */
       offlineMode?: 'auto';
-      /**
-       * Show deprecation warning in development mode (hidden either way in production)
-       * Default: `true`
-       */
-      deprecationWarning?: boolean;
       /**
        * If `true` uses cookie to store token
        * Only supported in a browser
        * Default: `false`
        */
       cookieAuth?: boolean;
+      /**
+       * Show deprecation warning in development mode (hidden either way in production)
+       * Default: `true`
+       */
+      deprecationWarning?: boolean;
     } = {}
   ) {
     super();
@@ -225,14 +225,37 @@ export class Kuzzle extends KuzzleEventEmitter {
       ? options.volatile
       : {};
 
-    this.deprecationHandler = new Deprecation(
-      typeof options.deprecationWarning === 'boolean' ? options.deprecationWarning : true
-    );
-
     this._cookieAuthentication = typeof options.cookieAuth === 'boolean'
       ? options.cookieAuth
       : false;
 
+    if (this._cookieAuthentication) {
+      this.protocol.enableCookieSupport();
+      let autoQueueState;
+      let autoReplayState;
+      let autoResbuscribeState;
+  
+      this.protocol.addListener('websocketRenewalStart', () => {
+        autoQueueState = this.autoQueue;
+        autoReplayState = this.autoReplay;
+        autoResbuscribeState = this.autoResubscribe;
+  
+        this.autoQueue = true;
+        this.autoReplay = true;
+        this.autoResubscribe = true;
+      });
+  
+      this.protocol.addListener('websocketRenewalDone', () => {
+        this.autoQueue = autoQueueState;
+        this.autoReplay = autoReplayState;
+        this.autoResubscribe = autoResbuscribeState;
+      });
+    }
+    
+    this.deprecationHandler = new Deprecation(
+      typeof options.deprecationWarning === 'boolean' ? options.deprecationWarning : true
+    );
+    
     if (this._cookieAuthentication && typeof XMLHttpRequest === 'undefined') {
       throw new Error('Support for cookie authentication with cookieAuth option is not supported outside a browser');
     }

src/Kuzzle.ts

@@ -113,7 +113,7 @@ export default class HttpProtocol extends KuzzleAbstractProtocol {
       return Promise.resolve();
     }
 
-    return this._sendHttpRequest('GET', '/_publicApi')
+    return this._sendHttpRequest({method: 'GET', path: '/_publicApi'})
       .then(({ result, error }) => {
         if (! error) {
           this._routes = this._constructRoutes(result);
@@ -133,7 +133,7 @@ export default class HttpProtocol extends KuzzleAbstractProtocol {
         } else if (error.status === 404) {
           // fallback to server:info route
           // server:publicApi is only available since Kuzzle 1.9.0
-          return this._sendHttpRequest('GET', '/')
+          return this._sendHttpRequest({method: 'GET', path: '/'})
             .then(({ result: res, error: err }) => {
               if (! err) {
                 this._routes = this._constructRoutes(res.serverInfo.kuzzle.api.routes);
@@ -173,12 +173,23 @@ export default class HttpProtocol extends KuzzleAbstractProtocol {
   }
 
   /**
-   * Sends a payload to the connected server
+   * Enable cookie authentication support at protocol level
+   */
+  enableCookieSupport () {
+    if (typeof XMLHttpRequest === 'undefined') {
+      throw new Error('Support for cookie cannot be enabled outside of a browser');
+    }
+
+    super.enableCookieSupport();
+  }
+
+  /**
+   * Preprocess and format the request
    *
    * @param {Object} data
    * @returns {Promise<any>}
    */
-  send (request: RequestPayload, options: JSONObject = {}) {
+  formatRequest (request: RequestPayload, options: JSONObject = {}) {
     const route = this.routes[request.controller]
       && this.routes[request.controller][request.action];
 
@@ -281,12 +292,30 @@ export default class HttpProtocol extends KuzzleAbstractProtocol {
       url += '?' + queryString.join('&');
     }
 
-    this._sendHttpRequest(method, url, payload)
-      .then(response => this.emit(payload.requestId, response))
-      .catch(error => this.emit(payload.requestId, {error}));
+    return {
+      method,
+      path: url,
+      payload
+    };
+  }
+
+  /**
+   * Sends a payload to the connected server
+   *
+   * @param {Object} data
+   * @returns {Promise<any>}
+   */
+  send (request: RequestPayload, options: JSONObject = {}) {
+    const formattedRequest = this.formatRequest(request, options);
+
+    if (formattedRequest) {
+      this._sendHttpRequest(formattedRequest)
+        .then(response => this.emit(formattedRequest.payload.requestId, response))
+        .catch(error => this.emit(formattedRequest.payload.requestId, {error}));
+    }
   }
 
-  _sendHttpRequest (method, path, payload: any = {}) {
+  _sendHttpRequest ({method, path, payload = {headers: undefined, body:undefined}}) {
     if (typeof XMLHttpRequest === 'undefined') {
       // NodeJS implementation, using http.request:
 
@@ -331,7 +360,7 @@ export default class HttpProtocol extends KuzzleAbstractProtocol {
       xhr.open(method, url);
 
       // Authorize the reception of cookies
-      xhr.withCredentials = true;
+      xhr.withCredentials = this.cookieSupport;
 
       for (const header of Object.keys(payload.headers || {})) {
         xhr.setRequestHeader(header, payload.headers[header]);

src/protocols/Http.ts

@@ -4,6 +4,7 @@ import { KuzzleError } from '../KuzzleError';
 import { BaseProtocolRealtime } from './abstract/Realtime';
 import { JSONObject } from '../types';
 import { RequestPayload } from '../types/RequestPayload';
+import HttpProtocol from './Http';
 
 /**
  * WebSocket protocol used to connect to a Kuzzle server.
@@ -18,6 +19,7 @@ export default class WebSocketProtocol extends BaseProtocolRealtime {
   private pingIntervalId: ReturnType<typeof setInterval>;
   private _pingInterval: number;
   private _pongTimeout: number;
+  private _httpProtocol: HttpProtocol;
 
   /**
    * @param host Kuzzle server hostname or IP
@@ -209,15 +211,66 @@ export default class WebSocketProtocol extends BaseProtocolRealtime {
     });
   }
 
+  enableCookieSupport () {
+    if (typeof XMLHttpRequest === 'undefined') {
+      throw new Error('Support for cookie cannot be enabled outside of a browser');
+    }
+
+    super.enableCookieSupport();
+    this._httpProtocol = new HttpProtocol(
+      this.host, 
+      {
+        port: this.port,
+        ssl: this.ssl,
+      }
+    );
+    this._httpProtocol.enableCookieSupport();
+  }
+
   /**
    * Sends a payload to the connected server
    *
    * @param {Object} payload
    */
-  send (request: RequestPayload) {
-    if (this.client && this.client.readyState === this.client.OPEN) {
+  send (request: RequestPayload, options: JSONObject = {}) {
+    if (!this.client || this.client.readyState !== this.client.OPEN) {
+      return;
+    }
+
+    if (! this.cookieSupport
+      || request.controller !== 'auth'
+      || ( request.action !== 'login'
+        && request.action !== 'logout'
+        && request.action !== 'refreshToken')
+    ) {
       this.client.send(JSON.stringify(request));
+      return;
+    }
+
+    const formattedRequest = this._httpProtocol.formatRequest(request, options);
+
+    if (!formattedRequest) {
+      return;
+    }
+
+    this.emit('websocketRenewalStart'); // Notify that the websocket is going to renew his connection with Kuzzle
+    if (this.client) {
+      this.client.close();
     }
+    this.client = null;
+    this.clientDisconnected(); // Simulate a disconnection, this will enable offline queue and trigger realtime subscriptions backup
+
+    this._httpProtocol._sendHttpRequest(formattedRequest)
+      .then(response => {
+        // Reconnection
+        return this.connect()
+          .then(() => {
+            this.emit(formattedRequest.payload.requestId, response);
+            this.emit('websocketRenewalDone'); // Notify that the websocket has finished renewing his connection with Kuzzle
+          });
+      })
+      .catch(error => this.emit(formattedRequest.payload.requestId, {error}));
+    
   }
 
   /**

src/protocols/WebSocket.ts

@@ -13,6 +13,7 @@ export abstract class KuzzleAbstractProtocol extends KuzzleEventEmitter {
   private _name: string;
   private _port: number;
   private _ssl: boolean;
+  private _cookieSupport: boolean;
 
   public id: string;
 
@@ -46,6 +47,7 @@ export abstract class KuzzleAbstractProtocol extends KuzzleEventEmitter {
 
     this.id = uuidv4();
     this.state = 'offline';
+    this._cookieSupport = false;
 
     Object.keys(options).forEach(opt => {
       if ( Object.prototype.hasOwnProperty.call(this, opt)
@@ -91,14 +93,29 @@ export abstract class KuzzleAbstractProtocol extends KuzzleEventEmitter {
     return this.state === 'connected';
   }
 
+  /**
+   * `true` if cookie authentication is enabled
+   */
+  get cookieSupport () {
+    return this._cookieSupport;
+  }
+
   get pendingRequests () {
     return this._pendingRequests;
   }
-
+  
   abstract connect (): Promise<any>
-
+  
   abstract send (request: RequestPayload, options: JSONObject): void
 
+
+  /**
+   * Called when we want to enable http cookie support
+   */
+  enableCookieSupport () {
+    this._cookieSupport = true;
+  }
+
   /**
    * Called when the client's connection is established
    */

src/protocols/abstract/Base.ts

@@ -155,4 +155,19 @@ describe('Kuzzle constructor', () => {
       );
     }).not.throw();
   });
+
+  it('should call protocol.enableCookieSupport', () => {
+    /* eslint-disable no-native-reassign */
+    /* eslint-disable no-global-assign */
+    XMLHttpRequest = () => {}; // Faking being in a browser, otherwise kuzzle will throw that cookie are not supported    
+    const kuzzle = new Kuzzle(protocolMock, {
+      cookieAuth: true,
+    });
+
+    should(kuzzle.cookieAuthentication).be.true();
+    should(protocolMock.enableCookieSupport).be.calledOnce();
+    /* eslint-disable no-native-reassign */
+    /* eslint-disable no-global-assign */
+    XMLHttpRequest = undefined; // Reset it to undefined
+  });
 });

test/kuzzle/constructor.test.js

@@ -14,6 +14,7 @@ class ProtocolMock extends KuzzleEventEmitter {
     this.connectCalled = false;
 
     this.close = sinon.stub();
+    this.enableCookieSupport = sinon.stub().returns();
     this.query = sinon.stub().resolves();
     this.playQueue = sinon.stub();
     this.flushQueue = sinon.stub();
@@ -50,6 +51,7 @@ class ProtocolMock extends KuzzleEventEmitter {
     });
   }
 
+
   disconnect () {
     this.state = 'offline';
     this.emit('disconnect');