DEV Community: Manuel Heidrich

How to secure your OpenAPI Specification and Swagger UI in a NestJS application

Manuel Heidrich — Sun, 21 Mar 2021 11:38:57 +0000

One cool thing about Nest is its dedicated OpenAPI module which allows you to nearly automatically generate an OpenAPI specification for your API. You practically just have to add some decorators here and there and voila.

„The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.“ Read more about the OpenAPI Specification here.

However OAS aims to be open by its name, making your API specifications available to everyone might not always be what you want, for example when your project‘s API is not a public one.

So what to do, when you want to benefit from OAS and the Swagger UI by only giving your team members access?

My strategy usually is protecting the Swagger UI with a password and hiding it on production entirely. This is how you could achieve that.

Getting started

Following the Nest docs, after installing all needed dependencies your main.ts could look something like this:

// main.ts

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('API Docs')
    .setDescription('The API documentation')
    .setVersion('1.0')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('docs', app, document);

  await app.listen(3000);
}
bootstrap();

Swagger UI will be up and running visiting http://localhost:8000/docs in the browser.

Password protection

So first let’s protect the Swagger UI with HTTP basic auth requiring visitors to enter a username and password to access /docs or /docs-json. This can easily be done by implementing express-basic-auth, a simple plug & play HTTP basic auth middleware for Express.

npm i express-basic-auth

After installing express-basic-auth you would want to enable this middleware for your /docs and /docs-json endpoints. To do so modify main.ts like the following:

// main.ts

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import * as basicAuth from 'express-basic-auth';

import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.use(['/docs', '/docs-json'], basicAuth({
    challenge: true,
    users: {
      [process.env.SWAGGER_USER]: process.env.SWAGGER_PASSWORD,
    },
  }));

  const config = new DocumentBuilder()
    .setTitle('API Docs')
    .setDescription('The API documentation')
    .setVersion('1.0')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('docs', app, document);

  await app.listen(3000);
}
bootstrap();

The key to getting this to work is the right order, it is important to apply the middleware app.use(['/docs', '/docs-json'], basicAuth({…}) before you initialize Swagger.

basicAuth() in this scenario expects an object of users, I am using just one here. Keep in mind that it is always a good idea to not hardcode credentials, so relying on environment variables is a good option here. There are quite a few config options to express-basic-auth available, just check out the docs.

Hide Swagger UI on production

As mentioned the second thing I tend to do is hiding Swagger UI entirely on production. The most simple way to do so might be by wrapping a conditional statement around the parts initializing Swagger. Check this out:

// main.ts

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import * as basicAuth from 'express-basic-auth';

import { AppModule } from './app.module';

const SWAGGER_ENVS = ['local', 'dev', 'staging'];

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  if (SWAGGER_ENVS.includes(process.env.NODE_ENV)) {
    app.use(['/docs', '/docs-json'], basicAuth({
      challenge: true,
      users: {
        [process.env.SWAGGER_USER]: process.env.SWAGGER_PASSWORD,
      },
    }));

    const config = new DocumentBuilder()
      .setTitle('API Docs')
      .setDescription('The API documentation')
      .setVersion('1.0')
      .build();

    const document = SwaggerModule.createDocument(app, config);
    SwaggerModule.setup('docs', app, document);
  }

  await app.listen(3000);
}
bootstrap();

This basically only applys the basic auth middleware and initializes Swagger when NODE_ENV is local, dev or staging. Depending on how you handle your environment names or have any other mechanism to check for a prodcution deployment, this may look slightly different in your project, but I think you get the gist.

So that's about it!

How to access the raw body of a Stripe webhook request in NestJS

Manuel Heidrich — Sat, 20 Feb 2021 22:09:22 +0000

"No signatures found matching the expected signature for payload. Are you passing the raw request body you received from Stripe?" This error drove me nuts recently, this is my solution.

