Add basic workflow for transfering a device to a different user (#525)

* Add basic workflow for transfering a device to a different user

* Add script to generate local docs

* Change claim schema

* Expire token after successful transfer

* Add TTL to config

* Add config to tests

* Move TTL config to models

* Add date param to create token for expires at

* Add PUT and GET methods for transfers

* Add tests for claim model

* Add checks for expiresAt property

* Add unique index for boxId to avoid more than one transfer token for a device

* Add API tests for transfer a device

* Add test for duplicate device id

* Add test for complete transfer of a device

* Reject claim box if token was not found

* Fix doc types and references

* Use timestamp plugin

* Add pre save hook to set default expiresAt

* Check date for timestamps in the past

Author: mpfeil

config/config.example.json

@@ -141,7 +141,7 @@
         // Should be the naked domain and a port
         // No Default
         "url": "mqtt-osem-integration:3925"
-      }
+      },
     },
     "password": {
       // Minimum required password length
@@ -151,6 +151,10 @@
       // Default: 13
       "salt_factor": 12
     },
+    "claims_ttl": {
+      "amount": 1,
+      "unit": "d"
+    },
     // Location on the filesystem where images should be saved
     // Should always end with a trailing slash
     // Default: "./userimages/"

packages/api/lib/controllers/boxesController.js

@@ -37,15 +37,16 @@
  */
 
 const
-  { Box } = require('@sensebox/opensensemap-api-models'),
+  { Box, User, Claim } = require('@sensebox/opensensemap-api-models'),
   { addCache, clearCache, checkContentType, redactEmail, postToSlack } = require('../helpers/apiUtils'),
   { point } = require('@turf/helpers'),
   classifyTransformer = require('../transformers/classifyTransformer'),
   {
     retrieveParameters,
     parseAndValidateTimeParamsForFindAllBoxes,
     validateFromToTimeParams,
-    checkPrivilege
+    checkPrivilege,
+    validateDateNotPast
   } = require('../helpers/userParamHelpers'),
   handleError = require('../helpers/errorHandler'),
   jsonstringify = require('stringify-stream');
@@ -487,24 +488,185 @@ const deleteBox = async function deleteBox (req, res, next) {
   }
 };
 
