feat(hermes): add scalar to eventually replace swagger ui (#921)

* feat(hermes): add scalar to eventually replace swagger ui

note: it throws a build error that we can hack around, but we should find a proper fix.
also, the issue of only client id appearing is also present here

* fix(hermes): add skipLibCheck to bypass ESM issues
refactor(router): fix security schemes when client id/secret is not active
fix(router): blocked scalar routes

libraries/hermes/package.json

@@ -19,6 +19,8 @@
     "@conduitplatform/grpc-sdk": "*",
     "@grpc/grpc-js": "^1.9.7",
     "@grpc/proto-loader": "^0.7.6",
+    "@scalar/api-reference": "^1.13.2",
+    "@scalar/express-api-reference": "^0.2.14",
     "@socket.io/redis-adapter": "^8.2.1",
     "@types/object-hash": "^3.0.6",
     "body-parser": "^1.20.2",

libraries/hermes/src/Rest/Rest.ts

@@ -18,7 +18,7 @@ import ConduitGrpcSdk, {
 import { Cookie } from '../interfaces';
 import { SwaggerRouterMetadata } from '../types';
 import { ConduitRoute, TypeRegistry } from '../classes';
-import { merge } from 'lodash';
+import { apiReference } from '@scalar/express-api-reference';
 
 const swaggerUi = require('swagger-ui-express');
 
@@ -313,6 +313,14 @@ export class RestController extends ConduitRouter {
     this._expressRouter!.get('/swagger', (req, res, next) =>
       swaggerUi.setup(self._swagger!.swaggerDoc)(req, res, next),
     );
+    this._expressRouter!.get(
+      '/reference',
+      apiReference({
+        spec: {
+          url: '/swagger.json',
+        },
+      }),
+    );
     this._expressRouter!.get('/swagger.json', (req, res) => {
       res.send(JSON.stringify(this._swagger!.swaggerDoc));
     });

libraries/hermes/tsconfig.json

@@ -4,6 +4,7 @@
     // "incremental": true,                   /* Enable incremental compilation */
     "target": "es2018",
     "module": "commonjs",
+    "skipLibCheck": true,
     // "lib": [],                             /* Specify library files to be included in the compilation. */
     // "allowJs": true,                       /* Allow javascript files to be compiled. */
     // "checkJs": true,                       /* Report errors in .js files. */

modules/router/src/hermes/swaggerMetadata.ts

@@ -5,19 +5,24 @@ import { ConduitRoute, SwaggerRouterMetadata } from '@conduitplatform/hermes';
 export const getSwaggerMetadata: () => SwaggerRouterMetadata = () => ({
   urlPrefix: '',
   securitySchemes: {
-    clientId: {
-      name: 'clientId',
-      type: 'apiKey',
-      in: 'header',
-      description: 'A security client id, retrievable through [POST] /security/client',
-    },
-    clientSecret: {
-      name: 'clientSecret',
-      type: 'apiKey',
-      in: 'header',
-      description:
-        'A security client secret, retrievable through [POST] /security/client',
-    },
+    ...(ConfigController.getInstance().config.security.clientValidation
+      ? {
+          clientId: {
+            name: 'clientId',
+            type: 'apiKey',
+            in: 'header',
+            description:
+              'A security client id, retrievable through [POST] /security/client',
+          },
+          clientSecret: {
+            name: 'clientSecret',
+            type: 'apiKey',
+            in: 'header',
+            description:
+              'A security client secret, retrievable through [POST] /security/client',
+          },
+        }
+      : {}),
     userToken: {
       type: 'http',
       scheme: 'bearer',

modules/router/src/security/handlers/client-validation/index.ts

@@ -38,7 +38,9 @@ export class ClientValidator {
 
     // check gql explorer and swagger access
     if (
-      (req.url === '/graphql' || req.url.startsWith('/swagger')) &&
+      (req.url === '/graphql' ||
+        req.url.startsWith('/swagger') ||
+        req.url.startsWith('/reference')) &&
       req.method === 'GET'
     ) {
       // disabled swagger and gql explorer access on production

modules/router/src/security/index.ts

@@ -51,7 +51,9 @@ export default class SecurityModule {
       'helmetGqlFix',
       (req: Request, res: Response, next: NextFunction) => {
         if (
-          (req.url.startsWith('/graphql') || req.url.startsWith('/swagger')) &&
+          (req.url.startsWith('/graphql') ||
+            req.url.startsWith('/swagger') ||
+            req.url.startsWith('/reference')) &&
           req.method === 'GET'
         ) {
           res.removeHeader('Content-Security-Policy');

packages/admin/src/index.ts

@@ -156,7 +156,9 @@ export default class AdminModule extends IConduitAdmin {
     this._router.registerMiddleware(helmet(), false);
     this._router.registerMiddleware((req: Request, res: Response, next: NextFunction) => {
       if (
-        (req.url.startsWith('/graphql') || req.url.startsWith('/swagger')) &&
+        (req.url.startsWith('/graphql') ||
+          req.url.startsWith('/swagger') ||
+          req.url.startsWith('/reference')) &&
         req.method === 'GET'
       ) {
         res.removeHeader('Content-Security-Policy');

packages/admin/src/middleware/Admin.middleware.ts

@@ -15,7 +15,9 @@ export function getAdminMiddleware(conduit: ConduitCommons) {
     const graphQlCheck =
       req.originalUrl.indexOf('/graphql') === 0 && req.method === 'GET';
     if (
-      (req.originalUrl.indexOf('/swagger') === 0 || graphQlCheck) &&
+      (req.originalUrl.indexOf('/swagger') === 0 ||
+        req.originalUrl.indexOf('/reference') === 0 ||
+        graphQlCheck) &&
       (await isDev(conduit))
     ) {
       return next();

packages/admin/src/middleware/Auth.middleware.ts

@@ -22,6 +22,7 @@ async function requestExcluded(req: ConduitRequest, conduit: ConduitCommons) {
   if (await isDev(conduit)) {
     if (req.originalUrl.indexOf('/graphql') === 0 && req.method === 'GET') return true;
     if (req.originalUrl.indexOf('/swagger') === 0) return true;
+    if (req.originalUrl.indexOf('/reference') === 0) return true;
   }
   // REST
   if (excludedRestRoutes.includes(req.path)) return true;