@mortezakarimi/nestjs-url-generator

NestJS module for generating & signing URL

Description

URL Generation is used to dynamically generate URL that point to NestJS controller method (Route).

nestjs-url-generator can generate plain and signed URLs

Installation

npm i --save nestjs-url-generator

Or if you use Yarn:

yarn add nestjs-url-generator

Requirements

nestjs-url-generator is built to work with Nest 7 and newer versions.

Basic Usage

Include Module

First you need to import [UrlGeneratorModule]:

app.module.ts

import { UrlGeneratorModule } from 'nestjs-url-generator';

@Module({
  imports: [
    UrlGeneratorModule.forRoot({
      secret: 'secret', // optional, required only for signed URL
      appUrl: 'https://localhost:3000',
    }),
  ],
})
export class ApplicationModule {}

Or Async Import With .ENV usage

.ENV

APP_KEY=secret
APP_URL=https://localhost:3000

signed-url.config.ts

import { UrlGeneratorModuleOptions } from 'nestjs-url-generator';

export function urlGeneratorModuleConfig(): UrlGeneratorModuleOptions {
  return {
    secret: process.env.APP_KEY,
    appUrl: process.env.APP_URL,
  };
}

app.module.ts

import { UrlGeneratorModule } from 'nestjs-url-generator';

@Module({
  imports: [
    ConfigModule.forRoot(),
    UrlGeneratorModule.forRootAsync({
      useFactory: () => urlGeneratorModuleConfig(),
    }),
  ],
})
export class ApplicationModule {}

Using Service

Now you need to register the service, by injecting it to the constructor. There are two methods for generating url:

generateUrlFromController({
  controller,
  controllerMethod,
  /*?*/ query,
  /*?*/ params,
});

generateUrlFromPath({
  relativePath,
  /*?*/ query,
  /*?*/ params,
});

app.controller.ts

import { UrlGeneratorService } from 'nestjs-url-generator';

@Controller()
export class AppController {
  constructor(private readonly urlGeneratorService: UrlGeneratorService) {}

  @Get('makeUrl')
  async makeUrl(): Promise<string> {
    const params = {
      version: '1.0',
      userId: 12,
    };

    const query = {
      email: 'email@email',
    };

    // This will generate:
    // https://localhost:3000/emailVerification/1.0/12?email=email%40email
    return this.urlGeneratorService.generateUrlFromController({
      controller: AppController,
      controllerMethod: AppController.prototype.emailVerification,
      query: query,
      params: params,
    });
  }
}

Generate Signed URL

There are two methods for generating url:

SignControllerUrl({
  controller,
  controllerMethod,
  /*?*/ expirationDate,
  /*?*/ query,
  /*?*/ params,
});

SignUrl({
  relativePath,
  /*?*/ expirationDate,
  /*?*/ query,
  /*?*/ params,
});

app.controller.ts

import { UrlGeneratorService } from 'nestjs-url-generator';

@Controller()
export class AppController {
  constructor(private readonly urlGeneratorService: UrlGeneratorService) {}

  @Get('makeSignUrl')
  async makeSignUrl(): Promise<string> {
    // This will generate:
    // https://localhost:3000/emailVerification?
    // expirationDate=2021-12-12T00%3A00%3A00.000Z&
    // signed=84b5a021c433d0ee961932ac0ec04d5dd5ffd6f7fdb60b46083cfe474dfae3c0
    return this.urlGeneratorService.SignControllerUrl({
      controller: AppController,
      controllerMethod: AppController.prototype.emailVerification,
      expirationDate: new Date('2021-12-12'),
      // or using DateTime library of your choice
      // will be expired 30 minutes after it was created
      expirationDate: dayjs().add(30, 'minute').toDate(),
    });
  }
}

• [expirationDate] and [signed] query keys are used for signed URL.

• By default, the signed URLs lives forever. You can add expiration date to them at the time of generating one.

Reminder

The difference between params & query in ExpressJS

Using Guard

You can use SignUrlGuard to verify the signed url in controller.

If the url has been tampered or when the expiration date is due, then a Forbidden exception will be thrown.

app.controller.ts

import { SignedUrlGuard } from 'nestjs-url-generator';

@Controller()
export class AppController {
  constructor(private readonly urlGeneratorService: UrlGeneratorService) {}

  @Get('emailVerification')
  @UseGuards(SignedUrlGuard)
  async emailVerification(): Promise<string> {
    return 'You emailed has been verified.';
  }
}

Note

• Changing the secret key will invalidate all signed urls

• Signed URL is typically used for unsubscribe email, email verification, sign file permission, and more.

• If you are using https with reverse proxy please make sure to enable trust proxy in express

const app = await NestFactory.create<NestExpressApplication>(AppModule);

app.set('trust proxy', true);
// or
expressSession({ proxy: true });

Generating Keys using node REPL

require('crypto').randomBytes(64, (err, buf) => {
  if (err) throw err;
  console.log(`${buf.length} bytes of random data: ${buf.toString('base64')}`);
  process.exit();
});

TODO

• [ ] Create unit test (expiration, tampered, with or without globalPrefix, request with or without query & param, if target for signerUrl doesn't have guard)

• [ ] Automate CI, npm run build, push, npm publish