@ftisindia/create-app 0.1.2 → 0.1.4

package/template/src/modules/audit/dto/list-audit-logs-query.dto.ts

@@ -1,5 +1,5 @@
-import { ApiPropertyOptional } from "@nestjs/swagger";
-import { Type } from "class-transformer";
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
 import {
   IsDateString,
   IsInt,
@@ -9,31 +9,31 @@ import {
   Max,
   MaxLength,
   Min,
-} from "class-validator";
+} from 'class-validator';
 
 export class ListAuditLogsQueryDto {
-  @ApiPropertyOptional({ example: "membership.status.update", maxLength: 120 })
+  @ApiPropertyOptional({ example: 'membership.status.update', maxLength: 120 })
   @IsOptional()
   @IsString()
   @MaxLength(120)
   action?: string;
 
   @ApiPropertyOptional({
-    example: "4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456",
-    format: "uuid",
+    example: '4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456',
+    format: 'uuid',
   })
   @IsOptional()
   @IsUUID()
   actorUserId?: string;
 
-  @ApiPropertyOptional({ example: "Membership", maxLength: 80 })
+  @ApiPropertyOptional({ example: 'Membership', maxLength: 80 })
   @IsOptional()
   @IsString()
   @MaxLength(80)
   targetType?: string;
 
   @ApiPropertyOptional({
-    example: "0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3",
+    example: '0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3',
     maxLength: 120,
   })
   @IsOptional()
@@ -42,16 +42,16 @@ export class ListAuditLogsQueryDto {
   targetId?: string;
 
   @ApiPropertyOptional({
-    example: "2026-06-01T00:00:00.000Z",
-    format: "date-time",
+    example: '2026-06-01T00:00:00.000Z',
+    format: 'date-time',
   })
   @IsOptional()
   @IsDateString()
   from?: string;
 
   @ApiPropertyOptional({
-    example: "2026-06-02T00:00:00.000Z",
-    format: "date-time",
+    example: '2026-06-02T00:00:00.000Z',
+    format: 'date-time',
   })
   @IsOptional()
   @IsDateString()
@@ -66,8 +66,8 @@ export class ListAuditLogsQueryDto {
   limit?: number;
 
   @ApiPropertyOptional({
-    example: "df6537c4-f58b-452e-a67e-18ec528d0f0f",
-    format: "uuid",
+    example: 'df6537c4-f58b-452e-a67e-18ec528d0f0f',
+    format: 'uuid',
   })
   @IsOptional()
   @IsUUID()

package/template/src/modules/audit/presentation/audit.controller.ts

@@ -1,37 +1,31 @@
-import { Controller, Get, Param, Query, UseGuards } from "@nestjs/common";
-import {
-  ApiBearerAuth,
-  ApiOkResponse,
-  ApiOperation,
-  ApiParam,
-  ApiTags,
-} from "@nestjs/swagger";
-import { ApiProtectedErrorResponses } from "../../../common/swagger/api-error-responses";
-import { PermissionGuard } from "../../access-control/application/services/permission.guard";
-import { RequirePermissions } from "../../access-control/presentation/permissions.decorator";
-import { JwtAuthGuard } from "../../auth/infrastructure/passport/jwt-auth.guard";
-import { OrgScopeGuard } from "../../request-context/presentation/org-scope.guard";
-import { AuditService } from "../application/services/audit.service";
-import { AuditLogListResponseDto } from "../dto/audit-response.dto";
-import { ListAuditLogsQueryDto } from "../dto/list-audit-logs-query.dto";
+import { Controller, Get, Param, Query, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, ApiOkResponse, ApiOperation, ApiParam, ApiTags } from '@nestjs/swagger';
+import { ApiProtectedErrorResponses } from '../../../common/swagger/api-error-responses';
+import { PermissionGuard } from '../../access-control/application/services/permission.guard';
+import { RequirePermissions } from '../../access-control/presentation/permissions.decorator';
+import { JwtAuthGuard } from '../../auth/infrastructure/passport/jwt-auth.guard';
+import { OrgScopeGuard } from '../../request-context/presentation/org-scope.guard';
+import { AuditService } from '../application/services/audit.service';
+import { AuditLogListResponseDto } from '../dto/audit-response.dto';
+import { ListAuditLogsQueryDto } from '../dto/list-audit-logs-query.dto';
 
-@ApiTags("Audit")
+@ApiTags('Audit')
 @ApiBearerAuth()
-@ApiParam({ name: "orgId", description: "Organisation ID.", format: "uuid" })
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
 @ApiProtectedErrorResponses()
-@Controller("organisations/:orgId/audit")
+@Controller('organisations/:orgId/audit')
 @UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
 export class AuditController {
   constructor(private readonly auditService: AuditService) {}
 
   @Get()
-  @RequirePermissions("audit.read")
-  @ApiOperation({ summary: "List audit logs for an organisation." })
+  @RequirePermissions('audit.read')
+  @ApiOperation({ summary: 'List audit logs for an organisation.' })
   @ApiOkResponse({
-    description: "Audit log page.",
+    description: 'Audit log page.',
     type: AuditLogListResponseDto,
   })
-  list(@Param("orgId") orgId: string, @Query() query: ListAuditLogsQueryDto) {
+  list(@Param('orgId') orgId: string, @Query() query: ListAuditLogsQueryDto) {
     return this.auditService.listOrgLogs(orgId, query);
   }
 }

package/template/src/modules/auth/application/services/auth.service.ts

@@ -3,26 +3,34 @@ import {
   ForbiddenException,
   Injectable,
   UnauthorizedException,
-} from "@nestjs/common";
-import { ConfigService } from "@nestjs/config";
-import { AuthProvider, Prisma, User } from "@prisma/client";
-import { createHash, randomBytes } from "crypto";
-import { PrismaService } from "../../../../database/prisma/prisma.service";
-import { LoginDto } from "../../dto/login.dto";
-import { LogoutDto } from "../../dto/logout.dto";
-import { OAuthExchangeDto } from "../../dto/oauth-exchange.dto";
-import { RefreshTokenDto } from "../../dto/refresh-token.dto";
-import { SignupDto } from "../../dto/signup.dto";
-import { AuthenticatedUser } from "../../types/authenticated-user";
-import { GoogleAuthProfile } from "../../types/google-auth-profile";
-import { PasswordService } from "./password.service";
-import { TokenService } from "./token.service";
-
-const DUMMY_PASSWORD_HASH =
-  "$2b$12$1rpQSsxHfzUmzLtIlCH5Hu4KDsKz.NNTkQ3kqMT1kJxCgW4YodNTm";
+} from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { AuthProvider, Prisma, User } from '@prisma/client';
+import { createHash, randomBytes } from 'crypto';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { LoginDto } from '../../dto/login.dto';
+import { LogoutDto } from '../../dto/logout.dto';
+import { OAuthExchangeDto } from '../../dto/oauth-exchange.dto';
+import { RefreshTokenDto } from '../../dto/refresh-token.dto';
+import { SignupDto } from '../../dto/signup.dto';
+import { AuthenticatedUser } from '../../types/authenticated-user';
+import { GoogleAuthProfile } from '../../types/google-auth-profile';
+import { PasswordService } from './password.service';
+import { TokenService } from './token.service';
+
+const DUMMY_PASSWORD_HASH = '$2b$12$1rpQSsxHfzUmzLtIlCH5Hu4KDsKz.NNTkQ3kqMT1kJxCgW4YodNTm';
 const OAUTH_EXCHANGE_CODE_TTL_MS = 5 * 60 * 1000;
-const SIGNUP_CONFLICT_MESSAGE =
-  "Unable to complete signup with the provided details.";
+const SIGNUP_CONFLICT_MESSAGE = 'Unable to complete signup with the provided details.';
+
+type RefreshResult =
+  | {
+      status: 'rotated';
+      refreshToken: string;
+    }
+  | {
+      status: 'reuse_detected' | 'invalid';
+    };
 
 @Injectable()
 export class AuthService {
@@ -30,6 +38,7 @@ export class AuthService {
     private readonly config: ConfigService,
     private readonly passwordService: PasswordService,
     private readonly prisma: PrismaService,
+    private readonly requestContext: RequestContextService,
     private readonly tokenService: TokenService,
   ) {}
 
@@ -68,11 +77,11 @@ export class AuthService {
         });
 
         await this.writeAudit(tx, {
-          action: "auth.signup",
+          action: 'auth.signup',
           actorUserId: createdUser.id,
-          targetType: "User",
+          targetType: 'User',
           targetId: createdUser.id,
-          metadata: { provider: "email_password", email },
+          metadata: { provider: 'email_password', email },
         });
 
         return createdUser;
@@ -102,21 +111,18 @@ export class AuthService {
       throw invalidCredentials();
     }
 
-    const passwordMatches = await this.passwordService.verify(
-      dto.password,
-      user.passwordHash,
-    );
+    const passwordMatches = await this.passwordService.verify(dto.password, user.passwordHash);
     if (!passwordMatches) {
       await this.recordFailedLogin(email, user.id);
       throw invalidCredentials();
     }
 
     await this.writeAudit(this.prisma, {
-      action: "auth.login.success",
+      action: 'auth.login.success',
       actorUserId: user.id,
-      targetType: "User",
+      targetType: 'User',
       targetId: user.id,
-      metadata: { provider: "email_password", email },
+      metadata: { provider: 'email_password', email },
     });
 
     return this.buildAuthResponse(user);
@@ -145,36 +151,67 @@ export class AuthService {
       throw invalidCredentials();
     }
 
-    const result = await this.prisma.$transaction(async (tx) => {
-      const next = await this.tokenService.createRefreshToken(
-        existing.userId,
-        tx,
-      );
+    const result: RefreshResult = await this.prisma.$transaction(async (tx) => {
+      // Atomically claim the rotation: only the request that flips revokedAt
+      // from null wins. Under READ COMMITTED a concurrent refresh presenting
+      // the same token blocks on the row lock, then re-evaluates this WHERE
+      // against the committed row, matches zero rows, and is rejected — so
+      // exactly one replacement is ever minted and no live token escapes the
+      // reuse-detection chain. The replacement is created only after winning.
+      const claimed = await tx.refreshToken.updateMany({
+        where: { id: existing.id, revokedAt: null },
+        data: { revokedAt: new Date() },
+      });
+
+      if (claimed.count === 0) {
+        // Lost the race to a concurrent refresh of the same token. The genuine
+        // stolen-token replay is handled here as well: after the winning
+        // transaction commits, the row is visible with a replacement pointer,
+        // so revoke the replacement family in this transaction before returning
+        // 401 outside the transaction. Do not throw here, or Prisma rolls back
+        // the revocation.
+        const current = await tx.refreshToken.findUnique({
+          where: { id: existing.id },
+          select: { replacedByTokenId: true },
+        });
+        if (current?.replacedByTokenId) {
+          await this.recordRefreshTokenReuse(tx, existing.id, existing.userId);
+          return { status: 'reuse_detected' };
+        }
+
+        return { status: 'invalid' };
+      }
+
+      const next = await this.tokenService.createRefreshToken(existing.userId, tx);
 
       await tx.refreshToken.update({
         where: { id: existing.id },
-        data: {
-          revokedAt: new Date(),
-          replacedByTokenId: next.record.id,
-        },
+        data: { replacedByTokenId: next.record.id },
       });
 
       await this.writeAudit(tx, {
-        action: "auth.refresh",
+        action: 'auth.refresh',
         actorUserId: existing.userId,
-        targetType: "RefreshToken",
+        targetType: 'RefreshToken',
         targetId: existing.id,
         metadata: { replacedByTokenId: next.record.id },
       });
 
-      return next.refreshToken;
+      return {
+        status: 'rotated',
+        refreshToken: next.refreshToken,
+      };
     });
 
+    if (result.status !== 'rotated') {
+      throw invalidCredentials();
+    }
+
     return {
       accessToken: await this.tokenService.signAccessToken(existing.user),
-      refreshToken: result,
-      tokenType: "Bearer",
-      expiresIn: this.tokenService.getAccessTokenTtl(),
+      refreshToken: result.refreshToken,
+      tokenType: 'Bearer',
+      expiresIn: this.tokenService.getAccessTokenTtlSeconds(),
       user: toSafeUser(existing.user),
     };
   }
@@ -197,9 +234,9 @@ export class AuthService {
       });
 
       await this.writeAudit(tx, {
-        action: "auth.logout",
+        action: 'auth.logout',
         actorUserId: token.userId,
-        targetType: "RefreshToken",
+        targetType: 'RefreshToken',
         targetId: token.id,
       });
     });
@@ -224,17 +261,24 @@ export class AuthService {
     }
 
     await this.prisma.$transaction(async (tx) => {
-      await tx.authExchangeCode.update({
-        where: { id: existing.id },
+      // Atomically claim the one-time code: only the request that flips usedAt
+      // from null wins, so concurrent exchanges of the same code can't both
+      // mint a session. The loser matches zero rows and is rejected.
+      const claimed = await tx.authExchangeCode.updateMany({
+        where: { id: existing.id, usedAt: null },
         data: { usedAt: new Date() },
       });
 
+      if (claimed.count === 0) {
+        throw invalidCredentials();
+      }
+
       await this.writeAudit(tx, {
-        action: "auth.oauth.exchange",
+        action: 'auth.oauth.exchange',
         actorUserId: existing.userId,
-        targetType: "AuthExchangeCode",
+        targetType: 'AuthExchangeCode',
         targetId: existing.id,
-        metadata: { provider: "google" },
+        metadata: { provider: 'google' },
       });
     });
 
@@ -245,7 +289,7 @@ export class AuthService {
     this.assertGoogleEnabled();
 
     if (!profile.emailVerified) {
-      throw new UnauthorizedException("Google email address is not verified.");
+      throw new UnauthorizedException('Google email address is not verified.');
     }
 
     const email = normalizeEmail(profile.email);
@@ -266,11 +310,11 @@ export class AuthService {
         }
 
         await this.writeAudit(tx, {
-          action: "auth.google.login",
+          action: 'auth.google.login',
           actorUserId: existingIdentity.userId,
-          targetType: "User",
+          targetType: 'User',
           targetId: existingIdentity.userId,
-          metadata: { provider: "google", email },
+          metadata: { provider: 'google', email },
         });
 
         return existingIdentity.user;
@@ -295,11 +339,11 @@ export class AuthService {
         });
 
         await this.writeAudit(tx, {
-          action: "auth.google.link",
+          action: 'auth.google.link',
           actorUserId: existingUser.id,
-          targetType: "User",
+          targetType: 'User',
           targetId: existingUser.id,
-          metadata: { provider: "google", email },
+          metadata: { provider: 'google', email },
         });
 
         return existingUser;
@@ -322,21 +366,19 @@ export class AuthService {
       });
 
       await this.writeAudit(tx, {
-        action: "auth.google.signup",
+        action: 'auth.google.signup',
         actorUserId: createdUser.id,
-        targetType: "User",
+        targetType: 'User',
         targetId: createdUser.id,
-        metadata: { provider: "google", email },
+        metadata: { provider: 'google', email },
       });
 
       return createdUser;
     });
 
     const code = await this.createOAuthExchangeCode(user.id);
