Build it

Build login with argon2id and rotating refresh tokens, a global JWT guard with @Roles(), order queries scoped to the user's sites, a Postgres RLS policy, and safe HTTP headers. The steps need a NestJS project and Postgres on your machine. The scoping rule from step 7 is also an exercise you can run in the browser, in JavaScript and in SQL, in the Practice section below.

1. Create the tables

   The refresh token itself is never stored, only its SHA-256 hash. A fast hash is fine here because the token is 32 random bytes, not a human password, so it cannot be guessed.

   SQLCopy

   CREATE TYPE role AS ENUM ('CASHIER', 'STORE_MANAGER', 'ZONAL_MANAGER', 'HQ_ADMIN');
   
   CREATE TABLE app_user (
     id             bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
     email          text        NOT NULL UNIQUE,
     password_hash  text        NOT NULL,             -- '$argon2id$v=19$m=19456,t=2,p=1$...'
     role           role        NOT NULL,
     is_active      boolean     NOT NULL DEFAULT true
   );
   
   CREATE TABLE user_site (                           -- which stores each user may see
     user_id  bigint NOT NULL REFERENCES app_user (id) ON DELETE CASCADE,
     site_id  bigint NOT NULL REFERENCES site (id),
     PRIMARY KEY (user_id, site_id)
   );
   
   CREATE TABLE refresh_token (
     id          bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
     user_id     bigint      NOT NULL REFERENCES app_user (id) ON DELETE CASCADE,
     family_id   uuid        NOT NULL,                -- all tokens from one login
     token_hash  text        NOT NULL UNIQUE,         -- sha256(token), never the token
     expires_at  timestamptz NOT NULL,
     used_at     timestamptz,                         -- set when it is rotated
     revoked_at  timestamptz,
     created_at  timestamptz NOT NULL DEFAULT now()
   );
   CREATE INDEX refresh_token_family_id_idx ON refresh_token (family_id);

   In Prisma, map them the same way as in Modeling data in tables: a Role enum with @@map("role"), and models User (@@map("app_user")), UserSite with @@id([userId, siteId]), and RefreshToken with familyId String @db.Uuid and tokenHash String @unique.

2. Hash passwords with argon2id

   Install with npm i argon2. The library's defaults are already argon2id with 64 MiB of memory. The settings below are OWASP's stated minimum, which suits small servers. needsRehash lets you raise the cost later: old hashes are upgraded the next time each user logs in.

   TypeScriptCopy

   // src/auth/password.service.ts
   import { Injectable } from '@nestjs/common';
   import * as argon2 from 'argon2';
   
   // OWASP minimum for argon2id: 19 MiB memory, 2 passes, 1 thread.
   // Raise memoryCost until one hash takes roughly 50-250 ms on your server.
   const OPTIONS: argon2.HashOptions = { type: argon2.argon2id, memoryCost: 19_456, timeCost: 2, parallelism: 1 };
   
   @Injectable()
   export class PasswordService {
     hash(password: string): Promise<string> {
       return argon2.hash(password, OPTIONS);          // random salt, stored inside the string
     }
   
     async verify(stored: string, password: string): Promise<{ ok: boolean; newHash?: string }> {
       const ok = await argon2.verify(stored, password);
       if (ok && argon2.needsRehash(stored, OPTIONS)) {
         return { ok, newHash: await this.hash(password) };   // upgrade an older, weaker hash
       }
       return { ok };
     }
   }

