@ftisindia/create-app 0.1.0

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

@@ -0,0 +1,95 @@
+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;
+  email: string | null;
+  mobile: string | null;
+};
+
+type RefreshTokenStore = Prisma.TransactionClient | PrismaService;
+
+@Injectable()
+export class TokenService {
+  constructor(
+    private readonly config: ConfigService,
+    private readonly jwt: JwtService,
+    private readonly prisma: PrismaService,
+  ) {}
+
+  async signAccessToken(user: TokenUser) {
+    const payload: JwtPayload = {
+      sub: user.id,
+      email: user.email,
+      mobile: user.mobile,
+    };
+
+    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"),
+    });
+  }
+
+  async createRefreshToken(
+    userId: string,
+    client: RefreshTokenStore = this.prisma,
+  ) {
+    const refreshToken = randomBytes(48).toString("base64url");
+    const tokenHash = this.hashRefreshToken(refreshToken);
+    const expiresAt = this.getRefreshTokenExpiry();
+
+    const record = await client.refreshToken.create({
+      data: {
+        userId,
+        tokenHash,
+        expiresAt,
+      },
+    });
+
+    return {
+      refreshToken,
+      record,
+    };
+  }
+
+  hashRefreshToken(refreshToken: string) {
+    return createHash("sha256").update(refreshToken).digest("hex");
+  }
+
+  getAccessTokenTtl() {
+    return this.config.get<string>("auth.jwt.accessExpiresIn") ?? "15m";
+  }
+
+  private getRefreshTokenExpiry() {
+    const ttl = this.config.get<string>("auth.jwt.refreshExpiresIn") ?? "7d";
+    return new Date(Date.now() + parseDurationToMs(ttl));
+  }
+}
+
+function parseDurationToMs(value: string) {
+  const match = /^(\d+)([smhdw])$/.exec(value.trim());
+  if (!match) {
+    throw new InternalServerErrorException(
+      `Unsupported duration value: ${value}`,
+    );
+  }
+
+  const amount = Number(match[1]);
+  const unit = match[2];
+  const multipliers: Record<string, number> = {
+    s: 1000,
+    m: 60 * 1000,
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+    w: 7 * 24 * 60 * 60 * 1000,
+  };
+
+  return amount * multipliers[unit];
+}

package/template/src/modules/auth/auth.module.ts

@@ -0,0 +1,73 @@
+import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
+import { ConfigModule, ConfigService } from "@nestjs/config";
+import { JwtModule } from "@nestjs/jwt";
+import { PassportModule } from "@nestjs/passport";
+import session = require("express-session");
+import { AuthService } from "./application/services/auth.service";
+import { PasswordService } from "./application/services/password.service";
+import { TokenService } from "./application/services/token.service";
+import { GoogleAuthGuard } from "./infrastructure/passport/google-auth.guard";
+import { GoogleStrategy } from "./infrastructure/passport/google.strategy";
+import { JwtAuthGuard } from "./infrastructure/passport/jwt-auth.guard";
+import { JwtStrategy } from "./infrastructure/passport/jwt.strategy";
+import { AuthController } from "./presentation/auth.controller";
+import { GoogleOAuthExceptionFilter } from "./presentation/google-oauth-exception.filter";
+
+@Module({
+  imports: [
+    PassportModule,
+    JwtModule.registerAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        secret: config.get<string>("auth.jwt.secret") ?? "",
+        signOptions: {
+          algorithm: "HS256",
+          issuer: config.get<string>("auth.jwt.issuer"),
+          audience: config.get<string>("auth.jwt.audience"),
+        },
+      }),
+    }),
+  ],
+  controllers: [AuthController],
+  providers: [
+    AuthService,
+    GoogleAuthGuard,
+    GoogleOAuthExceptionFilter,
+    GoogleStrategy,
+    JwtAuthGuard,
+    JwtStrategy,
+    PasswordService,
+    TokenService,
+  ],
+  exports: [JwtAuthGuard, PasswordService],
+})
+export class AuthModule implements NestModule {
+  constructor(private readonly config: ConfigService) {}
+
+  configure(consumer: MiddlewareConsumer) {
+    consumer
+      .apply(buildGoogleOAuthSessionMiddleware(this.config))
+      .forRoutes("auth/google", "auth/google/callback");
+  }
+}
+
+function buildGoogleOAuthSessionMiddleware(config: ConfigService) {
+  const secret =
+    config.get<string>("auth.session.secret") ||
+    "google-oauth-disabled-session-secret";
+
+  return session({
+    secret,
+    name: "oauth.sid",
+    resave: false,
+    saveUninitialized: false,
+    cookie: {
+      httpOnly: true,
+      sameSite: "lax",
+      secure: config.get<string>("app.nodeEnv") === "production",
+      maxAge: 10 * 60 * 1000,
+      path: "/auth/google",
+    },
+  });
+}

