@opentermsarchive/engine 0.29.1 → 0.30.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentermsarchive/engine",
-  "version": "0.29.1",
+  "version": "0.30.1",
   "description": "Tracks and makes visible changes to the terms of online services",
   "homepage": "https://github.com/OpenTermsArchive/engine#readme",
   "bugs": {
@@ -93,6 +93,7 @@
     "sib-api-v3-sdk": "^8.2.1",
     "simple-git": "^3.8.0",
     "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "4.6.2",
     "winston": "^3.3.3",
     "winston-mail": "^2.0.0"
   },

package/scripts/declarations/validate/index.mocha.js

@@ -78,6 +78,10 @@ export default async options => {
         if (!schemaOnly && service) {
           service.getTermsTypes()
             .filter(termsType => {
+              if (!service.terms[termsType]?.latest) { // If this terms type has been deleted and there is only a historical record for it, but no current valid declaration
+                return false;
+              }
+
               if (servicesTermsTypes[serviceId] && servicesTermsTypes[serviceId].length > 0) {
                 return servicesTermsTypes[serviceId].includes(termsType);
               }

package/src/api/routes/docs.js

@@ -0,0 +1,38 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import express from 'express';
+import swaggerJsdoc from 'swagger-jsdoc';
+import swaggerUi from 'swagger-ui-express';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default function specsRouter(basePath) {
+  const router = express.Router();
+  const specs = swaggerJsdoc({
+    definition: {
+      openapi: '3.1.0',
+      info: {
+        title: 'Open Terms Archive API',
+        version: '1.0.0',
+        license: {
+          name: 'EUPL-1.2',
+          url: 'https://eupl.eu/1.2/',
+        },
+      },
+      servers: [{ url: basePath }],
+    },
+    apis: [`${__dirname}/*.js`],
+  });
+
+  router.use('/docs', swaggerUi.serve);
+  router.get('/docs', (req, res) => {
+    if (req.get('Accept')?.match('json')) { // send OpenAPI spec to machines, Swagger UI to humans
+      return res.json(specs);
+    }
+
+    return swaggerUi.setup(specs)(req, res);
+  });
+
+  return router;
+}

package/src/api/routes/docs.test.js

@@ -0,0 +1,72 @@
+import { expect } from 'chai';
+import config from 'config';
+import request from 'supertest';
+
+import app from '../server.js';
+
+const basePath = config.get('api.basePath');
+
+describe('Docs API', () => {
+  describe('GET /docs', () => {
+    let response;
+
+    context('When requested as JSON', () => {
+      before(async () => {
+        response = await request(app).get(`${basePath}/v1/docs/`).set('Accept', 'application/json');
+      });
+
+      it('responds with 200 status code', () => {
+        expect(response.status).to.equal(200);
+      });
+
+      it('responds with Content-Type application/json', () => {
+        expect(response.type).to.equal('application/json');
+      });
+
+      describe('body response defines', () => {
+        let subject;
+
+        before(async () => {
+          subject = response.body;
+        });
+
+        it('OpenAPI version', () => {
+          expect(subject).to.have.property('openapi');
+        });
+
+        it('paths', () => {
+          expect(subject).to.have.property('paths');
+        });
+
+        describe('with endpoints', () => {
+          before(async () => {
+            subject = response.body.paths;
+          });
+
+          it('/services', () => {
+            expect(subject).to.have.property('/services');
+          });
+
+          it('/service/{serviceId}', () => {
+            expect(subject).to.have.property('/service/{serviceId}');
+          });
+        });
+      });
+    });
+
+    context('When requested as HTML', () => {
+      before(async () => {
+        response = await request(app).get(`${basePath}/v1/docs/`);
+        console.log(response);
+      });
+
+      it('responds with 200 status code', () => {
+        expect(response.status).to.equal(200);
+      });
+
+      it('responds with Content-Type text/html', () => {
+        expect(response.type).to.equal('text/html');
+      });
+    });
+  });
+});

package/src/api/routes/index.js

@@ -1,11 +1,32 @@
 import express from 'express';
+import helmet from 'helmet';
 
+import docsRouter from './docs.js';
 import servicesRouter from './services.js';
-import specsRouter from './specs.js';
 
-const apiRouter = express.Router();
+export default function apiRouter(basePath) {
+  const router = express.Router();
 
-apiRouter.use('/specs', specsRouter);
-apiRouter.use('/services', servicesRouter);
+  const defaultDirectives = helmet.contentSecurityPolicy.getDefaultDirectives();
 
-export default apiRouter;
+  delete defaultDirectives['upgrade-insecure-requests'];
+
+  router.use(helmet({
+    contentSecurityPolicy: {
+      useDefaults: false,
+      directives: defaultDirectives,
+    },
+  })); // Do not enable `upgrade-insecure-requests` directive set by Helmet for docs routes to ensure insecure requests won't be upgraded to secure requests for swaggerUI assets; see https://github.com/center-for-threat-informed-defense/attack-workbench-rest-api/issues/96#issuecomment-924193910 and https://github.com/scottie1984/swagger-ui-express/issues/212#issuecomment-825803088
+
+  router.use(docsRouter(basePath));
+
+  router.use(helmet()); // then, enable all `helmet` HTTP response headers for all others routes
+
+  router.get('/', (req, res) => {
+    res.json({ message: 'Welcome to an instance of the Open Terms Archive API. Documentation is available at /docs. Learn more on Open Terms Archive on https://opentermsarchive.org.' });
+  });
+
+  router.use(servicesRouter);
+
+  return router;
+}

package/src/api/routes/services.js

@@ -74,7 +74,7 @@ const router = express.Router();
  *               items:
  *                 $ref: '#/components/schemas/Service'
  */
-router.get('/', (req, res) => {
+router.get('/services', (req, res) => {
   res.status(200).json(Object.values(services).map(service => ({
     id: service.id,
     name: service.name,
@@ -113,7 +113,7 @@ router.get('/', (req, res) => {
  *       404:
  *         description: No service matching the provided ID is found.
  */
-router.get('/:serviceId', (req, res) => {
+router.get('/service/:serviceId', (req, res) => {
   const matchedServiceID = Object.keys(services).find(key => key.toLowerCase() === req.params.serviceId?.toLowerCase());
   const service = services[matchedServiceID];
 

package/src/api/routes/services.test.js

@@ -39,13 +39,13 @@ describe('Services API', () => {
     });
   });
 
-  describe('GET /services/:serviceId', () => {
+  describe('GET /service/:serviceId', () => {
     let response;
     const SERVICE_ID = 'Service B!';
     const CASE_INSENSITIVE_SERVICE_ID = 'service b!';
 
     before(async () => {
-      response = await request(app).get(`${basePath}/v1/services/${encodeURI(SERVICE_ID)}`);
+      response = await request(app).get(`${basePath}/v1/service/${encodeURI(SERVICE_ID)}`);
     });
 
     it('responds with 200 status code', () => {
@@ -94,7 +94,7 @@ describe('Services API', () => {
 
     context('With a case-insensitive service ID parameter', () => {
       before(async () => {
-        response = await request(app).get(`${basePath}/v1/services/${encodeURI(CASE_INSENSITIVE_SERVICE_ID)}`);
+        response = await request(app).get(`${basePath}/v1/service/${encodeURI(CASE_INSENSITIVE_SERVICE_ID)}`);
       });
 
       it('responds with 200 status code', () => {
@@ -140,7 +140,7 @@ describe('Services API', () => {
 
     context('When no matching service is found', () => {
       before(async () => {
-        response = await request(app).get(`${basePath}/v1/nonExistentService`);
+        response = await request(app).get(`${basePath}/v1/service/nonExistentService`);
       });
 
       it('responds with 404 status code', () => {

package/src/api/server.js

@@ -1,6 +1,5 @@
 import config from 'config';
 import express from 'express';
-import helmet from 'helmet';
 
 import logger from './logger.js';
 import errorsMiddleware from './middlewares/errors.js';
@@ -9,13 +8,13 @@ import apiRouter from './routes/index.js';
 
 const app = express();
 
-app.use(helmet());
-
 if (process.env.NODE_ENV !== 'test') {
   app.use(loggerMiddleware);
 }
 
-app.use(`${config.get('api.basePath')}/v1`, apiRouter);
+const basePath = `${config.get('api.basePath')}/v1`;
+
+app.use(basePath, apiRouter(basePath));
 app.use(errorsMiddleware);
 
 app.listen(config.get('api.port'));

package/src/api/routes/specs.js

@@ -1,28 +0,0 @@
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-import express from 'express';
-import swaggerJsdoc from 'swagger-jsdoc';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const router = express.Router();
-
-router.get('/', (req, res) => {
-  res.json(swaggerJsdoc({
-    definition: {
-      swagger: '2.0',
-      openapi: '3.1.0',
-      info: {
-        title: 'Open Terms Archive API',
-        version: '1.0.0',
-        license: {
-          name: 'EUPL-1.2',
-          url: 'https://eupl.eu/1.2/',
-        },
-      },
-    },
-    apis: [`${__dirname}/*.js`],
-  }));
-});
-
-export default router;

package/src/api/routes/specs.test.js

@@ -1,59 +0,0 @@
-import { expect } from 'chai';
-import config from 'config';
-import request from 'supertest';
-
-import app from '../server.js';
-
-const basePath = config.get('api.basePath');
-
-describe('Specs API', () => {
-  describe('GET /specs', () => {
-    let response;
-
-    before(async () => {
-      response = await request(app).get(`${basePath}/v1/specs`);
-    });
-
-    it('responds with 200 status code', () => {
-      expect(response.status).to.equal(200);
-    });
-
-    it('responds with Content-Type application/json', () => {
-      expect(response.type).to.equal('application/json');
-    });
-
-    describe('body response defines', () => {
-      let subject;
-
-      before(async () => {
-        subject = response.body;
-      });
-
-      it('openapi version', () => {
-        expect(subject).to.have.property('openapi');
-      });
-
-      it('swagger version', () => {
-        expect(subject).to.have.property('swagger');
-      });
-
-      it('paths', () => {
-        expect(subject).to.have.property('paths');
-      });
-
-      describe('with endpoints', () => {
-        before(async () => {
-          subject = response.body.paths;
-        });
-
-        it('/services', () => {
-          expect(subject).to.have.property('/services');
-        });
-
-        it('/service/{serviceId}', () => {
-          expect(subject).to.have.property('/service/{serviceId}');
-        });
-      });
-    });
-  });
-});