@soundworks/core 4.0.0-alpha.1 → 4.0.0-alpha.11

package/src/server/Server.js

@@ -5,10 +5,11 @@ import path from 'node:path';
 import os from 'node:os';
 import { X509Certificate, createPrivateKey } from 'node:crypto';
 
+import { getTime } from '@ircam/sc-gettime';
+import { isPlainObject, idGenerator } from '@ircam/sc-utils';
 import chalk from 'chalk';
 import compression from 'compression';
 import express from 'express';
-import isPlainObject from 'is-plain-obj';
 import Keyv from 'keyv';
 import { KeyvFile } from 'keyv-file';
 import merge from 'lodash.merge';
@@ -16,6 +17,7 @@ import pem from 'pem';
 import compile from 'template-literal';
 
 import auditSchema from './audit-schema.js';
+import { encryptData, decryptData } from './crypto.js';
 import Client from './Client.js';
 import ContextManager from './ContextManager.js';
 import PluginManager from './PluginManager.js';
@@ -23,14 +25,37 @@ import StateManager from './StateManager.js';
 import Sockets from './Sockets.js';
 import logger from '../common/logger.js';
 import {
+  SERVER_ID,
   CLIENT_HANDSHAKE_REQUEST,
   CLIENT_HANDSHAKE_RESPONSE,
   CLIENT_HANDSHAKE_ERROR,
   AUDIT_STATE_NAME,
 } from '../common/constants.js';
 
+
 let _dbNamespaces = new Set();
 
