auth-server-nest quickstart

See also NestJS quickstart for the role-oriented walkthrough.

Install

pnpm add @vendidit/auth-server-nest

Env

AUTH_SERVER_URL=https://auth.vendidit.com
AUTH_APP_CODE=my-service
JWT_ACCESS_SECRET=<shared with auth-server>
AUTH_CLIENT_ID=<m2m client id, optional>
AUTH_CLIENT_SECRET=<m2m client secret, optional>

Register the module

import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';
import { AuthClientModule, JwtAuthGuard } from '@vendidit/auth-server-nest';

@Module({
    imports: [
        AuthClientModule.forRoot({
            serviceName: 'my-service',
            authServerUrl: process.env.AUTH_SERVER_URL!,
            jwtSecret: process.env.JWT_ACCESS_SECRET!,
            appCode: process.env.AUTH_APP_CODE,
            checkRevocation: true,
        }),
    ],
    providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }],
})
export class AppModule {}

Protect a controller

import { Controller, Get } from '@nestjs/common';
import { CurrentUser, Roles, Public, type AuthenticatedUser } from '@vendidit/auth-server-nest';

@Controller('orders')
export class OrdersController {
    @Get('/me')
    listMine(@CurrentUser() user: AuthenticatedUser) {
        return this.svc.byUser(user.id);
    }

    @Get('/admin')
    @Roles('org_admin', 'system_admin')
    listAll() {
        return this.svc.all();
    }

    @Public()
    @Get('/health')
    health() {
        return { ok: true };
    }
}

Use the m2m client

import { ServiceAuthClient } from '@vendidit/auth-server-nest';

@Injectable()
export class BillingClient {
    constructor(private readonly m2m: ServiceAuthClient) {}

    async chargeUser(userId: string) {
        const token = await this.m2m.getToken();
        return fetch('https://billing.example.com/charge', {
            method: 'POST',
            headers: { Authorization: `Bearer ${token}` },
            body: JSON.stringify({ userId }),
        });
    }
}

Register permissions on boot

import { PERMISSIONS_MANIFEST_TOKEN } from '@vendidit/auth-server-nest';

AuthClientModule.forRoot({
    // ...
    permissions: {
        manifest: {
            service: 'orders',
            permissions: [
                { code: 'orders:read',   resource: 'orders', action: 'read',   name: 'Read orders' },
                { code: 'orders:create', resource: 'orders', action: 'create', name: 'Create order' },
            ],
        },
    },
});

Reconciled idempotently at boot.