3. Issue the tokens at login

   The access token carries the user id, role and site ids, so most requests need no database lookup for authorization. Each login starts a new token family. dummyHash is the hash of a random string, made once at startup. Verifying against it when the email does not exist makes both failures take the same time, so an attacker cannot learn which emails have accounts.

   TypeScriptCopy

   // src/auth/auth.service.ts (part 1)
   import { createHash, randomBytes, randomUUID } from 'node:crypto';
   import { Injectable, UnauthorizedException } from '@nestjs/common';
   import { JwtService } from '@nestjs/jwt';
   
   const sha256 = (s: string) => createHash('sha256').update(s).digest('hex');
   const REFRESH_TTL_MS = 30 * 24 * 3600 * 1000;   // 30 days
   const GRACE_MS = 30_000;                         // app retried after a lost response
   
   @Injectable()
   export class AuthService {
     private readonly dummyHash: Promise<string>;
     constructor(private prisma: PrismaService, private jwt: JwtService, private passwords: PasswordService) {
       this.dummyHash = passwords.hash(randomUUID());   // for "no such email"
     }
   
     async login(email: string, password: string) {
       const user = await this.prisma.user.findUnique({ where: { email } });
       const stored = user?.passwordHash ?? (await this.dummyHash);
       const { ok, newHash } = await this.passwords.verify(stored, password);
       if (!user || !user.isActive || !ok) throw new UnauthorizedException('Wrong email or password');
       if (newHash) await this.prisma.user.update({ where: { id: user.id }, data: { passwordHash: newHash } });
       return this.issueTokens(user.id, randomUUID());   // a new login starts a new family
     }
   
     private async issueTokens(userId: bigint, familyId: string) {
       const user = await this.prisma.user.findUniqueOrThrow({ where: { id: userId }, include: { sites: true } });
       const accessToken = await this.jwt.signAsync({
         sub: user.id.toString(), role: user.role, siteIds: user.sites.map((s) => s.siteId.toString()),
       });
       const refreshToken = randomBytes(32).toString('base64url');   // random, not a JWT
       await this.prisma.refreshToken.create({
         data: { userId, familyId, tokenHash: sha256(refreshToken), expiresAt: new Date(Date.now() + REFRESH_TTL_MS) },
       });
       return { accessToken, refreshToken, expiresIn: 900 };
     }

4. Rotate on refresh, and detect reuse

   The short grace period handles a common mobile case: the app sent the refresh, the response was lost on a weak store network, and the app retried with the same token. Outside the grace period, reuse means theft.

   TypeScriptCopy

   // src/auth/auth.service.ts (part 2, inside AuthService)
     async refresh(refreshToken: string) {
       const row = await this.prisma.refreshToken.findUnique({ where: { tokenHash: sha256(refreshToken) } });
       if (!row || row.revokedAt || row.expiresAt < new Date()) throw new UnauthorizedException();
   
       if (row.usedAt) {
         if (Date.now() - row.usedAt.getTime() < GRACE_MS) return this.issueTokens(row.userId, row.familyId);
         await this.revokeFamily(row.familyId);       // an old token came back: probably stolen
         throw new UnauthorizedException('Session ended, please log in again');
       }
       // Claim it atomically, so two parallel refreshes cannot both rotate it
       const claimed = await this.prisma.refreshToken.updateMany({
         where: { id: row.id, usedAt: null }, data: { usedAt: new Date() },
       });
       if (claimed.count === 0) throw new UnauthorizedException();
       return this.issueTokens(row.userId, row.familyId);
     }
   
     async logout(refreshToken: string) {
       const row = await this.prisma.refreshToken.findUnique({ where: { tokenHash: sha256(refreshToken) } });
       if (row) await this.revokeFamily(row.familyId);
     }
   
     private revokeFamily(familyId: string) {
       return this.prisma.refreshToken.updateMany({ where: { familyId, revokedAt: null }, data: { revokedAt: new Date() } });
     }
   }

5. Verify the access token with passport-jwt

   Install with npm i @nestjs/passport passport passport-jwt @nestjs/jwt and npm i -D @types/passport-jwt. Pin the algorithm, issuer and audience, so a token made for another system, or with a different algorithm, is refused.

   TypeScriptCopy

   // src/auth/jwt.strategy.ts
   import { Injectable } from '@nestjs/common';
   import { PassportStrategy } from '@nestjs/passport';
   import type { Role } from '@prisma/client';
   import { ExtractJwt, Strategy } from 'passport-jwt';
   
   export interface AuthUser { userId: bigint; role: Role; siteIds: bigint[] }   // becomes req.user
   interface AccessPayload { sub: string; role: Role; siteIds: string[] }
   
   @Injectable()
   export class JwtStrategy extends PassportStrategy(Strategy) {
     constructor() {
       super({
         jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),   // Authorization: Bearer ...
         secretOrKey: process.env.JWT_SECRET!,                       // 32+ random bytes
         algorithms: ['HS256'],
         issuer: 'ops-api',
         audience: 'ops-app',
       });                                                           // exp is checked for you
     }
   
     // Runs only after the signature and expiry are valid
     validate(p: AccessPayload): AuthUser {
       return { userId: BigInt(p.sub), role: p.role, siteIds: p.siteIds.map(BigInt) };
     }
   }