+/**
+ * @api {get} /boxes/transfer/:senseBoxId Get transfer information for a senseBox
+ * @apiDescription Get transfer information for a senseBox
+ * @apiName getTransfer
+ * @apiGroup Boxes
+ * @apiUse JWTokenAuth
+ * @apiUse BoxIdParam
+ */
+const getTransfer = async function getTransfer (req, res, next) {
+  const { boxId } = req._userParams;
+  try {
+    const transfer = await Claim.findClaimByDeviceID(boxId);
+    res.send(200, {
+      data: transfer,
+    });
+  } catch (err) {
+    handleError(err, next);
+  }
+};
+
+/**
+ * @api {post} /boxes/transfer Mark a senseBox for transferring to a different user
+ * @apiDescription This will mark a senseBox for transfering it to a different user account
+ * @apiName createTransfer
+ * @apiGroup Boxes
+ * @apiParam (RequestBody) {String} boxId ID of the senseBox you want to transfer.
+ * @apiParam (RequestBody) {RFC3339Date} expiresAt Expiration date for transfer token (default: 24 hours from now).
+ * @apiUse JWTokenAuth
+ */
+const createTransfer = async function createTransfer (req, res, next) {
+  const { boxId, date } = req._userParams;
+  try {
+    const transferCode = await req.user.transferBox(boxId, date);
+    res.send(201, {
+      message: 'Box successfully prepared for transfer',
+      data: transferCode,
+    });
+  } catch (err) {
+    handleError(err, next);
+  }
+};
+
+/**
+ * @api {put} /boxes/transfer/:senseBoxId Update a transfer token
+ * @apiDescription Update the expiration date of a transfer token
+ * @apiName updateTransfer
+ * @apiGroup Boxes
+ * @apiParam (RequestBody) {String} Transfer token you want to update.
+ * @apiParam (RequestBody) {RFC3339Date} expiresAt Expiration date for transfer token (default: 24 hours from now).
+ * @apiUse JWTokenAuth
+ * @apiUse BoxIdParam
+ */
+const updateTransfer = async function updateTransfer (req, res, next) {
+  const { boxId, token, date } = req._userParams;
+  try {
+    const transfer = await req.user.updateTransfer(boxId, token, date);
+    res.send(200, {
+      message: 'Transfer successfully updated',
+      data: transfer,
+    });
+  } catch (err) {
+    handleError(err, next);
+  }
+};
+
+/**
+ * @api {delete} /boxes/transfer Revoke transfer token and remove senseBox from transfer
+ * @apiDescription This will revoke the transfer token and remove the senseBox from transfer
+ * @apiName removeTransfer
+ * @apiGroup Boxes
+ * @apiParam (RequestBody) {String} boxId ID of the senseBox you want to remove from transfer.
+ * @apiParam (RequestBody) {String} token Transfer token you want to revoke.
+ * @apiUse JWTokenAuth
+ */
+const removeTransfer = async function removeTransfer (req, res, next) {
+  const { boxId, token } = req._userParams;
+  try {
+    await req.user.removeTransfer(boxId, token);
+    res.send(204);
+  } catch (err) {
+    handleError(err, next);
+  }
+};
+
+/**
+ * @api {post} /boxes/claim Claim a senseBox marked for transfer
+ * @apiDescription This will claim a senseBox marked for transfer
+ * @apiName claimBox
+ * @apiGroup Boxes
+ * @apiUse ContentTypeJSON
+ * @apiParam (RequestBody) {String} token the token to claim a senseBox
+ * @apiUse JWTokenAuth
+ */
+const claimBox = async function claimBox (req, res, next) {
+  const { token } = req._userParams;
+
+  try {
+    const { owner, claim } = await req.user.claimBox(token);
+    await User.transferOwnershipOfBox(owner, claim.boxId);
+
+    await claim.expireToken();
+
+    res.send(200, { message: 'Device successfully claimed!' });
+  } catch (err) {
+    handleError(err, next);
+  }
+};
+
 module.exports = {
   // auth required
   deleteBox: [
     checkContentType,
     retrieveParameters([
       { predef: 'boxId', required: true },
-      { predef: 'password' }
+      { predef: 'password' },
+    ]),
+    checkPrivilege,
+    deleteBox,
+  ],
+  getTransfer: [
+    retrieveParameters([{ predef: 'boxId', required: true }]),
+    checkPrivilege,
+    getTransfer,
+  ],
+  createTransfer: [
+    retrieveParameters([
+      { predef: 'boxId', required: true },
+      { predef: 'dateNoDefault' },
+    ]),
+    validateDateNotPast,
+    checkPrivilege,
+    createTransfer,
+  ],
+  updateTransfer: [
+    retrieveParameters([
+      { predef: 'boxId', required: true },
+      { name: 'token', dataType: 'String' },
+      { predef: 'dateNoDefault', required: true },
     ]),
+    validateDateNotPast,
     checkPrivilege,
-    deleteBox
+    updateTransfer,
+  ],
+  removeTransfer: [
+    retrieveParameters([
+      { predef: 'boxId', required: true },
+      { name: 'token', dataType: 'String' },
+    ]),
+    checkPrivilege,
+    removeTransfer,
+  ],
+  claimBox: [
+    checkContentType,
+    retrieveParameters([{ name: 'token', dataType: 'String' }]),
+    claimBox,
   ],
   getSketch: [
     retrieveParameters([
       { predef: 'boxId', required: true },
-      { name: 'serialPort', dataType: 'String', allowedValues: ['Serial1', 'Serial2'] },
-      { name: 'soilDigitalPort', dataType: 'String', allowedValues: ['A', 'B', 'C'] },
-      { name: 'soundMeterPort', dataType: 'String', allowedValues: ['A', 'B', 'C'] },
-      { name: 'windSpeedPort', dataType: 'String', allowedValues: ['A', 'B', 'C'] },
+      {
+        name: 'serialPort',
+        dataType: 'String',
+        allowedValues: ['Serial1', 'Serial2'],
+      },
+      {
+        name: 'soilDigitalPort',
+        dataType: 'String',
+        allowedValues: ['A', 'B', 'C'],
+      },
+      {
+        name: 'soundMeterPort',
+        dataType: 'String',
+        allowedValues: ['A', 'B', 'C'],
+      },
+      {
+        name: 'windSpeedPort',
+        dataType: 'String',
+        allowedValues: ['A', 'B', 'C'],
+      },
       { name: 'ssid', dataType: 'StringWithEmpty' },
       { name: 'password', dataType: 'StringWithEmpty' },
       { name: 'devEUI', dataType: 'StringWithEmpty' },
@@ -513,7 +675,7 @@ module.exports = {
       { name: 'display_enabled', allowedValues: ['true', 'false'] },
     ]),
     checkPrivilege,
-    getSketch
+    getSketch,
   ],
   updateBox: [
     checkContentType,
@@ -531,21 +693,25 @@ module.exports = {
       { name: 'addons', dataType: 'object' },
       { predef: 'location' },
       { name: 'useAuth', allowedValues: ['true', 'false'] },
-      { name: 'generate_access_token', allowedValues: ['true', 'false'] }
+      { name: 'generate_access_token', allowedValues: ['true', 'false'] },
     ]),
     checkPrivilege,
-    updateBox
+    updateBox,
   ],
   // no auth required
   getBoxLocations: [
     retrieveParameters([
       { predef: 'boxId', required: true },
-      { name: 'format', defaultValue: 'json', allowedValues: ['json', 'geojson'] },
+      {
+        name: 'format',
+        defaultValue: 'json',
+        allowedValues: ['json', 'geojson'],
+      },
       { predef: 'toDate' },
       { predef: 'fromDate' },
       validateFromToTimeParams,
     ]),
-    getBoxLocations
+    getBoxLocations,
   ],
   postNewBox: [
     checkContentType,
@@ -555,44 +721,100 @@ module.exports = {
       { name: 'exposure', allowedValues: Box.BOX_VALID_EXPOSURES },
       { name: 'model', allowedValues: Box.BOX_VALID_MODELS },
       { name: 'sensors', dataType: ['object'] },
-      { name: 'sensorTemplates', dataType: ['String'], allowedValues: ['hdc1080', 'bmp280', 'sds 011', 'tsl45315', 'veml6070', 'bme680', 'smt50', 'soundlevelmeter', 'windspeed', 'scd30', 'dps310'] },
-      { name: 'serialPort', dataType: 'String', defaultValue: 'Serial1', allowedValues: ['Serial1', 'Serial2'] },
-      { name: 'soilDigitalPort', dataType: 'String', defaultValue: 'A', allowedValues: ['A', 'B', 'C'] },
-      { name: 'soundMeterPort', dataType: 'String', defaultValue: 'B', allowedValues: ['A', 'B', 'C'] },
-      { name: 'windSpeedPort', dataType: 'String', defaultValue: 'C', allowedValues: ['A', 'B', 'C'] },
+      {
+        name: 'sensorTemplates',
+        dataType: ['String'],
+        allowedValues: [
+          'hdc1080',
+          'bmp280',
+          'sds 011',
+          'tsl45315',
+          'veml6070',
+          'bme680',
+          'smt50',
+          'soundlevelmeter',
+          'windspeed',
+          'scd30',
+          'dps310',
+        ],
+      },
+      {
+        name: 'serialPort',
+        dataType: 'String',
+        defaultValue: 'Serial1',
+        allowedValues: ['Serial1', 'Serial2'],
+      },
+      {
+        name: 'soilDigitalPort',
+        dataType: 'String',
+        defaultValue: 'A',
+        allowedValues: ['A', 'B', 'C'],
+      },
+      {
+        name: 'soundMeterPort',
+        dataType: 'String',
+        defaultValue: 'B',
+        allowedValues: ['A', 'B', 'C'],
+      },
+      {
+        name: 'windSpeedPort',
+        dataType: 'String',
+        defaultValue: 'C',
+        allowedValues: ['A', 'B', 'C'],
+      },
       { name: 'mqtt', dataType: 'object' },
       { name: 'ttn', dataType: 'object' },
       { name: 'useAuth', allowedValues: ['true', 'false'] },
-      { predef: 'location', required: true }
+      { predef: 'location', required: true },
     ]),
-    postNewBox
+    postNewBox,
   ],
   getBox: [
     retrieveParameters([
       { predef: 'boxId', required: true },
-      { name: 'format', defaultValue: 'json', allowedValues: ['json', 'geojson'] }
+      {
+        name: 'format',
+        defaultValue: 'json',
+        allowedValues: ['json', 'geojson'],
+      },
     ]),
-    getBox
+    getBox,
   ],
   getBoxes: [
     retrieveParameters([
       { name: 'name', dataType: 'String' },
       { name: 'limit', dataType: 'Number', defaultValue: 5, min: 1, max: 20 },
-      { name: 'exposure', allowedValues: Box.BOX_VALID_EXPOSURES, dataType: ['String'] },
+      {
+        name: 'exposure',
+        allowedValues: Box.BOX_VALID_EXPOSURES,
+        dataType: ['String'],
+      },
       { name: 'model', dataType: ['StringWithEmpty'] },
       { name: 'grouptag', dataType: ['StringWithEmpty'] },
       { name: 'phenomenon', dataType: 'StringWithEmpty' },
       { name: 'date', dataType: ['RFC 3339'] },
-      { name: 'format', defaultValue: 'json', allowedValues: ['json', 'geojson'] },
-      { name: 'classify', defaultValue: 'false', allowedValues: ['true', 'false'] },
-      { name: 'minimal', defaultValue: 'false', allowedValues: ['true', 'false'] },
+      {
+        name: 'format',
+        defaultValue: 'json',
+        allowedValues: ['json', 'geojson'],
+      },
+      {
+        name: 'classify',
+        defaultValue: 'false',
+        allowedValues: ['true', 'false'],
+      },
+      {
+        name: 'minimal',
+        defaultValue: 'false',
+        allowedValues: ['true', 'false'],
+      },
       { name: 'full', defaultValue: 'false', allowedValues: ['true', 'false'] },
       { name: 'near' },
       { name: 'maxDistance' },
       { predef: 'bbox' },
     ]),
     parseAndValidateTimeParamsForFindAllBoxes,
     addCache('5 minutes', 'getBoxes'),
-    getBoxes
-  ]
+    getBoxes,
+  ],
 };