Nestjs-signed-url NPM

Project Status

nestjs-signed-url has been moved to nestjs-url-generator.

Description

Signed URL module for for Nest applications.

Installation

npm i --save nestjs-signed-url

Or if you use Yarn:

yarn add nestjs-signed-url

Requirements

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

Basic Usage

Include Module

First you need to import this module into your module:

app.module.ts

import { SignedUrlModule } from 'nestjs-signed-url';

@Module({
    imports: [
        SignedUrlModule.forRoot({
            secret: 'secret',
            appUrl: 'localhost:3000',
        })
    ],
})
export class ApplicationModule {}

Or Async Import With .ENV usage

.ENV

APP_KEY=secret
APP_URL=localhost:3000

signed-url.config.ts

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

app.module.ts

import { SignedUrlModule } from 'nestjs-signed-url';

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

Using Service

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

signedControllerRoute(
    controller: Controller,
    controllerMethod: ControllerMethod,
    expirationDate: Date,
    query?: any,
    params?: any
)

signedRelativePathUrl(
    relativePath: string,
    expirationDate: Date,
    query?: any,
    params?: any
)

app.controller.ts

import { SignedUrlService } from 'nestjs-signed-url';

@Controller()
export class AppController {
    constructor(
        private readonly signedUrlService: SignedUrlService,
    ) { }

    @Get('makeSignedUrl')
    async makeSignedUrl(): Promise<string> {
        const query = {
            id: 1,
            info: 'info',
        }

        return this.signedUrlService.signedControllerRoute(
            AppController,
            AppController.prototype.emailVerification,
            new Date('2021-12-12'),
            query
        )
    }
}

'expirationDate' and 'signed' query are used internally by nestjs-signed-url.

Exception will be thrown if those query are used.

Reminder

Using Guard

You can use SignedUrlGuard 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-signed-url';

@Controller()
export class AppController {
    constructor(
        private readonly signedUrlService: SignedUrlService,
    ) { }

    @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.

TODO

Create test (expiration, query clash, tampered, with or without globalPrefix, request with query & param)
Renovate Automated dependency updates
Add params obj(check if key duplicate in url & replace /:a/:b) long with query obj
Automate CI, npm run build, push, npm publish, npm i (in sample after rebuild)