6. Add @Public(), @Roles() and two global guards

   Making the JWT guard global means a new endpoint is protected by default. You must opt out with @Public(), which is much safer than remembering to opt in. Guards run in the order they are registered: login first (401), then role (403).

   TypeScriptCopy

   // src/auth/guards.ts
   import { CanActivate, createParamDecorator, ExecutionContext, Injectable, SetMetadata } from '@nestjs/common';
   import { Reflector } from '@nestjs/core';
   import { AuthGuard } from '@nestjs/passport';
   import type { Role } from '@prisma/client';
   
   export const Public = () => SetMetadata('isPublic', true);
   export const Roles = (...roles: Role[]) => SetMetadata('roles', roles);
   export const CurrentUser = createParamDecorator(
     (_d: unknown, ctx: ExecutionContext): AuthUser => ctx.switchToHttp().getRequest().user);
   
   @Injectable()
   export class JwtAuthGuard extends AuthGuard('jwt') {
     constructor(private readonly reflector: Reflector) { super(); }
     canActivate(ctx: ExecutionContext) {
       const isPublic = this.reflector.getAllAndOverride<boolean>('isPublic', [ctx.getHandler(), ctx.getClass()]);
       return isPublic ? true : super.canActivate(ctx);
     }
   }
   
   @Injectable()
   export class RolesGuard implements CanActivate {
     constructor(private readonly reflector: Reflector) {}
     canActivate(ctx: ExecutionContext): boolean {
       const needed = this.reflector.getAllAndOverride<Role[]>('roles', [ctx.getHandler(), ctx.getClass()]);
       if (!needed?.length) return true;                       // logged in is enough
       const user: AuthUser | undefined = ctx.switchToHttp().getRequest().user;
       return !!user && needed.includes(user.role);
     }
   }

   TypeScriptCopy

   // src/auth/auth.module.ts
   @Module({
     imports: [
       PassportModule,
       JwtModule.register({
         secret: process.env.JWT_SECRET,
         signOptions: { expiresIn: '15m', algorithm: 'HS256', issuer: 'ops-api', audience: 'ops-app' },
       }),
     ],
     controllers: [AuthController],      // marked @Public(); add a login rate limit
     providers: [
       PrismaService, AuthService, PasswordService, JwtStrategy,
       { provide: APP_GUARD, useClass: JwtAuthGuard },   // 1. every route needs a valid token
       { provide: APP_GUARD, useClass: RolesGuard },     // 2. then the @Roles() check
     ],
   })
   export class AuthModule {}

7. Scope every order query to the user's sites

   The scoping rule lives in one private method. Every read goes through it, so a new endpoint cannot forget.

   TypeScriptCopy

   // src/orders/orders.service.ts
   @Injectable()
   export class OrdersService {
     constructor(private readonly prisma: PrismaService) {}
   
     private scope(user: AuthUser): Prisma.OrderWhereInput {
       if (user.role === 'HQ_ADMIN') return {};                // head office sees all sites
       return { siteId: { in: user.siteIds } };                // everyone else: own sites only
     }
   
     async findOne(user: AuthUser, id: bigint) {
       const order = await this.prisma.order.findFirst({ where: { AND: [{ id }, this.scope(user)] } });
       if (!order) throw new NotFoundException();              // 404: do not confirm it exists
       return order;
     }
   
     list(user: AuthUser, siteId?: bigint) {
       return this.prisma.order.findMany({
         where: { AND: [this.scope(user), siteId ? { siteId } : {}] },   // ?siteId=31 cannot widen it
         orderBy: { id: 'desc' },
         take: 50,
       });
     }
   }
   
   // src/orders/orders.controller.ts
   @Get(':id')
   @Roles('STORE_MANAGER', 'ZONAL_MANAGER', 'HQ_ADMIN')
   findOne(@CurrentUser() user: AuthUser, @Param('id', ParseIntPipe) id: number) {
     return this.orders.findOne(user, BigInt(id));    // convert bigint fields to strings for JSON
   }

   OutputCopy

   $ curl -s localhost:3000/v1/orders/1001 -H "Authorization: Bearer $TOKEN"   # site 27
   {"id":"1001","siteId":"27","status":"PAID","total":"5400"}
   $ curl -s localhost:3000/v1/orders/1002 -H "Authorization: Bearer $TOKEN"   # site 31
   {"message":"Not Found","statusCode":404}
   $ curl -s localhost:3000/v1/orders/1001
   {"message":"Unauthorized","statusCode":401}