For a current project I'm implementing Stripe with a NestJS API. One powerful feature of Stripe are webhooks. To make them secure, each webhook request from Stripe contains a signature in the stripe-signature header. This way it is possible to verify that the webhook request really originates from Stripe. See the Stripe docs for reference.

In Node for example to verify the webhook payload you would use the stripe.webhooks.constructEvent(request.body, signature, endpointSecret) method by passing the raw request body, the mentioned signature header and the endpoint secret obtained in from the Stripe dashboard. And this is where the trouble begins...

NestJS and the raw body

NestJS uses body-parser by default which - you might have guessed it - results in a JSON parsed body. However Stripe's constructEvent() method expects the raw request body, which (unfortunately) hasn't been around in the request object of Express for ages (for good reasons). As NestJS uses Express under the hood by default, you won't find the raw request body there either.

Let's add the raw request body then

After trying (and failing) to convert the JSON body to something Stripe might accept as a raw body, I stumbled upon this Stack Overflow question and implemented a solution based on a modified and extended version of the currently accepted answer by MikingTheViking.

First I had to disable body-parser globally for the whole NestJS application in main.ts.

// main.ts

const app = await NestFactory.create(AppModule, {
  bodyParser: false,
});

Then (also in main.ts) I re-enabled body-parser as a middleware with the verify option set (see the body-parser docs). This allows me to add the raw request body to the request object as a string. As I only want to make rawBody available if really needed, I check for the presence of the stripe-siganture header first and just return if not set.

// main.ts

import * as bodyParser from 'body-parser';

...

const rawBodyBuffer = (req, res, buffer, encoding) => {
  if (!req.headers['stripe-signature']) { return; }

  if (buffer && buffer.length) {
    req.rawBody = buffer.toString(encoding || 'utf8');
  }
};

app.use(bodyParser.urlencoded({ verify: rawBodyBuffer, extended: true }));
app.use(bodyParser.json({ verify: rawBodyBuffer }));

The extra mile (optional but nice)

While this works fine and you can access req.rawBody in your constructor with the help of Nest's @Req() decorator, wouldn't it be nice to use something like @RawBody() similar to @Body() instead?

It would.

Without further ado, here comes your custom @RawBody() decorator:

// raw-body.decorator.ts

import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export const RawBody = createParamDecorator(
  (data: unknown, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();

    return request.rawBody || null;
  },
);

I hope this solution might help someone else too, it is working great for me so far.

A fix for ‘FirebaseCore/FirebaseCore.h file not found’ when using cordova-plugin-firebasex

Manuel Heidrich — Tue, 24 Mar 2020 18:40:01 +0000

When building a Cordova application chances are that you might want to integrate Google Firebase, whether for push notifications, analytics or authentication. Chances also are that like me you would use cordova-plugin-firebasex as it seems to be the most advanced and most actively maintained firebase plugin out there. In my case the extensive Ionic Native wrapper is a plus as well.

As extensive and well-maintained cordova-plugin-firebasex is, there are some quirks that can drive you crazy. One of them is the FirebaseCore/FirebaseCore.h file not found issue on iOS. This issue occurs mostly when running cordova prepare ios, after a fresh checkout for example or if you had to delete the platforms and plugins folders for some other reason. For me the issue occurs literally every time, even so I made sure all pods are up to date (as the plugin docs and issues suggest).

The only thing that seems to work well all the time is removing and re-adding the plugin every time after cordova prepare. This can be a cumbersome task, as you might want to keep the plugins's exact version as well as all custom configuration (which will be removed from package.json on cordova plugin rm).