+/**
+ * Configuration object for the server.
+ *
+ * @typedef ServerConfig
+ * @memberof server
+ * @type {object}
+ * @property {object} [app] - Application configration object.
+ * @property {object} app.clients - Definition of the application clients.
+ * @property {string} [app.name=''] - Name of the application.
+ * @property {string} [app.author=''] - Name of the author.
+ * @property {object} [env] - Environment configration object.
+ * @property {boolean} env.port - Port on which the server is listening.
+ * @property {boolean} env.useHttps - Define is the server run in http or in https.
+ * @property {boolean} [env.httpsInfos={}] - Path to cert files for https.
+ * @property {boolean} env.serverAddress - Domain name or IP of the server.
+ *  Mandatory if node clients are defined
+ * @property {string} [env.websockets={}] - Configuration options for websockets.
+ * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
+ */
+
+/** @private */
 const DEFAULT_CONFIG = {
   env: {
     type: 'development',
@@ -52,6 +77,8 @@ const DEFAULT_CONFIG = {
   },
 };
 
+const TOKEN_VALID_DURATION = 20; // sec
+
 // set terminal title
 /** @private */
 function setTerminalTitle(server) {
@@ -74,52 +101,89 @@ function setTerminalTitle(server) {
 }
 
 /**
- * Server side entry point for a `soundworks` application.
+ * The `Server` class is the main entry point for the server-side of a soundworks
+ * application.
  *
- * This object hosts configuration informations, as well as methods to
- * initialize and start the application. It is also responsible for creating
- * the static file (http) server as well as the socket server.
- *
- * @memberof server
+ * The `Server` instance allows to access soundworks components such as {@link server.StateManager},
+ * {@link server.PluginManager},{@link server.Socket} or {@link server.ContextManager}.
+ * Its is also responsible for handling the initialization lifecycles of the different
+ * soundworks components.
  *
- * @param {server.ServerConfig} config
- * @example
+ * ```
  * import { Server } from '@soundworks/core/server';
+ *
  * const server = new Server({
  *   app: {
  *     name: 'my-example-app',
- *     clients: { myClient: { target: 'node' } },
+ *     clients: {
+ *       player: { target: 'browser', default: true },
+ *       controller: { target: 'browser' },
+ *       thing: { target: 'node' }
+ *     },
  *   },
  *   env: {
- *     port: 8888,
+ *     port: 8000,
  *   },
  * });
- * await server.init();
+ *
  * await server.start();
+ * ```
+ *
+ * According to the clients definitions provided in `config.app.clients`, the
+ * server will automatically create a dedicated route for each browser client role.
+ * For example, given the config object of the example above that defines two
+ * different client roles for browser targets (i.e. `player` and `controller`):
+ *
+ * ```
+ * config.app.clients = {
+ *   player: { target: 'browser', default: true },
+ *   controller: { target: 'browser' },
+ * }
+ * ```
+ *
+ * The server will listen to the following URLs:
+ * - `http://127.0.0.1:8000/` for the `player` role, which is defined as the default client.
+ * - `http://127.0.0.1:8000/controller` for the `controller` role.
+ *
+ * @memberof server
  */
 class Server {
+  /**
+   * @param {server.ServerConfig} config - Configuration object for the server.
+   * @throws
+   * - If `config.app.clients` is empty.
+   * - If a `node` client is defined but `config.env.serverAddress` is not defined.
+   * - if `config.env.useHttps` is `true` and `config.env.httpsInfos` is not `null`
+   *   (which generates self signed certificated), `config.env.httpsInfos.cert` and
+   *   `config.env.httpsInfos.key` should point to valid cert files.
+   */
   constructor(config) {
     if (!isPlainObject(config)) {
       throw new Error(`[soundworks:Server] Invalid argument for Server constructor, config should be an object`);
     }
     /**
-     * Configuration informations.
-     * Defaults to:
-     * ```
+     * @description Given config object merged with the following defaults:
+     * @example
      * {
      *   env: {
      *     type: 'development',
      *     port: 8000,
-     *     subfolder: '',
+     *     serverAddress: null,
+     *     subpath: '',
+     *     websockets: {
+     *       path: 'socket',
+     *       pingInterval: 5000,
+     *     },
      *     useHttps: false,
      *     httpsInfos: null,
+     *     crossOriginIsolated: true,
+     *     verbose: true,
      *   },
      *   app: {
      *     name: 'soundworks',
      *     clients: {},
-     *   },
+     *   }
      * }
-     * ```
      */
     this.config = merge({}, DEFAULT_CONFIG, config);
 
@@ -161,67 +225,92 @@ class Server {
     }
 
     /**
-     * Router. Internally use polka.
-     * (cf. {@link https://github.com/lukeed/polka})
+     * Instance of the express router.
+     *
+     * The router can be used to open new route, for example to expose a directory
+     * of static assets (in default soundworks applications only the `public` is exposed).
+     *
+     * @see {@link https://github.com/expressjs/express}
+     * @example
+     * import { Server } from '@soundworks/core/server.js';
+     * import express from 'express';
+     *
+     * // create the soundworks server instance
+     * const server = new Server(config);
+     *
+     * // expose assets located in the `soundfiles` directory on the network
+     * server.router.use('/soundfiles', express.static('soundfiles')));
      */
+    // @note: we use express() instead of express.Router() because all 404 and
+    // error stuff is handled by default
     this.router = express();
-    // compression (must be set before serve-static)
+    // compression (must be set before express.static())
     this.router.use(compression());
 
     /**
-     * Http(s) server instance. The node `http` or `https` module instance
-     * (cf. {@link https://nodejs.org/api/http.html})
+     * Raw Node.js `http` or `https` instance
+     *
+     * @see {@link https://nodejs.org/api/http.html}
+     * @see {@link https://nodejs.org/api/https.html}
      */
     this.httpServer = null;
 
     /**
-     * Key / value storage with Promise based Map API
-     * basically a wrapper around kvey (cf. {@link https://github.com/lukechilds/keyv})
-     * @private
-     */
-    this.db = this.createNamespacedDb('core');
-
-    /**
-     * The {@link server.Sockets} instance. A small wrapper around
-     * [`ws`](https://github.com/websockets/ws) server.
+     * Instance of the {@link server.Sockets} class.
+     *
      * @see {@link server.Sockets}
      * @type {server.Sockets}
      */
     this.sockets = new Sockets();
 
     /**
-     * The {@link server.PluginManager} instance.
+     * Instance of the {@link server.PluginManager} class.
+     *
      * @see {@link server.PluginManager}
      * @type {server.PluginManager}
      */
     this.pluginManager = new PluginManager(this);
 
     /**
-     * The {@link server.StateManager} instance.
+     * Instance of the {@link server.StateManager} class.
+     *
      * @see {@link server.StateManager}
      * @type {server.StateManager}
      */
     this.stateManager = new StateManager();
 
     /**
-     * The {@link server.ContextManager} instance.
+     * Instance of the {@link server.ContextManager} class.
      *
+     * @see {@link server.ContextManager}
+     * @type {server.ContextManager}
      */
     this.contextManager = new ContextManager(this);
 
     /**
-     * If https is required, will contain informations about the certificates
-     * (self-signed, validity dates, etc.)
+     * If `https` is required, hold informations about the certificates, e.g. if
+     * self-signed, the dates of validity of the certificates, etc.
      */
     this.httpsInfos = null;
 
     /**
-     * Current status of the server ['idle', 'inited', 'started']
+     * Status of the server, 'idle', 'inited', 'started' or 'errored'.
+     *
+     * @type {string}
      */
     this.status = 'idle';
 
+    /**
+     * Simple key / value database with Promise based Map API store on filesystem,
+     * basically a tiny wrapper around the `kvey` package.
+     *
+     * @private
+     * @see {@link https://github.com/lukechilds/keyv}
+     */
+    this.db = this.createNamespacedDb('core');
+
     /** @private */
-    this._applicationTemplateConfig = {
+    this._applicationTemplateOptions = {
       templateEngine: null,
       templatePath: null,
       clientConfigFunction: null,
@@ -230,9 +319,17 @@ class Server {
     /** @private */
     this._onStatusChangeCallbacks = new Set();
     /** @private */
+    this._onClientConnectCallbacks = new Set();
+    /** @private */
+    this._onClientDisconnectCallbacks = new Set();
+    /** @private */
     this._auditState = null;
+    /** @private */
+    this._pendingConnectionTokens = new Set();
+    /** @private */
+    this._trustedClients = new Set();
 
-    // create audit state
+    // register audit state schema
     this.stateManager.registerSchema(AUDIT_STATE_NAME, auditSchema);
 
     logger.configure(this.config.env.verbose);
@@ -240,18 +337,30 @@ class Server {
   }
 
   /**
-   * Method to be called before `start` in the initialization lifecycle of the
-   * soundworks server. Note that if `init()`` is not explicitely called, `start()`
-   *  will call it implicitely.
+   * Id of the server, a constant set to -1
+   * @type {Number}
+   * @readonly
+   */
+  get id() {
+    return SERVER_ID;
+  }
+
+  /**
+   * The `init` method is part of the initialization lifecycle of the `soundworks`
+   * server. Most of the time, the `init` method will be implicitly called by the
+   * {@link server.Server#start} method.
+   *
+   * In some situations you might want to call this method manually, in such cases
+   * the method should be called before the {@link server.Server#start} method.
    *
    * What it does:
    * - create the audit state
    * - prepapre http(s) server and routing according to the informations
    * declared in `config.app.clients`
-   * - starts all registered plugins
+   * - initialize all registered plugins
    *
-   * After `await server.init()`, you can safely use the StateManager, as well
-   * as any registered Plugins.
+   * After `await server.init()` is fulfilled, the {@link server.Server#stateManager}
+   * and all registered plugins can be safely used.
    *
    * @example
    * const server = new Server(config);
@@ -272,11 +381,24 @@ class Server {
 
     // basic http authentication
     if (this.config.env.auth) {
-      this.router.use((req, res, next) => {
+      const ids = idGenerator();
 
-        const isProtected  = this.config.env.auth.clients
-          .map(type => req.path.endsWith(`/${type}`))
-          .reduce((acc, value) => acc || value, false);
+      const soundworksAuth = (req, res, next) => {
+        let role = null;
+
+        for (let [_role, config] of Object.entries(this.config.app.clients)) {
+          if (req.path === config.route) {
+            role = _role;
+          }
+        }
+
+        // route that are not client entry points just pass through the middleware
+        if (role === null) {
+          next();
+          return;
+        }
+
+        const isProtected  = this.isProtected(role);
 
         if (isProtected) {
           // authentication middleware
@@ -288,20 +410,39 @@ class Server {
           // verify login and password are set and correct
           if (login && password && login === auth.login && password === auth.password) {
             // -> access granted...
+            // generate token for web socket to check connections
+            const id = ids.next().value;
+            const ip = req.ip;
+            const time = getTime();
+            const token = { id, ip, time };
+            const encryptedToken = encryptData(token);
+
+            this._pendingConnectionTokens.add(encryptedToken);
+
+            setTimeout(() => {
+              this._pendingConnectionTokens.delete(encryptedToken);
+            }, TOKEN_VALID_DURATION * 1000);
+
+            // pass to the response object to be send to the client
+            res.swToken = encryptedToken;
+
             return next();
           }
 
-          // -> access denied...
+          // show login / password modal
           res.writeHead(401, {
             'WWW-Authenticate':'Basic',
             'Content-Type':'text/plain',
           });
+
           res.end('Authentication required.');
         } else {
-          // route not protected
+          // route is not protected
           return next();
         }
-      });
+      };
+
+      this.router.use(soundworksAuth);
     }
 
     // start http server
@@ -326,7 +467,7 @@ class Server {
           // this fails with self-signed certificates for whatever reason...
           try {
             x509 = new X509Certificate(cert);
-          } catch(err) {
+          } catch (err) {
             this._dispatchStatus('errored');
             throw new Error(`[soundworks:Server] Invalid https cert file`);
           }
@@ -338,7 +479,7 @@ class Server {
               this._dispatchStatus('errored');
               throw new Error(`[soundworks:Server] Invalid https key file`);
             }
-          } catch(err) {
+          } catch (err) {
             this._dispatchStatus('errored');
             throw new Error(`[soundworks:Server] Invalid https key file`);
           }
@@ -362,7 +503,7 @@ class Server {
           };
 
           this.httpServer = https.createServer({ key, cert }, this.router);
-        } catch(err) {
+        } catch (err) {
           logger.error(`
 Invalid certificate files, please check your:
 - key file: ${httpsInfos.key}
@@ -421,9 +562,9 @@ Invalid certificate files, please check your:
     }
 
     if (!nodeOnly) {
-      if (this._applicationTemplateConfig.templateEngine === null
-        || this._applicationTemplateConfig.templatePath === null
-        || this._applicationTemplateConfig.clientConfigFunction === null
+      if (this._applicationTemplateOptions.templateEngine === null
+        || this._applicationTemplateOptions.templatePath === null
+        || this._applicationTemplateOptions.clientConfigFunction === null
       ) {
         throw new Error('[soundworks:Server] A browser client has been found in "config.app.clients" but configuration for html templating is missing. You should probably call `server.setDefaultTemplateConfig()` if you use the soundworks-template and/or refer (at your own risks) to the documentation of `setCustomTemplateConfig()`');
       }
@@ -464,17 +605,23 @@ Invalid certificate files, please check your:
   }
 
   /**
-   * Method to be called when `init` step is done in the initialization
-   * lifecycle of the soundworks server. If `server.init()` has not been called
-   * explicitely, `server.start()` will call it automatically.
+   * The `start` method is part of the initialization lifecycle of the `soundworks`
+   * server. The `start` method will implicitly call the {@link server.Server#init}
+   * method if it has not been called manually.
    *
    * What it does:
-   * - starts all registered contexts (context are automatically registered
-   * when instantiated)
-   * - start the web socket server
-   * - launch the HTTP server on given port
+   * - implicitely call {@link server.Server#init} if not done manually
+   * - launch the HTTP and WebSocket servers
+   * - start all created contexts. To this end, you will have to call `server.init`
+   * manually and instantiate the contexts between `server.init()` and `server.start()`
    *
-   * After `await server.start()` the server is ready to accept incoming connexions
+   * After `await server.start()` the server is ready to accept incoming connections
+   *
+   * @example
+   * import { Server } from '@soundworks/core/server.js'
+   *
+   * const server = new Server(config);
+   * await server.start();
    */
   async start() {
     if (this.status === 'idle') {
@@ -500,7 +647,7 @@ Invalid certificate files, please check your:
     await this.sockets.start(
       this,
       this.config.env.websockets,
-      (role, socket) => this._onSocketConnection(role, socket),
+      (...args) => this._onSocketConnection(...args),
     );
 
     // ------------------------------------------------------------
@@ -557,15 +704,31 @@ Invalid certificate files, please check your:
 
         await this._dispatchStatus('started');
 
+        if (this.config.env.type === 'development') {
+          logger.log(`\n> press "${chalk.bold('Ctrl + C')}" to exit`);
+        }
+
         resolve();
       });
     });
   }
 
-  // @todo - handle gracefull close of the server (but define what it means first...)
   /**
-   * Stop the server, close all existing WebSocket connections.
-   * Mainly usefull for test.
+   * Stops all started contexts, plugins, close all the socket connections and
+   * the http(s) server.
+   *
+   * In most situations, you might not need to call this method. However, it can
+   * be usefull for unit testing or similar situations where you want to create
+   * and delete several servers in the same process.
+   *
+   * @example
+   * import { Server } from '@soundworks/core/server.js'
+   *
+   * const server = new Server(config);
+   * await server.start();
+   *
+   * await new Promise(resolve => setTimeout(resolve, 1000));
+   * await server.stop();
    */
   async stop() {
     if (this.status !== 'started') {
@@ -603,12 +766,14 @@ Invalid certificate files, please check your:
       route += `${role}`;
     }
 
+    this.config.app.clients[role].route = route;
+
     // define template filename: `${role}.html` or `default.html`
     const {
       templatePath,
       templateEngine,
       clientConfigFunction,
-    } = this._applicationTemplateConfig;
+    } = this._applicationTemplateOptions;
 
     const clientTmpl = path.join(templatePath, `${role}.tmpl`);
     const defaultTmpl = path.join(templatePath, `default.tmpl`);
@@ -619,7 +784,7 @@ Invalid certificate files, please check your:
     try {
       const stats = fs.statSync(clientTmpl);
       template = stats.isFile() ? clientTmpl : defaultTmpl;
-    } catch(err) {
+    } catch (err) {
       template = defaultTmpl;
     }
 
@@ -627,15 +792,21 @@ Invalid certificate files, please check your:
 
     try {
       tmplString = fs.readFileSync(template, 'utf8');
-    } catch(err) {
+    } catch (err) {
       throw new Error(`[soundworks:Server] html template file "${template}" not found`);
     }
 
     const tmpl = templateEngine.compile(tmplString);
-    // http request
-    router.get(route, (req, res) => {
+
+    const soundworksClientHandler = (req, res) => {
       const data = clientConfigFunction(role, this.config, req);
 
+      // if the client has gone through the connection middleware (add succedeed),
+      // add the token to the data object
+      if (res.swToken) {
+        data.token = res.swToken;
+      }
+
       // CORS / COOP / COEP headers for `crossOriginIsolated pages,
       // enables `sharedArrayBuffers` and high precision timers
       // cf. https://web.dev/why-coop-coep/
@@ -649,34 +820,78 @@ Invalid certificate files, please check your:
 
       const appIndex = tmpl(data);
       res.end(appIndex);
-    });
+    };
+
+    // http request
+    router.get(route, soundworksClientHandler);
 
     // return route infos for logging on server start
     return route;
   }
 
+  onClientConnect(callback) {
+    this._onClientConnectCallbacks.add(callback);
+
+    return () => this._onClientConnectCallbacks.delete(callback);
+  }
+
+  onClientDisconnect(callback) {
+    this._onClientDisconnectCallbacks.add(callback);
+
+    return () => this._onClientDisconnectCallbacks.delete(callback);
+  }
+
   /**
    * Socket connection callback.
    * @private
    */
-  _onSocketConnection(role, socket) {
+  _onSocketConnection(role, socket, connectionToken) {
     const client = new Client(role, socket);
     const roles = Object.keys(this.config.app.clients);
 
+    // this has been validated
+    if (this.isProtected(role) && this.isValidConnectionToken(connectionToken)) {
+      const { ip } = decryptData(connectionToken);
+      const newData = {
+        ip: ip,
+        id: client.id,
+      };
+
+      const newToken = encryptData(newData);
+
+      client.token = newToken;
+
+      this._pendingConnectionTokens.delete(connectionToken);
+      this._trustedClients.add(client);
+    }
+
     socket.addListener('close', async () => {
-      // do nothin if client type was invalid
+      // do nothing if client role is invalid
       if (roles.includes(role)) {
         // decrement audit state counter
         const numClients = this._auditState.get('numClients');
         numClients[role] -= 1;
         this._auditState.set({ numClients });
 
-        // clean context manager, await before cleaning state manager
-        await this.contextManager.removeClient(client);
-        // remove client from pluginManager
-        await this.pluginManager.removeClient(client);
-        // clean state manager
-        await this.stateManager.removeClient(client.id);
+        // delete token
+        if (this._trustedClients.has(client)) {
+          this._trustedClients.delete(client);
+        }
+
+        // if something goes wrong here, the 'close' event is called again and
+        // again and again... let's just log the error and terminate the socket
+        try {
+          // clean context manager, await before cleaning state manager
+          await this.contextManager.removeClient(client);
+          // remove client from pluginManager
+          await this.pluginManager.removeClient(client);
+          // clean state manager
+          await this.stateManager.removeClient(client.id);
+
+          this._onClientDisconnectCallbacks.forEach(callback => callback(client));
+        } catch (err) {
+          console.error(err);
+        }
       }
 
       // clean sockets
@@ -698,7 +913,7 @@ Invalid certificate files, please check your:
 
       try {
         this.pluginManager.checkRegisteredPlugins(registeredPlugins);
-      } catch(err) {
+      } catch (err) {
         socket.send(CLIENT_HANDSHAKE_ERROR, {
           type: 'invalid-plugin-list',
           message: err.message,
@@ -723,8 +938,10 @@ Invalid certificate files, please check your:
       // add client to context manager
       await this.contextManager.addClient(client);
 
-      const { id, uuid } = client;
-      socket.send(CLIENT_HANDSHAKE_RESPONSE, { id, uuid });
+      this._onClientConnectCallbacks.forEach(callback => callback(client));
+
+      const { id, uuid, token } = client;
+      socket.send(CLIENT_HANDSHAKE_RESPONSE, { id, uuid, token });
     });
   }
 
@@ -783,8 +1000,8 @@ Invalid certificate files, please check your:
   }
 
   /**
-   * Configure the server to work out-of-the box with the soundworks-template
-   * directory tree structure.
+   * Configure the server to work _out-of-the-box_ within the soundworks application
+   * template provided by `@soundworks/create.
    *
    * - uses [template-literal](https://www.npmjs.com/package/template-literal) package
    * as html templateEngine
@@ -796,9 +1013,33 @@ Invalid certificate files, please check your:
    * Also expose two public directory:
    * - the `public` directory which is exposed behind the root path
    * - the `./.build/public` directory which is exposed behind the `build` path
+   *
+   * _Note: except in very rare cases (so rare that they are quite difficult to imagine),
+   * you should rely on these defaults._
    */
-  setDefaultTemplateConfig() {
-    this._applicationTemplateConfig = {
+  useDefaultApplicationTemplate() {
+    const buildDirectory = path.join('.build', 'public');
+
+    const useMinifiedFile = {};
+    const roles = Object.keys(this.config.app.clients);
+
+    roles.forEach(role => {
+      if (this.config.env.type === 'production') {
+        // check if minified file exists
+        const minifiedFilePath = path.join(buildDirectory, `${role}.min.js`);
+
+        if (fs.existsSync(minifiedFilePath)) {
+          useMinifiedFile[role] = true;
+        } else {
+          console.log(chalk.yellow(`    > Minified file not found for client "${role}", falling back to normal build file (use \`npm run build:production && npm start\` to use minified files)`));
+          useMinifiedFile[role] = false;
+        }
+      } else {
+        useMinifiedFile[role] = false;
+      }
+    });
+
+    this._applicationTemplateOptions = {
       templateEngine: { compile },
       templatePath: path.join('.build', 'server', 'tmpl'),
       clientConfigFunction: (role, config, _httpRequest) => {
@@ -812,30 +1053,41 @@ Invalid certificate files, please check your:
             type: config.env.type,
             websockets: config.env.websockets,
             subpath: config.env.subpath,
+            useMinifiedFile: useMinifiedFile[role],
           },
         };
       },
     };
 
     this.router.use(express.static('public'));
-    this.router.use('/build', express.static(path.join('.build', 'public')));
+    this.router.use('/build', express.static(buildDirectory));
   }
 
   /**
-   * Define your own template path, template engine, and clientConfig function.
-   * This method is for very advanced use-cases and only be used if you know what
-   * you are doing. As such its behavior could probably be improved a lot...
-   *
-   * If you end up using this, please contact me to explain your use-case :)
+   * Define custom template path, template engine, and clientConfig function.
+   * This method is proposed for very advanced use-cases and should very probably
+   * be improved. If you consider using this for some reason, please get in touch
+   * first to explain your use-case :)
    */
-  setCustomTemplateConfig(options) {
-    Object.assign(this._applicationTemplateConfig, options);
+  setCustomApplicationTemplateOptions(options) {
+    Object.assign(this._applicationTemplateOptions, options);
   }
 
   /**
-   * Get the global audit state of the application.
+   * Attach and retrieve the global audit state of the application.
+   *
+   * The audit state is a {@link server.SharedState} instance that keeps track of
+   * global informations about the application such as, the number of connected
+   * clients, network latency estimation, etc.
+   *
+   * The audit state is created by the server on start up.
    *
+   * @returns {Promise<server.SharedState>}
    * @throws Will throw if called before `server.init()`
+   * @see {@link server.SharedState}
+   * @example
+   * const auditState = await server.getAuditState();
+   * auditState.onUpdate(() => console.log(auditState.getValues()), true);
    */
   async getAuditState() {
     if (this.status === 'idle') {
@@ -844,6 +1096,81 @@ Invalid certificate files, please check your:
 
     return this._auditState;
   }
+
+  /** @private */
+  isProtected(role) {
+    if (this.config.env.auth && Array.isArray(this.config.env.auth.clients)) {
+      return this.config.env.auth.clients.includes(role);
+    }
+
+    return false;
+  }
+
+  /** @private */
+  isValidConnectionToken(token) {
+    // token should be in pending token list
+    if (!this._pendingConnectionTokens.has(token)) {
+      return false;
+    }
+
+    // check the token is not too old
+    const data = decryptData(token);
+    const now = getTime();
+
+    // token is valid only for 30 seconds (this is arbitrary)
+    if (now > data.time + TOKEN_VALID_DURATION) {
+      // delete the token, is too old
+      this._pendingConnectionTokens.delete(token);
+      return false;
+    } else {
+      return true;
+    }
+  }
+
+  /**
+   * Check if the given client is trusted, i.e. config.env.type == 'production'
+   * and the client is protected behind a password.
+   *
+   * @param {server.Client} client - Client to be tested
+   * @returns {Boolean}
+   */
+  isTrustedClient(client) {
+    if (this.config.env.type !== 'production') {
+      return true;
+    } else {
+      return this._trustedClients.has(client);
+    }
+  }
+
+  /**
+   * Check if the token from a client is trusted, i.e. config.env.type == 'production'
+   * and the client is protected behind a password.
+   *
+   * @param {Number} clientId - Id of the client
+   * @param {Number} clientIp - Ip of the client
+   * @param {String} token - Token to be tested
+   * @returns {Boolean}
+   */
+  // for stateless interactions, e.g. POST files
+  isTrustedToken(clientId, clientIp, token) {
+    if (this.config.env.type !== 'production') {
+      return true;
+    } else {
+      for (let client of this._trustedClients) {
+        if (client.id === clientId && client.token === token) {
+          // check that given token is consistent with client ip and id
+          const { id, ip } = decryptData(client.token);
+
+          if (clientId === id && clientIp === ip) {
+            return true;
+          }
+        }
+
+      }
+
+      return false;
+    }
+  }
 }
 
 export default Server;