@ftisindia/create-app 0.1.0

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

@@ -0,0 +1,75 @@
+import { ApiPropertyOptional } from "@nestjs/swagger";
+import { Type } from "class-transformer";
+import {
+  IsDateString,
+  IsInt,
+  IsOptional,
+  IsString,
+  IsUUID,
+  Max,
+  MaxLength,
+  Min,
+} from "class-validator";
+
+export class ListAuditLogsQueryDto {
+  @ApiPropertyOptional({ example: "membership.status.update", maxLength: 120 })
+  @IsOptional()
+  @IsString()
+  @MaxLength(120)
+  action?: string;
+
+  @ApiPropertyOptional({
+    example: "4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456",
+    format: "uuid",
+  })
+  @IsOptional()
+  @IsUUID()
+  actorUserId?: string;
+
+  @ApiPropertyOptional({ example: "Membership", maxLength: 80 })
+  @IsOptional()
+  @IsString()
+  @MaxLength(80)
+  targetType?: string;
+
+  @ApiPropertyOptional({
+    example: "0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3",
+    maxLength: 120,
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(120)
+  targetId?: string;
+
+  @ApiPropertyOptional({
+    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",
+  })
+  @IsOptional()
+  @IsDateString()
+  to?: string;
+
+  @ApiPropertyOptional({ example: 50, minimum: 1, maximum: 100 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number;
+
+  @ApiPropertyOptional({
+    example: "df6537c4-f58b-452e-a67e-18ec528d0f0f",
+    format: "uuid",
+  })
+  @IsOptional()
+  @IsUUID()
+  cursor?: string;
+}

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

@@ -0,0 +1,37 @@
+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")
+@ApiBearerAuth()
+@ApiParam({ name: "orgId", description: "Organisation ID.", format: "uuid" })
+@ApiProtectedErrorResponses()
+@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." })
+  @ApiOkResponse({
+    description: "Audit log page.",
+    type: AuditLogListResponseDto,
+  })
+  list(@Param("orgId") orgId: string, @Query() query: ListAuditLogsQueryDto) {
+    return this.auditService.listOrgLogs(orgId, query);
+  }
+}

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

@@ -0,0 +1,509 @@
+import {
+  ConflictException,
+  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";
+const OAUTH_EXCHANGE_CODE_TTL_MS = 5 * 60 * 1000;
+const SIGNUP_CONFLICT_MESSAGE =
+  "Unable to complete signup with the provided details.";
+
+@Injectable()
+export class AuthService {
+  constructor(
+    private readonly config: ConfigService,
+    private readonly passwordService: PasswordService,
+    private readonly prisma: PrismaService,
+    private readonly tokenService: TokenService,
+  ) {}
+
+  async signup(dto: SignupDto) {
+    this.assertEmailPasswordEnabled();
+
+    const email = normalizeEmail(dto.email);
+    const existing = await this.prisma.user.findUnique({
+      where: { email },
+      select: { id: true },
+    });
+
+    if (existing) {
+      throw new ConflictException(SIGNUP_CONFLICT_MESSAGE);
+    }
+
+    const passwordHash = await this.passwordService.hash(dto.password);
+    let user: User;
+    try {
+      user = await this.prisma.$transaction(async (tx) => {
+        const createdUser = await tx.user.create({
+          data: {
+            email,
+            passwordHash,
+            displayName: dto.displayName?.trim() || null,
+          },
+        });
+
+        await tx.authIdentity.create({
+          data: {
+            userId: createdUser.id,
+            provider: AuthProvider.EMAIL_PASSWORD,
+            providerUserId: email,
+            email,
+          },
+        });
+
+        await this.writeAudit(tx, {
+          action: "auth.signup",
+          actorUserId: createdUser.id,
+          targetType: "User",
+          targetId: createdUser.id,
+          metadata: { provider: "email_password", email },
+        });
+
+        return createdUser;
+      });
+    } catch (error) {
+      if (isPrismaUniqueError(error)) {
+        throw new ConflictException(SIGNUP_CONFLICT_MESSAGE);
+      }
+
+      throw error;
+    }
+
+    return this.buildAuthResponse(user);
+  }
+
+  async login(dto: LoginDto) {
+    this.assertEmailPasswordEnabled();
+
+    const email = normalizeEmail(dto.email);
+    const user = await this.prisma.user.findUnique({
+      where: { email },
+    });
+
+    if (!user?.passwordHash || !user.isActive) {
+      await this.passwordService.verify(dto.password, DUMMY_PASSWORD_HASH);
+      await this.recordFailedLogin(email);
+      throw invalidCredentials();
+    }
+
+    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",
+      actorUserId: user.id,
+      targetType: "User",
+      targetId: user.id,
+      metadata: { provider: "email_password", email },
+    });
+
+    return this.buildAuthResponse(user);
+  }
+
+  async refresh(dto: RefreshTokenDto) {
+    const tokenHash = this.tokenService.hashRefreshToken(dto.refreshToken);
+    const existing = await this.prisma.refreshToken.findUnique({
+      where: { tokenHash },
+      include: { user: true },
+    });
+
+    if (!existing) {
+      throw invalidCredentials();
+    }
+
+    if (existing.revokedAt) {
+      if (existing.replacedByTokenId) {
+        await this.handleRefreshTokenReuse(existing.id, existing.userId);
+      }
+
+      throw invalidCredentials();
+    }
+
+    if (existing.expiresAt <= new Date() || !existing.user.isActive) {
+      throw invalidCredentials();
+    }
+
+    const result = await this.prisma.$transaction(async (tx) => {
+      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,
+        },
+      });
+
+      await this.writeAudit(tx, {
+        action: "auth.refresh",
+        actorUserId: existing.userId,
+        targetType: "RefreshToken",
+        targetId: existing.id,
+        metadata: { replacedByTokenId: next.record.id },
+      });
+
+      return next.refreshToken;
+    });
+
+    return {
+      accessToken: await this.tokenService.signAccessToken(existing.user),
+      refreshToken: result,
+      tokenType: "Bearer",
+      expiresIn: this.tokenService.getAccessTokenTtl(),
+      user: toSafeUser(existing.user),
+    };
+  }
+
+  async logout(dto: LogoutDto) {
+    const tokenHash = this.tokenService.hashRefreshToken(dto.refreshToken);
+    const token = await this.prisma.refreshToken.findUnique({
+      where: { tokenHash },
+      select: { id: true, userId: true, revokedAt: true },
+    });
+
+    if (!token || token.revokedAt) {
+      return { revoked: true };
+    }
+
+    await this.prisma.$transaction(async (tx) => {
+      await tx.refreshToken.update({
+        where: { id: token.id },
+        data: { revokedAt: new Date() },
+      });
+
+      await this.writeAudit(tx, {
+        action: "auth.logout",
+        actorUserId: token.userId,
+        targetType: "RefreshToken",
+        targetId: token.id,
+      });
+    });
+
+    return { revoked: true };
+  }
+
+  async exchangeOAuthCode(dto: OAuthExchangeDto) {
+    const tokenHash = hashOneTimeCode(dto.code);
+    const existing = await this.prisma.authExchangeCode.findUnique({
+      where: { tokenHash },
+      include: { user: true },
+    });
+
+    if (
+      !existing ||
+      existing.usedAt ||
+      existing.expiresAt <= new Date() ||
+      !existing.user.isActive
+    ) {
+      throw invalidCredentials();
+    }
+
+    await this.prisma.$transaction(async (tx) => {
+      await tx.authExchangeCode.update({
+        where: { id: existing.id },
+        data: { usedAt: new Date() },
+      });
+
+      await this.writeAudit(tx, {
+        action: "auth.oauth.exchange",
+        actorUserId: existing.userId,
+        targetType: "AuthExchangeCode",
+        targetId: existing.id,
+        metadata: { provider: "google" },
+      });
+    });
+
+    return this.buildAuthResponse(existing.user);
+  }
+
+  async googleLogin(profile: GoogleAuthProfile) {
+    this.assertGoogleEnabled();
+
+    if (!profile.emailVerified) {
+      throw new UnauthorizedException("Google email address is not verified.");
+    }
+
+    const email = normalizeEmail(profile.email);
+    const user = await this.prisma.$transaction(async (tx) => {
+      const existingIdentity = await tx.authIdentity.findUnique({
+        where: {
+          provider_providerUserId: {
+            provider: AuthProvider.GOOGLE,
+            providerUserId: profile.providerUserId,
+          },
+        },
+        include: { user: true },
+      });
+
+      if (existingIdentity) {
+        if (!existingIdentity.user.isActive) {
+          throw invalidCredentials();
+        }
+
+        await this.writeAudit(tx, {
+          action: "auth.google.login",
+          actorUserId: existingIdentity.userId,
+          targetType: "User",
+          targetId: existingIdentity.userId,
+          metadata: { provider: "google", email },
+        });
+
+        return existingIdentity.user;
+      }
+
+      const existingUser = await tx.user.findUnique({
+        where: { email },
+      });
+
+      if (existingUser) {
+        if (!existingUser.isActive) {
+          throw invalidCredentials();
+        }
+
+        await tx.authIdentity.create({
+          data: {
+            userId: existingUser.id,
+            provider: AuthProvider.GOOGLE,
+            providerUserId: profile.providerUserId,
+            email,
+          },
+        });
+
+        await this.writeAudit(tx, {
+          action: "auth.google.link",
+          actorUserId: existingUser.id,
+          targetType: "User",
+          targetId: existingUser.id,
+          metadata: { provider: "google", email },
+        });
+
+        return existingUser;
+      }
+
+      const createdUser = await tx.user.create({
+        data: {
+          email,
+          displayName: profile.displayName,
+        },
+      });
+
+      await tx.authIdentity.create({
+        data: {
+          userId: createdUser.id,
+          provider: AuthProvider.GOOGLE,
+          providerUserId: profile.providerUserId,
+          email,
+        },
+      });
+
+      await this.writeAudit(tx, {
+        action: "auth.google.signup",
+        actorUserId: createdUser.id,
+        targetType: "User",
+        targetId: createdUser.id,
+        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);
+
+    return redirectUrl.toString();
+  }
+
+  me(user: AuthenticatedUser) {
+    return user;
+  }
+
+  private async buildAuthResponse(user: User) {
+    const refresh = await this.tokenService.createRefreshToken(user.id);
+
+    return {
+      accessToken: await this.tokenService.signAccessToken(user),
+      refreshToken: refresh.refreshToken,
+      tokenType: "Bearer",
+      expiresIn: this.tokenService.getAccessTokenTtl(),
+      user: toSafeUser(user),
+    };
+  }
+
+  private async createOAuthExchangeCode(userId: string) {
+    const code = randomBytes(48).toString("base64url");
+    await this.prisma.authExchangeCode.create({
+      data: {
+        userId,
+        tokenHash: hashOneTimeCode(code),
+        expiresAt: new Date(Date.now() + OAUTH_EXCHANGE_CODE_TTL_MS),
+      },
+    });
+
+    return code;
+  }
+
+  private async handleRefreshTokenReuse(
+    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,
+        },
+      });
+    });
+  }
+
+  private assertEmailPasswordEnabled() {
+    const enabled = this.config.get<boolean>(
+      "auth.providers.emailPasswordEnabled",
+    );
+    if (!enabled) {
+      throw new ForbiddenException(
+        "Email/password authentication is disabled.",
+      );
+    }
+  }
+
+  private assertGoogleEnabled() {
+    const enabled = this.config.get<boolean>("auth.providers.googleEnabled");
+    if (!enabled) {
+      throw new ForbiddenException("Google authentication is disabled.");
+    }
+  }
+
+  private async recordFailedLogin(email: string, actorUserId?: string) {
+    await this.writeAudit(this.prisma, {
+      action: "auth.login.failed",
+      actorUserId,
+      targetType: "Auth",
+      metadata: { provider: "email_password", email },
+    });
+  }
+
+  private async writeAudit(
+    client: Prisma.TransactionClient | PrismaService,
+    data: {
+      action: string;
+      actorUserId?: string;
+      targetType: string;
+      targetId?: string;
+      metadata?: Prisma.InputJsonObject;
+    },
+  ) {
+    await client.auditLog.create({
+      data: {
+        orgId: null,
+        actorUserId: data.actorUserId,
+        action: data.action,
+        targetType: data.targetType,
+        targetId: data.targetId,
+        metadata: data.metadata,
+      },
+    });
+  }
+}
+
+function hashOneTimeCode(code: string) {
+  return createHash("sha256").update(code).digest("hex");
+}
+
+async function revokeRefreshTokenDescendants(
+  tx: Prisma.TransactionClient,
+  refreshTokenId: string,
+  revokedAt: Date,
+): Promise<string[]> {
+  const revokedIds = new Set<string>([refreshTokenId]);
+  let cursor: string | null = refreshTokenId;
+
+  while (cursor) {
+    const token: { replacedByTokenId: string | null } | null =
+      await tx.refreshToken.findUnique({
+        where: { id: cursor },
+        select: {
+          replacedByTokenId: true,
+        },
+      });
+
+    cursor = token?.replacedByTokenId ?? null;
+    if (cursor) {
+      revokedIds.add(cursor);
+    }
+  }
+
+  await tx.refreshToken.updateMany({
+    where: {
+      id: {
+        in: [...revokedIds],
+      },
+    },
+    data: { revokedAt },
+  });
+
+  return [...revokedIds];
+}
+
+function normalizeEmail(email: string) {
+  return email.trim().toLowerCase();
+}
+
+function invalidCredentials() {
+  return new UnauthorizedException("Invalid credentials.");
+}
+
+function isPrismaUniqueError(error: unknown) {
+  return (
+    error instanceof Prisma.PrismaClientKnownRequestError &&
+    error.code === "P2002"
+  );
+}
+
+function toSafeUser(user: User): AuthenticatedUser {
+  return {
+    id: user.id,
+    email: user.email,
+    mobile: user.mobile,
+    displayName: user.displayName,
+    isActive: user.isActive,
+  };
+}

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

@@ -0,0 +1,15 @@
+import { Injectable } from "@nestjs/common";
+import * as bcrypt from "bcryptjs";
+
+const PASSWORD_HASH_ROUNDS = 12;
+
+@Injectable()
+export class PasswordService {
+  hash(password: string) {
+    return bcrypt.hash(password, PASSWORD_HASH_ROUNDS);
+  }
+
+  verify(password: string, hash: string) {
+    return bcrypt.compare(password, hash);
+  }
+}