Recently I just had enough (and sometimes I'am super lazy), so I wrote a script to automate the removing and re-adding of cordova-plugin-firebasex with all it's configuration from package.json.

To hopefully make someone else’s life a little easier as well, I decided to share my script with you, have fun!

const packageJson = require('../package.json');
const { spawn } = require('child_process');

function reinstallFirebase() {
  console.log(`Starting to re-install cordova-plugin-firebasex... Go grab some ☕️ or 🍔 while I'm at it. I will get back to you, as soon as I'm done!`);

  const firebaseVersion = packageJson.dependencies['cordova-plugin-firebasex'];

  let command = `ionic cordova plugin remove cordova-plugin-firebasex && ionic cordova plugin add cordova-plugin-firebasex@${firebaseVersion}`;

  const firebaseOptions = packageJson.cordova.plugins['cordova-plugin-firebasex'];

  for (const option in firebaseOptions) {
    if (firebaseOptions.hasOwnProperty(option)) {
      const value = firebaseOptions[option];

      command += ` --variable ${option}=${value}`;
    }
  }

  const npm = spawn(command, {
    cwd: process.cwd(),
    env: process.env,
    shell: true,
  });

  npm.stdout.on('data', (data) => {
    console.log(data.toString());
  });

  npm.on('close', (code) => {
    console.log(`🎉 Fixed firebase for you! 🔥`);
  });
}

reinstallFirebase();

(I put this script in scripts/reinstall-firebase.js and added ”rf”: “node scripts/reinstall-firebase.js” to scripts in package.json.)

An elegant way to handle native http requests with Cordova Advanced HTTP in an Ionic app

Manuel Heidrich — Tue, 17 Mar 2020 11:53:54 +0000

Despite advantages of cordova-plugin-advanced-http over JavaScript http requests like background threading and SSL pinning I personally do not really like using this plugin.
That’s mostly for two reasons: First I like Angular‘s HttpClient for its observable based interface. Also if you decide to switch to native http requests at a later stage, it can be a whole lot of work to refactor an app, because cordova-plugin-advanced-http uses promises. The second reason is debugging on a device or in the simulator. As the requests will be handled natively, you are not able to see and inspect them in Safari’s network tab.

So for a recent app project I was forced to use native http and this time I sat down for a bit to think about, if I could find a satisfying solution for my two major pain points. First I thought about a custom http service using observables with an interface similar to HttpClient. But as HttpClient is very comprehensive it didn‘t seem to be the best idea to re-invent the wheel.

So why not make HttpClient use cordova-plugin-advanced-http if available? 🤔

HttpInterceptors to the rescue!

A HttpInterceptor is a simple way provided by Angular to intercept and modify HttpRequests globally before they are sent to the server respectively intercept and modify the server’s response.

My idea was to create a HttpInterceptor that automatically handles requests with the native http plugin, if the app is running on a native device. (Or more accurate, if the plugin is available, as cordova-plugin-advanced-http supports the platform browser.) If running in the browser (with ionic serve for example), the interceptor should just do nothing and the request will be handled by HttpClient as expected.

So let's start by creating a new interceptor called native-http.interceptor.ts (A good place to put the interceptor would be the core module.)

import { Injectable } from '@angular/core';
import { HttpInterceptor, HttpHandler, HttpRequest, HttpEvent } from '@angular/common/http';
import { Observable } from 'rxjs/Observable';

@Injectable()
export class NativeHttpInterceptor implements HttpInterceptor {
  intercept(request: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
    return next.handle(request);
  }
}

Next we want to check if the app is running on a device or if the interceptor should just do nothing. I'm doing this by verifying if the platform is cordova.

intercept(request: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
  if (!this.platform.is(‘cordova’)) { return next.handle(request); }

  // some native http magic happening here
}

So, let’s write a method to handle the request natively next. The method will take the original request ( request: HttpRequest<any> ) as the only argument and return Promise<HttpResponse<any>>.

The final method is coming up next, followed by a step-by-step explanation:

private async handleNativeRequest(request: HttpRequest<any>): Promise<HttpResponse<any>> {
    const headerKeys = request.headers.keys();
    const headers = {};

    headerKeys.forEach((key) => {
      headers[key] = request.headers.get(key);
    });

    try {
      await this.platform.ready();

      const method = <HttpMethod> request.method.toLowerCase();

      const nativeHttpResponse = await this.nativeHttp.sendRequest(request.url, {
        method: method,
        data: request.body,
        headers: headers,
        serializer: ‘json’,
      });

      let body;

      try {
        body = JSON.parse(nativeHttpResponse.data);
      } catch (error) {
        body = { response: nativeHttpResponse.data };
      }

      const response = new HttpResponse({
        body: body,
        status: nativeHttpResponse.status,
        headers: nativeHttpResponse.headers,
        url: nativeHttpResponse.url,
      });

      return Promise.resolve(response);
    } catch (error) {
      if (!error.status) { return Promise.reject(error); }

      const response = new HttpResponse({
        body: JSON.parse(error.error),
        status: error.status,
        headers: error.headers,
        url: error.url,
      });

      return Promise.reject(response);
    }
  }

First we need to get the headers of the original request and transform them to an object (key value pair). This format is how cordova-plugin-advanced-http expects headers. You can get the keys of the headers of the original request with request.headers.keys() and then just loop through them to populate the headers object for the plugin.
Next it is a good idea to wait until the platform is ready: await this.platform.ready();
HttpClient’s HttpMethods are uppercase strings, while cordova-plugin-advanced-http expects lowercase strings (see plugin’s docs) . (I created a type for those methods: type HttpMethod = ‘get’ | ‘post’ | ‘put’ | ‘patch’ | ‘head’ | ‘delete’ | ‘upload’ | ‘download’;.)
Now we need to run the native http request and get its response. (see plugin’s docs)
As the response body of cordova-plugin-advanced-http in my case was a stringified JSON object or empty, I had to handle both cases and either return a parsed JSON body or an empty one.
Finally we build a HttpClient’s HttpResponse and resolve the promise.
It’s also always a good idea to handle errors. In this case there could be tow types of errors: a plugin error or an error response from the server. A plugin error does not have a status code (status) so it is pretty easy to check for that.

And now my final NativeHttpInterceptor in its entirety:

import { Injectable } from ‘@angular/core’;
import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent, HttpResponse } from ‘@angular/common/http’;
import { Observable, from } from ‘rxjs’;
import { Platform } from ‘@ionic/angular’;
import { HTTP } from ‘@ionic-native/http/ngx’;