8. Add a row-level security policy as a safety net

   RLS does not apply to the table's owner or to superusers, so the API must connect as a separate role that does not own the tables (the app role from Running Postgres in production). When app.site_ids is not set, current_setting(…, true) returns NULL or an empty string, the comparison is never true, and the query sees zero rows. The default is "deny", which is what you want.

   SQLCopy

   ALTER TABLE "order" ENABLE ROW LEVEL SECURITY;
   
   -- The API role sees and writes only rows for the sites set in this transaction
   CREATE POLICY order_site_scope ON "order"
     USING (site_id = ANY (string_to_array(NULLIF(current_setting('app.site_ids', true), ''), ',')::bigint[]))
     WITH CHECK (site_id = ANY (string_to_array(NULLIF(current_setting('app.site_ids', true), ''), ',')::bigint[]));
   
   -- A read-only reporting role may read every row
   CREATE POLICY order_reporting_all ON "order" FOR SELECT TO reporting_ro USING (true);

   SQLCopy

   -- Try it as the API role
   BEGIN;
   SELECT set_config('app.site_ids', '27,44', true);   -- true: only for this transaction
   SELECT id, site_id FROM "order";                     -- rows for 27 and 44 only
   INSERT INTO "order" (site_id, status, total) VALUES (31, 'PAID', 100);
   COMMIT;

   OutputCopy

    id | site_id
   ----+---------
     1 |      27
     3 |      27
     4 |      44
   (3 rows)
   
   ERROR:  new row violates row-level security policy for table "order"

   In Prisma, set the value inside an interactive transaction. The tagged-template $executeRaw sends the site list as a parameter, so it is safe from injection.

   TypeScriptCopy

   // src/prisma/with-site-scope.ts
   import { PrismaClient } from '@prisma/client';
   
   type Tx = Omit<PrismaClient, '$connect' | '$disconnect' | '$on' | '$transaction' | '$extends'>;
   
   export function withSiteScope<T>(prisma: PrismaClient, user: AuthUser, fn: (tx: Tx) => Promise<T>) {
     return prisma.$transaction(async (tx) => {
       await tx.$executeRaw`SELECT set_config('app.site_ids', ${user.siteIds.join(',')}, true)`;
       return fn(tx);
     });
   }
   
   // usage: the WHERE is still there; RLS catches the day someone forgets it
   const sales = await withSiteScope(this.prisma, user, (tx) => tx.order.findMany({ where: this.scope(user) }));

9. Add security headers, CORS and strict validation

   helmet() sets about a dozen safe response headers, including Strict-Transport-Security (browsers use HTTPS only) and X-Content-Type-Options: nosniff. whitelist drops unknown body fields, which blocks mass assignment.

   TypeScriptCopy

   // src/main.ts
   import helmet from 'helmet';
   
   const app = await NestFactory.create(AppModule);
   app.use(helmet());
   app.enableCors({ origin: ['https://ops.example.com'], methods: ['GET', 'POST', 'PATCH', 'DELETE'] });
   app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true }));

   OutputCopy

   $ curl -sI localhost:3000/v1/orders/1001 -H "Authorization: Bearer $TOKEN"
   Strict-Transport-Security: max-age=31536000; includeSubDomains
   X-Content-Type-Options: nosniff
   X-Frame-Options: SAMEORIGIN
   Content-Security-Policy: default-src 'self';base-uri 'self';...