package/template/src/modules/auth/dto/auth-response.dto.ts

@@ -0,0 +1,29 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { ActiveUserSummaryDto } from "../../../common/dto/user-summary.dto";
+
+export class AuthTokensResponseDto {
+  @ApiProperty({
+    description: "JWT access token for bearer authentication.",
+    example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  })
+  accessToken!: string;
+
+  @ApiProperty({
+    description:
+      "Opaque refresh token. Store it securely and send it only to auth endpoints.",
+    example: "rfr_9b2f4f8d2d9f4d65a1f4",
+  })
+  refreshToken!: string;
+
+  @ApiProperty({ example: "Bearer" })
+  tokenType!: "Bearer";
+
+  @ApiProperty({
+    description: "Access token lifetime in seconds.",
+    example: 900,
+  })
+  expiresIn!: number;
+
+  @ApiProperty({ type: ActiveUserSummaryDto })
+  user!: ActiveUserSummaryDto;
+}

package/template/src/modules/auth/dto/login.dto.ts

@@ -0,0 +1,15 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsEmail, IsString, MaxLength, MinLength } from "class-validator";
+
+export class LoginDto {
+  @ApiProperty({ example: "owner@example.com" })
+  @IsEmail()
+  @MaxLength(320)
+  email!: string;
+
+  @ApiProperty({ example: "dev-password-123" })
+  @IsString()
+  @MinLength(8)
+  @MaxLength(128)
+  password!: string;
+}

package/template/src/modules/auth/dto/logout.dto.ts

@@ -0,0 +1,3 @@
+import { RefreshTokenDto } from "./refresh-token.dto";
+
+export class LogoutDto extends RefreshTokenDto {}

package/template/src/modules/auth/dto/oauth-exchange.dto.ts

@@ -0,0 +1,15 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsString, Length } from "class-validator";
+
+export class OAuthExchangeDto {
+  @ApiProperty({
+    description:
+      "One-time code returned to the frontend by the Google OAuth callback redirect.",
+    example: "DXB2rcx5HcKXy35bA3AzYdVq2e4nGsgYeG3D9M7uAQM",
+    minLength: 32,
+    maxLength: 256,
+  })
+  @IsString()
+  @Length(32, 256)
+  code!: string;
+}

package/template/src/modules/auth/dto/refresh-token.dto.ts

@@ -0,0 +1,14 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsString, MinLength } from "class-validator";
+
+export class RefreshTokenDto {
+  @ApiProperty({
+    description:
+      "Opaque refresh token returned by signup, login, refresh, or OAuth exchange.",
+    example: "rfr_9b2f4f8d2d9f4d65a1f4",
+    minLength: 32,
+  })
+  @IsString()
+  @MinLength(32)
+  refreshToken!: string;
+}

package/template/src/modules/auth/dto/signup.dto.ts

@@ -0,0 +1,27 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import {
+  IsEmail,
+  IsOptional,
+  IsString,
+  MaxLength,
+  MinLength,
+} from "class-validator";
+
+export class SignupDto {
+  @ApiProperty({ example: "owner@example.com" })
+  @IsEmail()
+  @MaxLength(320)
+  email!: string;
+
+  @ApiProperty({ minLength: 8, maxLength: 128, example: "dev-password-123" })
+  @IsString()
+  @MinLength(8)
+  @MaxLength(128)
+  password!: string;
+
+  @ApiPropertyOptional({ example: "Starter Owner" })
+  @IsOptional()
+  @IsString()
+  @MaxLength(120)
+  displayName?: string;
+}