type HttpMethod = ‘get’ | ‘post’ | ‘put’ | ‘patch’ | ‘head’ | ‘delete’ | ‘upload’ | ‘download’;

@Injectable()
export class NativeHttpInterceptor implements HttpInterceptor {
  constructor(
    private nativeHttp: HTTP,
    private platform: Platform,
  ) { }

  public intercept(request: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
    if (!this.platform.is(‘cordova’)) { return next.handle(request); }

    return from(this.handleNativeRequest(request));
  }

  private async handleNativeRequest(request: HttpRequest<any>): Promise<HttpResponse<any>> {
    const headerKeys = request.headers.keys();
    const header = {};

    headerKeys.forEach((key) => {
      headers[key] = request.headers.get(key);
    });

    try {
      await this.platform.ready();

      const method = <HttpMethod> request.method.toLowerCase();

      const nativeHttpResponse = await this.nativeHttp.sendRequest(request.url, {
        method: method,
        data: request.body,
        headers: headers,
        serializer: ‘json’,
      });

      let body;

      try {
        body = JSON.parse(nativeHttpResponse.data);
      } catch (error) {
        body = { response: nativeHttpResponse.data };
      }

      const response = new HttpResponse({
        body: body,
        status: nativeHttpResponse.status,
        headers: nativeHttpResponse.headers,
        url: nativeHttpResponse.url,
      });

      return Promise.resolve(response);
    } catch (error) {
      if (!error.status) { return Promise.reject(error); }

      const response = new HttpResponse({
        body: JSON.parse(error.error),
        status: error.status,
        headers: error.headers,
        url: error.url,
      });

      return Promise.reject(response);
    }
  }
}

