API V3

.eslintrc.js

@@ -9,6 +9,15 @@ module.exports = {
       "commonjs": true,
       "es6": true,
       "node": true,
+      "mocha": true,
       "jquery": true
+    },
+    "rules": {
+      "no-unused-vars": [
+        "error",
+        {
+          "varsIgnorePattern": "should|expect"
+        }
+      ]
     }
   };

.gitignore

@@ -24,3 +24,9 @@ npm-debug.log
 *.heapsnapshot
 
 /tmp
+/.vs
+/cgm-remote-monitor.njsproj
+/cgm-remote-monitor.sln
+/obj/Debug
+/bin
+/*.bat

app.js

@@ -114,11 +114,12 @@ function create (env, ctx) {
     });
   }
 
-  ///////////////////////////////////////////////////
-  // api and json object variables
-  ///////////////////////////////////////////////////
-  var api = require('./lib/api/')(env, ctx);
-  var ddata = require('./lib/data/endpoints')(env, ctx);
+    ///////////////////////////////////////////////////
+    // api and json object variables
+    ///////////////////////////////////////////////////
+    var api = require('./lib/api/')(env, ctx);
+    var api3 = require('./lib/api3/')(env, ctx);
+    var ddata = require('./lib/data/endpoints')(env, ctx);
 
   app.use(compression({
     filter: function shouldCompress (req, res) {
@@ -172,6 +173,8 @@ function create (env, ctx) {
   app.use('/api/v2/authorization', ctx.authorization.endpoints);
   app.use('/api/v2/ddata', ddata);
 
+  app.use('/api/v3', api3);
+
   // pebble data
   app.get('/pebble', ctx.pebble);
 

env.js

@@ -112,6 +112,7 @@ function setStorage() {
   env.authentication_collections_prefix = readENV('MONGO_AUTHENTICATION_COLLECTIONS_PREFIX', 'auth_');
   env.treatments_collection = readENV('MONGO_TREATMENTS_COLLECTION', 'treatments');
   env.profile_collection = readENV('MONGO_PROFILE_COLLECTION', 'profile');
+  env.settings_collection = readENV('MONGO_SETTINGS_COLLECTION', 'settings');
   env.devicestatus_collection = readENV('MONGO_DEVICESTATUS_COLLECTION', 'devicestatus');
   env.food_collection = readENV('MONGO_FOOD_COLLECTION', 'food');
   env.activity_collection = readENV('MONGO_ACTIVITY_COLLECTION', 'activity');

lib/api3/const.json

@@ -0,0 +1,51 @@
+{
+  "API3_VERSION": "3.0.0-alpha",
+  "API3_SECURITY_ENABLE": true,
+  "API3_TIME_SKEW_TOLERANCE": 5,
+  "API3_DEDUP_FALLBACK_ENABLED": true,
+  "API3_CREATED_AT_FALLBACK_ENABLED": true,
+  "API3_MAX_LIMIT": 1000,
+
+  "HTTP": {
+    "OK": 200,
+    "CREATED": 201,
+    "NO_CONTENT": 204,
+    "NOT_MODIFIED": 304,
+    "BAD_REQUEST": 400,
+    "UNAUTHORIZED": 401,
+    "FORBIDDEN": 403,
+    "NOT_FOUND": 404,
+    "GONE": 410,
+    "PRECONDITION_FAILED": 412,
+    "INTERNAL_ERROR": 500
+  },
+
+  "MSG": {
+    "HTTP_400_BAD_LAST_MODIFIED": "Bad or missing Last-Modified header/parameter",
+    "HTTP_400_BAD_LIMIT": "Parameter limit out of tolerance",
+    "HTTP_400_BAD_REQUEST_BODY": "Bad or missing request body",
+    "HTTP_400_BAD_FIELD_IDENTIFIER": "Bad or missing identifier field",
+    "HTTP_400_BAD_FIELD_DATE": "Bad or missing date field",
+    "HTTP_400_BAD_FIELD_UTC": "Bad or missing utcOffset field",
+    "HTTP_400_BAD_FIELD_APP": "Bad or missing app field",
+    "HTTP_400_BAD_SKIP": "Parameter skip out of tolerance",
+    "HTTP_400_SORT_SORT_DESC": "Parameters sort and sort_desc cannot be combined",
+    "HTTP_400_UNSUPPORTED_FILTER_OPERATOR": "Unsupported filter operator {0}",
+    "HTTP_400_IMMUTABLE_FIELD": "Field {0} cannot be modified by the client",
+    "HTTP_401_BAD_DATE": "Bad Date header",
+    "HTTP_401_BAD_TOKEN": "Bad access token or JWT",
+    "HTTP_401_DATE_OUT_OF_TOLERANCE": "Date header out of tolerance",
+    "HTTP_401_MISSING_DATE": "Missing Date header",
+    "HTTP_401_MISSING_OR_BAD_TOKEN": "Missing or bad access token or JWT",
+    "HTTP_403_MISSING_PERMISSION": "Missing permission {0}",
+    "HTTP_403_NOT_USING_HTTPS": "Not using SSL/TLS",
+    "HTTP_500_INTERNAL_ERROR": "Internal Server Error",
+    "STORAGE_ERROR": "Database error",
+    "SOCKET_MISSING_OR_BAD_ACCESS_TOKEN": "Missing or bad accessToken",
+    "SOCKET_UNAUTHORIZED_TO_ANY": "Unauthorized to receive any collection"
+  },
+
+  "MIN_TIMESTAMP": 946684800000,
+  "MIN_UTC_OFFSET": -1440,
+  "MAX_UTC_OFFSET":  1440
+}

lib/api3/doc/security.md

@@ -0,0 +1,48 @@
+# APIv3: Security
+
+### Enforcing HTTPS
+APIv3 is ment to run only under SSL version of HTTP protocol, which provides:
+- **message secrecy** - once the secure channel between client and server is closed the communication cannot be eavesdropped by any third party
+- **message consistency** - each request/response is protected against modification by any third party (any forgery would be detected)
+- **authenticity of identities** - once the client and server establish the secured channel, it is guaranteed that the identity of the client or server does not change during the whole session
+
+HTTPS (in use with APIv3) does not address the true identity of the client, but ensures the correct identity of the server. Furthermore, HTTPS does not prevent the resending of previously intercepted encrypted messages by an attacker.
+
+
+---
+###  Authentication and authorization
+In APIv3, *API_SECRET* can no longer be used for authentication or authorization. Instead, a roles/permissions security model is used, which is managed in the *Admin tools* section of the web application.
+
+
+The identity of the client is represented by the *subject* to whom the access level is set by assigning security *roles*. One or more *permissions* can be assigned to each role. Permissions are used in an [Apache Shiro-like style](http://shiro.apache.org/permissions.html "Apache Shiro-like style").
+
+
+For each security *subject*, the system automatically generates an *access token* that is difficult to guess since it is derived from the secret *API_SECRET*. The *access token* must be included in every secured API operation to decode the client's identity and determine its authorization level. In this way, it is then possible to resolve whether the client has the permission required by a particular API operation.
+
+
+There are two ways to authorize API calls:
+- use `token` query parameter to pass the *access token*, eg. `token=testreadab-76eaff2418bfb7e0`
+- use so-called [JSON Web Tokens](https://jwt.io "JSON Web Tokens")
+  - at first let the `/api/v2/authorization/request` generates you a particular JWT, eg. `GET https://nsapiv3.herokuapp.com/api/v2/authorization/request/testreadab-76eaff2418bfb7e0`
+  - then, to each secure API operation attach a JWT token in the HTTP header, eg. `Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NUb2tlbiI6InRlc3RyZWFkYWItNzZlYWZmMjQxOGJmYjdlMCIsImlhdCI6MTU2NTAzOTczMSwiZXhwIjoxNTY1MDQzMzMxfQ.Y-OFtFJ-gZNJcnZfm9r4S7085Z7YKVPiaQxuMMnraVk` (until the JWT expires)
+
+
+
+---
+###  Client timestamps
+As previously mentioned, a potential attacker cannot decrypt the captured messages, but he can send them back to the client/server at any later time. APIv3 is partially preventing this by the temporal validity of each secured API call.
+
+
+The client must include his current timestamp to each call so that the server can compare it against its clock. If the timestamp difference is not within the limit, the request is considered invalid. The tolerance limit is set in minutes in the `API3_TIME_SKEW_TOLERANCE` environment variable.
+
+There are two ways to include the client timestamp to the call:
+-  use `now` query parameter with UNIX epoch millisecond timestamp, eg. `now=1565041446908`
+- add HTTP `Date` header to the request, eg. `Date: Sun, 12 May 2019 07:49:58 GMT`
+
+
+The client can check each server response in the same way, because each response contains a server timestamp in the HTTP *Date* header as well.
+
+
+---
+APIv3 security is enabled by default, but it can be completely disabled for development and debugging purposes by setting the web environment variable `API3_SECURITY_ENABLE=false`.
+This setting is hazardous and it is strongly discouraged to be used for production purposes!

lib/api3/doc/socket.md

@@ -0,0 +1,142 @@
+# APIv3: Socket.IO storage modifications channel
+
+APIv3 has the ability to broadcast events about all created, edited and deleted documents, using Socket.IO library.
+
+This provides a real-time data exchange experience in combination with API REST operations.
+
+### Complete sample client code
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta http-equiv="x-ua-compatible" content="ie=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+
+    <title>APIv3 Socket.IO sample</title>
+
+    <link rel="icon" href="images/favicon.png" />
+  </head>
+
+  <body>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/2.2.0/socket.io.js"></script>
+
+	<script>
+      const socket = io('https://nsapiv3.herokuapp.com/storage');
+
+      socket.on('connect', function () {
+        socket.emit('subscribe', { 
+          accessToken: 'testadmin-ad3b1f9d7b3f59d5',
+          collections: [ 'entries', 'treatments' ]
+        }, function (data) {
+          if (data.success) {
+            console.log('subscribed for collections', data.collections);
+          }
+          else {
+            console.error(data.message);
+          }
+        });
+      });
+
+      socket.on('create', function (data) {
+        console.log(`${data.colName}:created document`, data.doc);
+      });
+
+      socket.on('update', function (data) {
+        console.log(`${data.colName}:updated document`, data.doc);
+      });
+
+      socket.on('delete', function (data) {
+        console.log(`${data.colName}:deleted document with identifier`, data.identifier);
+      });
+	</script>
+  </body>
+</html>
+```
+
+**Important notice: Only changes made via APIv3 are being broadcasted. All direct database or APIv1 modifications are not included by this channel.**
+
+### Subscription (authorization)
+The client must first subscribe to the channel that is exposed at `storage` namespace, ie the `/storage` subadress of the base Nightscout's web address (without `/api/v3` subaddress).
+```javascript
+const socket = io('https://nsapiv3.herokuapp.com/storage');
+```
+
+
+Subscription is requested by emitting `subscribe` event to the server, while including document with parameters:
+* `accessToken`: required valid accessToken of the security subject, which has been prepared in *Admin Tools* of Nightscout. 
+* `collections`: optional array of collections which the client wants to subscribe to, by default all collections are requested)
+
+```javascript
+socket.on('connect', function () {
+  socket.emit('subscribe', { 
+    accessToken: 'testadmin-ad3b1f9d7b3f59d5',
+    collections: [ 'entries', 'treatments' ]
+  },
+```
+
+
+On the server, the subject is first identified and authenticated (by the accessToken) and then a verification takes place, if the subject has read access to each required collection. 
+
+An exception is the `settings` collection for which `api:settings:admin` permission is required, for all other collections `api:<collection>:read` permission is required.
+
+
+If the authentication was successful and the client has read access to at least one collection, `success` = `true` is set in the response object and the field `collections` contains an array of collections which were actually subscribed (granted).
+In other case `success` = `false` is set in the response object and the field `message` contains an error message.
+
+```javascript
+function (data) {
+    if (data.success) {
+      console.log('subscribed for collections', data.collections);
+    }
+    else {
+      console.error(data.message);
+    }
+  });
+});
+```
+
+### Receiving events
+After the successful subscription the client can start listening to `create`, `update` and/or `delete` events of the socket.
+
+
+##### create
+`create` event fires each time a new document is inserted into the storage, regardless of whether it was CREATE or UPDATE operation of APIv3 (both of these operations are upserting/deduplicating, so they are "insert capable"). If the document already existed in the storage, the `update` event would be fired instead.
+
+The received object contains:
+* `colName` field with the name of the affected collection 
+* the inserted document in `doc` field
+
+```javascript
+socket.on('create', function (data) {
+  console.log(`${data.colName}:created document`, data.doc);
+});
+```
+
+
+##### update
+`update` event fires each time an existing document is modified in the storage, regardless of whether it was CREATE, UPDATE or PATCH operation of APIv3 (all of these operations are "update capable"). If the document did not yet exist in the storage, the `create` event would be fired instead.
+
+The received object contains:
+* `colName` field with the name of the affected collection 
+* the new version of the modified document in `doc` field
+
+```javascript
+socket.on('update', function (data) {
+  console.log(`${data.colName}:updated document`, data.doc);
+});
+```
+
+
+##### delete
+`delete` event fires each time an existing document is deleted in the storage, regardless of whether it was "soft" (marking as invalid) or permanent deleting.
+
+The received object contains:
+* `colName` field with the name of the affected collection 
+* the identifier of the deleted document in the `identifier` field
+
+```javascript
+socket.on('delete', function (data) {
+  console.log(`${data.colName}:deleted document with identifier`, data.identifier);
+});
+```