package/template/src/modules/auth/infrastructure/passport/google-auth.guard.ts

@@ -0,0 +1,27 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+} from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { AuthGuard } from "@nestjs/passport";
+
+@Injectable()
+export class GoogleAuthGuard
+  extends AuthGuard("google")
+  implements CanActivate
+{
+  constructor(private readonly config: ConfigService) {
+    super();
+  }
+
+  canActivate(context: ExecutionContext) {
+    const enabled = this.config.get<boolean>("auth.providers.googleEnabled");
+    if (!enabled) {
+      throw new ForbiddenException("Google authentication is disabled.");
+    }
+
+    return super.canActivate(context);
+  }
+}

package/template/src/modules/auth/infrastructure/passport/google.strategy.ts

@@ -0,0 +1,56 @@
+import { Injectable, UnauthorizedException } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { PassportStrategy } from "@nestjs/passport";
+import { Profile, Strategy, VerifyCallback } from "passport-google-oauth20";
+import { GoogleAuthProfile } from "../../types/google-auth-profile";
+
+@Injectable()
+export class GoogleStrategy extends PassportStrategy(Strategy, "google") {
+  constructor(config: ConfigService) {
+    const enabled = config.get<boolean>("auth.providers.googleEnabled");
+
+    super({
+      clientID: enabled
+        ? (config.get<string>("auth.google.clientId") ?? "")
+        : "google-disabled",
+      clientSecret: enabled
+        ? (config.get<string>("auth.google.clientSecret") ?? "")
+        : "google-disabled",
+      callbackURL:
+        config.get<string>("auth.google.callbackUrl") ??
+        "http://localhost:3000/auth/google/callback",
+      state: true,
+      pkce: true,
+      scope: ["email", "profile"],
+    });
+  }
+
+  validate(
+    _accessToken: string,
+    _refreshToken: string,
+    profile: Profile,
+    done: VerifyCallback,
+  ) {
+    const email = profile.emails?.[0]?.value?.trim().toLowerCase();
+    if (!email) {
+      done(
+        new UnauthorizedException(
+          "Google account did not provide an email address.",
+        ),
+      );
+      return;
+    }
+
+    const profileJson = profile._json as
+      | { email_verified?: boolean }
+      | undefined;
+    const result: GoogleAuthProfile = {
+      providerUserId: profile.id,
+      email,
+      emailVerified: profileJson?.email_verified === true,
+      displayName: profile.displayName || null,
+    };
+
+    done(null, result);
+  }
+}

package/template/src/modules/auth/infrastructure/passport/jwt-auth.guard.ts

@@ -0,0 +1,5 @@
+import { Injectable } from "@nestjs/common";
+import { AuthGuard } from "@nestjs/passport";
+
+@Injectable()
+export class JwtAuthGuard extends AuthGuard("jwt") {}

package/template/src/modules/auth/infrastructure/passport/jwt.strategy.ts

@@ -0,0 +1,43 @@
+import { Injectable, UnauthorizedException } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { PassportStrategy } from "@nestjs/passport";
+import { ExtractJwt, Strategy } from "passport-jwt";
+import { PrismaService } from "../../../../database/prisma/prisma.service";
+import { AuthenticatedUser } from "../../types/authenticated-user";
+import { JwtPayload } from "../../types/jwt-payload";
+
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy) {
+  constructor(
+    private readonly prisma: PrismaService,
+    config: ConfigService,
+  ) {
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      ignoreExpiration: false,
+      algorithms: ["HS256"],
+      issuer: config.get<string>("auth.jwt.issuer"),
+      audience: config.get<string>("auth.jwt.audience"),
+      secretOrKey: config.get<string>("auth.jwt.secret") ?? "",
+    });
+  }
+
+  async validate(payload: JwtPayload): Promise<AuthenticatedUser> {
+    const user = await this.prisma.user.findUnique({
+      where: { id: payload.sub },
+      select: {
+        id: true,
+        email: true,
+        mobile: true,
+        displayName: true,
+        isActive: true,
+      },
+    });
+
+    if (!user?.isActive) {
+      throw new UnauthorizedException();
+    }
+
+    return user;
+  }
+}

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