This worked pretty neatly in my project and I am very happy with the result. Using cordova-plugin-advanced-http for me is no longer the big pain as it was before.

And what about the debugging issue?

My other pain point was logging. As cordova-plugin-advanced-http handles the requests natively you are not able to see them in Safari’s network tab (when debugging on an iOS device for example). So to see what’s going on I added some console.logs here and there in the interceptor, that I commented out by default.

const method = <HttpMethod> request.method.toLowerCase();

// console.log(‘— Request url’);
// console.log(request.url)
// console.log(‘— Request body’);
// console.log(request.body);

const nativeHttpResponse = await this.nativeHttp.sendRequest(request.url, {
  method: method,
  data: request.body,
  headers: headers,
  serializer: ‘json’,
});

let body;

try {
  body = JSON.parse(nativeHttpResponse.data);
} catch (error) {
  body = { response: nativeHttpResponse.data };
}

const response = new HttpResponse({
  body: body,
  status: nativeHttpResponse.status,
  headers: nativeHttpResponse.headers,
  url: nativeHttpResponse.url,
});

// console.log(‘— Response success’)
// console.log(response);

return Promise.resolve(response);
} catch (error) {
if (!error.status) { return Promise.reject(error); }

// console.log(‘— Response error’)
// console.log(error);

Commenting out those lines might not be the most elegant solution, as well as leaving console functions in a production app isn‘t either. But don‘t worry, I wrote about how to painlessly handle console methods in a production environment in this article. 😎

A hassle-free, zero dependency way to handle console.log() & co. in a production Angular application

Manuel Heidrich — Tue, 10 Mar 2020 06:40:33 +0000

console.log() and its siblings likely are the most used methods any JavaScript developer has ever used. And that‘s totally fine, because console.log() most definitely is a huge help if not even a life saver when debugging an application.

And there is the challenge right there: as helpful as output in the browser‘s console is when debugging, it is absolutely not a good idea to leave this output when deploying your application to production. At least any output below the error level.

So one solution could be to not leave any console methods in the code (except maybe console.error()). Fortunately linters like tslint or eslint have built-in rules to help you with that. But let‘s be honest, we developers usually are lazy af. Also often there are situations where we want to have console output permanently when developing. So it would be a huge hassle to add, remove, re-add (and so on) the console methods.

I wrote about a custom logger service a couple of years ago, which is environment agnostic, but I’m no longer using it. The main reason is that you are not able to see the file and line the output was generated. Plus I do not always want to import and inject a service first. Using console.log() is just so much more convenient.

My solution

For my current side project Monitornator I added a method called handleConsole() to my AppComponent that looks like this:

private handleConsole(): void {
  let methods: string[] = [];

  switch (environment.name) {
    case ‘production’:
    case ‘staging’:
      methods = [‘log’, ‘debug’, ‘info’, ‘warn’];
      break;

    default:
      break;
  }

  if (methods.length) {
    console.warn(`🚨 Console output is disabled on ${environment.name}!`);
  }

  methods.forEach((method) => {
    console[method] = function(): void { };
  });
}

What it does is basically overriding any console method with an empty function, depending on the current environment. So leaving console.log() in the code in this case will just print nothing while on staging or production.
Using switch case allows me to quickly add different log levels for different environments.
And before overriding the methods I print a warning to the console, because... let’s say SOMEONE more then once spent a huge amount of time wondering why console.log() suddenly stopped working while on staging 🤦🏼‍♂️.

Conclusion

Of course there is a fair amount of logging libraries out there, some better than others, but I personally don’t want to add another dependency for something I can solve with just a couple lines of code. The above solution works pretty fine for me.

Pagination in LoopBack 3

Manuel Heidrich — Wed, 12 Jun 2019 06:27:15 +0000

This article was originally published on Medium.

When developing an application with a LoopBack backend it usually won’t take long until you will need some kind of pagination in your frontend to make long lists of countless items more user-friendly to navigate.

Thankfully LoopBack has a skip filter and a limit filter which allows us to implement pagination with just using some url parameters. Your first request to fetch the list would contain

?filter={“skip”:0,”limit”:10}

the next request

?filter={“skip”:10,”limit”:10}

and so on. This is quite useful!

However whether you are building a classic pagination with pages, a load more button or even some kind of infinite scrolling you might want to know exactly how many pages there are or how many items there are left to fetch. In this post I will discuss two options to solve this issue: the X-Total-Count header and the loopback-paginator mixin.

The X-Total-Count header

As the headline might suggest one solution would be to add a header to your response that tells you, how much items there are in total. This can easily be done with the following boot script you just have to place into the server/boot directory.

This will automatically intercept all calls for item lists (find) and add the X-Total-Count header to the response. This also takes filters into account. So if you applied a where filter to your request only items that fit your filter will be counted.

In your frontend you can use that total count to calculate the number of available pages for example or hide the load more button if no more items are available.

The loopback-paginator

The second option is to use the loopback-paginator mixin. (Full disclosure: I’m the author of this mixin which I wrote to have an in my opinion more elegant solution to the pagination problem.) After installing and applying the mixin to your models (check the readme to see all available options), the response body of your GET /api/items requests will look slightly different:

Instead of an array with all your items the body will contain data and meta. Data contains the array of items as you are used to and meta contains some helpful information to implement pagination. You will see the total number of items, the total number of available pages, the number of items per page as well as the current, previous and next page (if available). This solution also takes all your applied filters into account.

I just started working on the paginator last week, but I have some more features in mind and updates will come soon.

So which solution you want to use is totally up to you. They will both optimise the user experience of your application.

Have any questions? Want to let me know what you think? Just post a comment below!

To cross-post or not to cross-post

Manuel Heidrich — Tue, 11 Jun 2019 18:07:59 +0000

As I will be moving away from Medium for blogging (not that much posts yet, but I'm going to hopefully write more this year) I have to decide where to move to.

I really like dev.to so far, but I'm not sure yet if I should run my own blog (with Gatsby.js) and cross-post to dev.to (and others) or if I should use dev.to as my main blog (and cross-post from there).

What do you think, what is your blogging strategy?

Analytics in Ionic 3: Easily Track Page Views with a Custom Decorator

Manuel Heidrich — Tue, 11 Jun 2019 15:33:59 +0000

This post was originally posted on Medium.

If you develop a production Ionic app chances are you also want to integrate some kind of analytics to analyse how your app is being used. There are a lot of different options available like Google Analytics, Firebase or Flurry Analytics, but all they have in common: you have to implement to implement the tracking of your individual views.

I am usually using @ionic-native/google-analytics in my apps and since I did not really want to add this.googleAnalytics.trackView(‘SomePage’) manually to every page I tried different approaches to implement automatic view tracking. What I ended up using is a custom decorator I just need to add to any page I want to track.

How does this decorator look like?

Glad you asked. Like this:

To use it you have to modify your core module as well. If you don’t have a core module you can just do the same in your app.module.ts. (Don’t forget to change line 3 in page-track.decorator.ts in that case!)

Core module example:

And now you just have to import and add the PageTrack() decorator to your page component:

That’s it!

So how does this work?

What the page track decorator basically does is publish a ‘view:enter’ event every time a view is being entered which also passes the page name (the name of the page component to be exact).
I am using the ionViewDidEnter life cycle event of Ionic to achieve that, but you could also use other events depending on when you want the event to be published.

So all I have to do is listen to the ‘view:enter’ event in an analytics service for example and do the actual view tracking there:

I think this is a pretty neat way to add page tracking to an Ionic app. What do you think?