-    const redirectUrl = new URL(
-      this.config.get<string>("auth.google.successRedirectUrl") ?? "",
-    );
-    redirectUrl.searchParams.set("code", code);
+    const redirectUrl = new URL(this.config.get<string>('auth.google.successRedirectUrl') ?? '');
+    redirectUrl.searchParams.set('code', code);
 
     return redirectUrl.toString();
   }
@@ -351,14 +393,14 @@ export class AuthService {
     return {
       accessToken: await this.tokenService.signAccessToken(user),
       refreshToken: refresh.refreshToken,
-      tokenType: "Bearer",
-      expiresIn: this.tokenService.getAccessTokenTtl(),
+      tokenType: 'Bearer',
+      expiresIn: this.tokenService.getAccessTokenTtlSeconds(),
       user: toSafeUser(user),
     };
   }
 
   private async createOAuthExchangeCode(userId: string) {
-    const code = randomBytes(48).toString("base64url");
+    const code = randomBytes(48).toString('base64url');
     await this.prisma.authExchangeCode.create({
       data: {
         userId,
@@ -370,54 +412,51 @@ export class AuthService {
     return code;
   }
 
-  private async handleRefreshTokenReuse(
+  private async handleRefreshTokenReuse(refreshTokenId: string, userId: string) {
+    await this.prisma.$transaction(async (tx) => {
+      await this.recordRefreshTokenReuse(tx, refreshTokenId, userId);
+    });
+  }
+
+  private async recordRefreshTokenReuse(
+    tx: Prisma.TransactionClient,
     refreshTokenId: string,
     userId: string,
   ) {
-    await this.prisma.$transaction(async (tx) => {
-      const now = new Date();
-      const revokedIds = await revokeRefreshTokenDescendants(
-        tx,
-        refreshTokenId,
-        now,
-      );
-
-      await this.writeAudit(tx, {
-        action: "auth.refresh.reuse_detected",
-        actorUserId: userId,
-        targetType: "RefreshToken",
-        targetId: refreshTokenId,
-        metadata: {
-          revokedTokenIds: revokedIds,
-        },
-      });
+    const now = new Date();
+    const revokedIds = await revokeRefreshTokenDescendants(tx, refreshTokenId, now);
+
+    await this.writeAudit(tx, {
+      action: 'auth.refresh.reuse_detected',
+      actorUserId: userId,
+      targetType: 'RefreshToken',
+      targetId: refreshTokenId,
+      metadata: {
+        revokedTokenIds: revokedIds,
+      },
     });
   }
 
   private assertEmailPasswordEnabled() {
-    const enabled = this.config.get<boolean>(
-      "auth.providers.emailPasswordEnabled",
-    );
+    const enabled = this.config.get<boolean>('auth.providers.emailPasswordEnabled');
     if (!enabled) {
-      throw new ForbiddenException(
-        "Email/password authentication is disabled.",
-      );
+      throw new ForbiddenException('Email/password authentication is disabled.');
     }
   }
 
   private assertGoogleEnabled() {
-    const enabled = this.config.get<boolean>("auth.providers.googleEnabled");
+    const enabled = this.config.get<boolean>('auth.providers.googleEnabled');
     if (!enabled) {
-      throw new ForbiddenException("Google authentication is disabled.");
+      throw new ForbiddenException('Google authentication is disabled.');
     }
   }
 
   private async recordFailedLogin(email: string, actorUserId?: string) {
     await this.writeAudit(this.prisma, {
-      action: "auth.login.failed",
+      action: 'auth.login.failed',
       actorUserId,
-      targetType: "Auth",
-      metadata: { provider: "email_password", email },
+      targetType: 'Auth',
+      metadata: { provider: 'email_password', email },
     });
   }
 
@@ -439,13 +478,15 @@ export class AuthService {
         targetType: data.targetType,
         targetId: data.targetId,
         metadata: data.metadata,
+        ipAddress: this.requestContext.getIpAddress(),
+        userAgent: this.requestContext.getUserAgent(),
       },
     });
   }
 }
 
 function hashOneTimeCode(code: string) {
-  return createHash("sha256").update(code).digest("hex");
+  return createHash('sha256').update(code).digest('hex');
 }
 
 async function revokeRefreshTokenDescendants(
@@ -457,13 +498,12 @@ async function revokeRefreshTokenDescendants(
   let cursor: string | null = refreshTokenId;
 
   while (cursor) {
-    const token: { replacedByTokenId: string | null } | null =
-      await tx.refreshToken.findUnique({
-        where: { id: cursor },
-        select: {
-          replacedByTokenId: true,
-        },
-      });
+    const token: { replacedByTokenId: string | null } | null = await tx.refreshToken.findUnique({
+      where: { id: cursor },
+      select: {
+        replacedByTokenId: true,
+      },
+    });
 
     cursor = token?.replacedByTokenId ?? null;
     if (cursor) {
@@ -488,14 +528,11 @@ function normalizeEmail(email: string) {
 }
 
 function invalidCredentials() {
-  return new UnauthorizedException("Invalid credentials.");
+  return new UnauthorizedException('Invalid credentials.');
 }
 
 function isPrismaUniqueError(error: unknown) {
-  return (
-    error instanceof Prisma.PrismaClientKnownRequestError &&
-    error.code === "P2002"
-  );
+  return error instanceof Prisma.PrismaClientKnownRequestError && error.code === 'P2002';
 }
 
 function toSafeUser(user: User): AuthenticatedUser {

package/template/src/modules/auth/application/services/password.service.ts

@@ -1,5 +1,5 @@
-import { Injectable } from "@nestjs/common";
-import * as bcrypt from "bcryptjs";
+import { Injectable } from '@nestjs/common';
+import * as bcrypt from 'bcryptjs';
 
 const PASSWORD_HASH_ROUNDS = 12;
 

package/template/src/modules/auth/application/services/token.service.ts

@@ -1,10 +1,10 @@
-import { randomBytes, createHash } from "node:crypto";
-import { InternalServerErrorException, Injectable } from "@nestjs/common";
-import { ConfigService } from "@nestjs/config";
-import { JwtService } from "@nestjs/jwt";
-import { Prisma } from "@prisma/client";
-import { PrismaService } from "../../../../database/prisma/prisma.service";
-import { JwtPayload } from "../../types/jwt-payload";
+import { randomBytes, createHash } from 'node:crypto';
+import { InternalServerErrorException, Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { JwtService } from '@nestjs/jwt';
+import { Prisma } from '@prisma/client';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+import { JwtPayload } from '../../types/jwt-payload';
 
 type TokenUser = {
   id: string;
@@ -31,17 +31,14 @@ export class TokenService {
 
     return this.jwt.signAsync(payload, {
       expiresIn: this.getAccessTokenTtl() as never,
-      algorithm: "HS256",
-      issuer: this.config.get<string>("auth.jwt.issuer"),
-      audience: this.config.get<string>("auth.jwt.audience"),
+      algorithm: 'HS256',
+      issuer: this.config.get<string>('auth.jwt.issuer'),
+      audience: this.config.get<string>('auth.jwt.audience'),
     });
   }
 
-  async createRefreshToken(
-    userId: string,
-    client: RefreshTokenStore = this.prisma,
-  ) {
-    const refreshToken = randomBytes(48).toString("base64url");
+  async createRefreshToken(userId: string, client: RefreshTokenStore = this.prisma) {
+    const refreshToken = randomBytes(48).toString('base64url');
     const tokenHash = this.hashRefreshToken(refreshToken);
     const expiresAt = this.getRefreshTokenExpiry();
 
@@ -60,15 +57,19 @@ export class TokenService {
   }
 
   hashRefreshToken(refreshToken: string) {
-    return createHash("sha256").update(refreshToken).digest("hex");
+    return createHash('sha256').update(refreshToken).digest('hex');
   }
 
   getAccessTokenTtl() {
-    return this.config.get<string>("auth.jwt.accessExpiresIn") ?? "15m";
+    return this.config.get<string>('auth.jwt.accessExpiresIn') ?? '15m';
+  }
+
+  getAccessTokenTtlSeconds() {
+    return Math.floor(parseDurationToMs(this.getAccessTokenTtl()) / 1000);
   }
 
   private getRefreshTokenExpiry() {
-    const ttl = this.config.get<string>("auth.jwt.refreshExpiresIn") ?? "7d";
+    const ttl = this.config.get<string>('auth.jwt.refreshExpiresIn') ?? '7d';
     return new Date(Date.now() + parseDurationToMs(ttl));
   }
 }
@@ -76,9 +77,7 @@ export class TokenService {
 function parseDurationToMs(value: string) {
   const match = /^(\d+)([smhdw])$/.exec(value.trim());
   if (!match) {
-    throw new InternalServerErrorException(
-      `Unsupported duration value: ${value}`,
-    );
+    throw new InternalServerErrorException(`Unsupported duration value: ${value}`);
   }
 
   const amount = Number(match[1]);