@@ -0,0 +1,148 @@
+import {
+  Body,
+  Controller,
+  Get,
+  HttpCode,
+  Post,
+  Req,
+  Res,
+  UseFilters,
+  UseGuards,
+} from "@nestjs/common";
+import {
+  ApiBearerAuth,
+  ApiCreatedResponse,
+  ApiFoundResponse,
+  ApiOkResponse,
+  ApiOperation,
+  ApiTags,
+} from "@nestjs/swagger";
+import { Throttle } from "@nestjs/throttler";
+import { RevokedResponseDto } from "../../../common/dto/mutation-response.dto";
+import { ActiveUserSummaryDto } from "../../../common/dto/user-summary.dto";
+import { ApiErrorResponses } from "../../../common/swagger/api-error-responses";
+import { AuthService } from "../application/services/auth.service";
+import { AuthTokensResponseDto } from "../dto/auth-response.dto";
+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 { GoogleAuthGuard } from "../infrastructure/passport/google-auth.guard";
+import { JwtAuthGuard } from "../infrastructure/passport/jwt-auth.guard";
+import { AuthenticatedUser } from "../types/authenticated-user";
+import { GoogleAuthProfile } from "../types/google-auth-profile";
+import { CurrentUser } from "./current-user.decorator";
+import { GoogleOAuthExceptionFilter } from "./google-oauth-exception.filter";
+
+@ApiTags("Auth")
+@Controller("auth")
+export class AuthController {
+  constructor(private readonly authService: AuthService) {}
+
+  @Post("signup")
+  @Throttle({ default: { limit: 5, ttl: 60_000 } })
+  @ApiOperation({ summary: "Create an email/password user and issue tokens." })
+  @ApiCreatedResponse({
+    description: "User created and tokens issued.",
+    type: AuthTokensResponseDto,
+  })
+  @ApiErrorResponses(400, 409, 429)
+  signup(@Body() dto: SignupDto) {
+    return this.authService.signup(dto);
+  }
+
+  @Post("login")
+  @HttpCode(200)
+  @Throttle({ default: { limit: 5, ttl: 60_000 } })
+  @ApiOperation({ summary: "Login with email/password." })
+  @ApiOkResponse({
+    description: "Login succeeded and tokens were issued.",
+    type: AuthTokensResponseDto,
+  })
+  @ApiErrorResponses(400, 401, 429)
+  login(@Body() dto: LoginDto) {
+    return this.authService.login(dto);
+  }
+
+  @Post("refresh")
+  @HttpCode(200)
+  @Throttle({ default: { limit: 10, ttl: 60_000 } })
+  @ApiOperation({
+    summary: "Rotate a refresh token and issue a new access token.",
+  })
+  @ApiOkResponse({
+    description: "Refresh token rotated.",
+    type: AuthTokensResponseDto,
+  })
+  @ApiErrorResponses(400, 401, 429)
+  refresh(@Body() dto: RefreshTokenDto) {
+    return this.authService.refresh(dto);
+  }
+
+  @Post("oauth/exchange")
+  @HttpCode(200)
+  @Throttle({ default: { limit: 10, ttl: 60_000 } })
+  @ApiOperation({
+    summary: "Exchange a Google OAuth one-time code for tokens.",
+  })
+  @ApiOkResponse({
+    description: "OAuth exchange succeeded.",
+    type: AuthTokensResponseDto,
+  })
+  @ApiErrorResponses(400, 401, 429)
+  exchangeOAuthCode(@Body() dto: OAuthExchangeDto) {
+    return this.authService.exchangeOAuthCode(dto);
+  }
+
+  @Post("logout")
+  @HttpCode(200)
+  @ApiOperation({ summary: "Revoke a refresh token." })
+  @ApiOkResponse({
+    description: "Refresh token is revoked or already unusable.",
+    type: RevokedResponseDto,
+  })
+  @ApiErrorResponses(400)
+  logout(@Body() dto: LogoutDto) {
+    return this.authService.logout(dto);
+  }
+
+  @Get("google")
+  @UseFilters(GoogleOAuthExceptionFilter)
+  @UseGuards(GoogleAuthGuard)
+  @ApiOperation({ summary: "Start the Google OAuth login flow." })
+  @ApiFoundResponse({ description: "Redirects the browser to Google OAuth." })
+  @ApiErrorResponses(403)
+  google() {
+    return undefined;
+  }
+
+  @Get("google/callback")
+  @UseFilters(GoogleOAuthExceptionFilter)
+  @UseGuards(GoogleAuthGuard)
+  @ApiOperation({ summary: "Handle the Google OAuth callback." })
+  @ApiFoundResponse({
+    description: "Redirects to the configured frontend success or error URL.",
+  })
+  @ApiErrorResponses(401, 403)
+  async googleCallback(
+    @Req() request: { user: GoogleAuthProfile },
+    @Res() response: { redirect: (status: number, url: string) => void },
+  ) {
+    const redirectUrl = await this.authService.googleLogin(request.user);
+    response.redirect(302, redirectUrl);
+  }
+
+  @Get("me")
+  @UseGuards(JwtAuthGuard)
+  @ApiBearerAuth()
+  @ApiOperation({ summary: "Return the current JWT identity." })
+  @ApiOkResponse({
+    description: "Current authenticated user.",
+    type: ActiveUserSummaryDto,
+  })
+  @ApiErrorResponses(401)
+  me(@CurrentUser() user: AuthenticatedUser) {
+    return this.authService.me(user);
+  }
+}

package/template/src/modules/auth/presentation/current-user.decorator.ts

@@ -0,0 +1,11 @@
+import { createParamDecorator, ExecutionContext } from "@nestjs/common";
+import { AuthenticatedUser } from "../types/authenticated-user";
+
+export const CurrentUser = createParamDecorator(
+  (_data: unknown, context: ExecutionContext): AuthenticatedUser => {
+    const request = context
+      .switchToHttp()
+      .getRequest<{ user: AuthenticatedUser }>();
+    return request.user;
+  },
+);

package/template/src/modules/auth/presentation/google-oauth-exception.filter.ts

@@ -0,0 +1,33 @@
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  Injectable,
+} from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+
+type RedirectResponse = {
+  headersSent?: boolean;
+  redirect: (status: number, url: string) => void;
+};
+
+@Injectable()
+@Catch()
+export class GoogleOAuthExceptionFilter implements ExceptionFilter {
+  constructor(private readonly config: ConfigService) {}
+
+  catch(_exception: unknown, host: ArgumentsHost) {
+    const response = host.switchToHttp().getResponse<RedirectResponse>();
+    if (response.headersSent) {
+      return;
+    }
+
+    const redirectUrl = new URL(
+      this.config.get<string>("auth.google.errorRedirectUrl") ??
+        "http://localhost:3000/auth/google/error",
+    );
+    redirectUrl.searchParams.set("error", "oauth_failed");
+
+    response.redirect(302, redirectUrl.toString());
+  }
+}

package/template/src/modules/auth/types/authenticated-user.ts

@@ -0,0 +1,7 @@
+export type AuthenticatedUser = {
+  id: string;
+  email: string | null;
+  mobile: string | null;
+  displayName: string | null;
+  isActive: boolean;
+};

package/template/src/modules/auth/types/google-auth-profile.ts

@@ -0,0 +1,6 @@
+export type GoogleAuthProfile = {
+  providerUserId: string;
+  email: string;
+  emailVerified: boolean;
+  displayName: string | null;
+};

package/template/src/modules/auth/types/jwt-payload.ts

@@ -0,0 +1,5 @@
+export type JwtPayload = {
+  sub: string;
+  email?: string | null;
+  mobile?: string | null;
+};

package/template/src/modules/health/dto/health-response.dto.ts

@@ -0,0 +1,9 @@
+import { ApiProperty } from "@nestjs/swagger";
+
+export class HealthResponseDto {
+  @ApiProperty({ example: "ok" })
+  status!: "ok";
+
+  @ApiProperty({ example: "ok" })
+  db!: "ok";
+}

package/template/src/modules/health/health.module.ts

@@ -0,0 +1,7 @@
+import { Module } from "@nestjs/common";
+import { HealthController } from "./presentation/health.controller";
+
+@Module({
+  controllers: [HealthController],
+})
+export class HealthModule {}