@ftisindia/create-app 0.1.0

package/template/src/common/dto/role-summary.dto.ts

@@ -0,0 +1,18 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+
+export class RoleSummaryDto {
+  @ApiProperty({
+    example: "f602c057-04f4-4ef8-8c84-1b7c62fbf8c5",
+    format: "uuid",
+  })
+  id!: string;
+
+  @ApiProperty({ example: "Owner" })
+  name!: string;
+
+  @ApiPropertyOptional({ example: "Full organisation access.", nullable: true })
+  description?: string | null;
+
+  @ApiPropertyOptional({ example: true })
+  isSystemSeeded?: boolean;
+}

package/template/src/common/dto/user-summary.dto.ts

@@ -0,0 +1,23 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+
+export class UserSummaryDto {
+  @ApiProperty({
+    example: "4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456",
+    format: "uuid",
+  })
+  id!: string;
+
+  @ApiPropertyOptional({ example: "owner@example.com", nullable: true })
+  email?: string | null;
+
+  @ApiPropertyOptional({ example: "+14155552671", nullable: true })
+  mobile?: string | null;
+
+  @ApiPropertyOptional({ example: "Starter Owner", nullable: true })
+  displayName?: string | null;
+}
+
+export class ActiveUserSummaryDto extends UserSummaryDto {
+  @ApiProperty({ example: true })
+  isActive!: boolean;
+}

package/template/src/common/enums/.gitkeep

@@ -0,0 +1 @@
+# keep

package/template/src/common/filters/.gitkeep

@@ -0,0 +1 @@
+# keep

package/template/src/common/filters/http-exception.filter.ts

@@ -0,0 +1,78 @@
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+} from "@nestjs/common";
+
+type HttpResponse = {
+  status: (statusCode: number) => {
+    json: (body: unknown) => void;
+  };
+};
+
+@Catch()
+export class HttpExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const response = host.switchToHttp().getResponse<HttpResponse>();
+    const status =
+      exception instanceof HttpException
+        ? exception.getStatus()
+        : HttpStatus.INTERNAL_SERVER_ERROR;
+
+    response.status(status).json({
+      error: {
+        code: errorCode(status),
+        message: errorMessage(exception),
+        details: errorDetails(exception),
+      },
+    });
+  }
+}
+
+function errorCode(status: number) {
+  return HttpStatus[status] ?? "ERROR";
+}
+
+function errorMessage(exception: unknown) {
+  if (!(exception instanceof HttpException)) {
+    return "Internal server error.";
+  }
+
+  const body = exception.getResponse();
+  if (typeof body === "string") {
+    return body;
+  }
+
+  if (isObject(body) && typeof body.message === "string") {
+    return body.message;
+  }
+
+  if (isObject(body) && Array.isArray(body.message)) {
+    return body.message.join("; ");
+  }
+
+  return exception.message;
+}
+
+function errorDetails(exception: unknown) {
+  if (!(exception instanceof HttpException)) {
+    return undefined;
+  }
+
+  const body = exception.getResponse();
+  if (!isObject(body)) {
+    return undefined;
+  }
+
+  return Object.fromEntries(
+    Object.entries(body).filter(
+      ([key]) => !["statusCode", "error", "message"].includes(key),
+    ),
+  );
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/template/src/common/guards/.gitkeep

@@ -0,0 +1 @@
+# keep

package/template/src/common/interceptors/.gitkeep

@@ -0,0 +1 @@
+# keep

package/template/src/common/pipes/.gitkeep

@@ -0,0 +1 @@
+# keep

package/template/src/common/swagger/api-error-responses.ts

@@ -0,0 +1,54 @@
+import { applyDecorators } from "@nestjs/common";
+import {
+  ApiBadRequestResponse,
+  ApiConflictResponse,
+  ApiForbiddenResponse,
+  ApiGoneResponse,
+  ApiInternalServerErrorResponse,
+  ApiNotFoundResponse,
+  ApiServiceUnavailableResponse,
+  ApiTooManyRequestsResponse,
+  ApiUnauthorizedResponse,
+} from "@nestjs/swagger";
+import { ErrorResponseDto } from "../dto/error-response.dto";
+
+type ApiErrorStatus = 400 | 401 | 403 | 404 | 409 | 410 | 429 | 500 | 503;
+
+const errorResponseFactories = {
+  400: ApiBadRequestResponse,
+  401: ApiUnauthorizedResponse,
+  403: ApiForbiddenResponse,
+  404: ApiNotFoundResponse,
+  409: ApiConflictResponse,
+  410: ApiGoneResponse,
+  429: ApiTooManyRequestsResponse,
+  500: ApiInternalServerErrorResponse,
+  503: ApiServiceUnavailableResponse,
+} satisfies Record<ApiErrorStatus, typeof ApiBadRequestResponse>;
+
+const descriptions: Record<ApiErrorStatus, string> = {
+  400: "The request body, route parameter, or query string is invalid.",
+  401: "Authentication failed or the bearer token is missing.",
+  403: "The authenticated user does not have access to this organisation or permission.",
+  404: "The requested resource was not found.",
+  409: "The request conflicts with current resource state.",
+  410: "The resource is no longer available.",
+  429: "Too many requests.",
+  500: "Unexpected server error.",
+  503: "The service is temporarily unavailable.",
+};
+
+export function ApiErrorResponses(...statuses: ApiErrorStatus[]) {
+  return applyDecorators(
+    ...statuses.map((status) =>
+      errorResponseFactories[status]({
+        description: descriptions[status],
+        type: ErrorResponseDto,
+      }),
+    ),
+  );
+}
+
+export function ApiProtectedErrorResponses(...extraStatuses: ApiErrorStatus[]) {
+  return ApiErrorResponses(400, 401, 403, ...extraStatuses);
+}

package/template/src/common/types/.gitkeep

@@ -0,0 +1 @@
+# keep

package/template/src/config/app.config.ts

@@ -0,0 +1,7 @@
+import { registerAs } from "@nestjs/config";
+import { getEnv } from "./env.validation";
+
+export default registerAs("app", () => ({
+  nodeEnv: getEnv().NODE_ENV,
+  port: getEnv().PORT,
+}));

package/template/src/config/auth.config.ts

@@ -0,0 +1,33 @@
+import { registerAs } from "@nestjs/config";
+import { getEnv } from "./env.validation";
+
+export default registerAs("auth", () => {
+  const env = getEnv();
+
+  return {
+    jwt: {
+      secret: env.JWT_SECRET,
+      accessExpiresIn: env.JWT_ACCESS_EXPIRES_IN,
+      refreshExpiresIn: env.JWT_REFRESH_EXPIRES_IN,
+      issuer: env.JWT_ISSUER,
+      audience: env.JWT_AUDIENCE,
+    },
+    providers: {
+      emailPasswordEnabled: env.AUTH_EMAIL_PASSWORD_ENABLED,
+      googleEnabled: env.AUTH_GOOGLE_ENABLED,
+      facebookEnabled: env.AUTH_FACEBOOK_ENABLED,
+      mobileOtpEnabled: env.AUTH_MOBILE_OTP_ENABLED,
+      magicLinkEnabled: env.AUTH_MAGIC_LINK_ENABLED,
+    },
+    google: {
+      clientId: env.AUTH_GOOGLE_CLIENT_ID,
+      clientSecret: env.AUTH_GOOGLE_CLIENT_SECRET,
+      callbackUrl: env.AUTH_GOOGLE_CALLBACK_URL,
+      successRedirectUrl: env.AUTH_GOOGLE_SUCCESS_REDIRECT_URL,
+      errorRedirectUrl: env.AUTH_GOOGLE_ERROR_REDIRECT_URL,
+    },
+    session: {
+      secret: env.SESSION_SECRET,
+    },
+  };
+});

package/template/src/config/database.config.ts

@@ -0,0 +1,6 @@
+import { registerAs } from "@nestjs/config";
+import { getEnv } from "./env.validation";
+
+export default registerAs("database", () => ({
+  url: getEnv().DATABASE_URL,
+}));

package/template/src/config/env.validation.ts

@@ -0,0 +1,131 @@
+import { z } from "zod";
+
+const booleanFromEnv = z.preprocess((value) => {
+  if (typeof value === "boolean") {
+    return value;
+  }
+
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "true") {
+      return true;
+    }
+
+    if (normalized === "false") {
+      return false;
+    }
+  }
+
+  return value;
+}, z.boolean());
+
+const durationSchema = z
+  .string()
+  .trim()
+  .regex(/^\d+[smhdw]$/, "duration must use s, m, h, d, or w units");
+
+export const envSchema = z
+  .object({
+    NODE_ENV: z
+      .enum(["development", "test", "production"])
+      .default("development"),
+    PORT: z.coerce.number().int().positive().default(3000),
+    DATABASE_URL: z
+      .string()
+      .trim()
+      .min(1, "DATABASE_URL is required")
+      .url("DATABASE_URL must be a valid URL"),
+    JWT_SECRET: z
+      .string()
+      .trim()
+      .min(16, "JWT_SECRET must be at least 16 characters"),
+    JWT_ACCESS_EXPIRES_IN: durationSchema.default("15m"),
+    JWT_REFRESH_EXPIRES_IN: durationSchema.default("7d"),
+    JWT_ISSUER: z.string().trim().min(1).default("foundation-starter"),
+    JWT_AUDIENCE: z.string().trim().min(1).default("foundation-api"),
+    AUTH_EMAIL_PASSWORD_ENABLED: booleanFromEnv.default(true),
+    AUTH_GOOGLE_ENABLED: booleanFromEnv.default(false),
+    AUTH_GOOGLE_CLIENT_ID: z.string().trim().optional().default(""),
+    AUTH_GOOGLE_CLIENT_SECRET: z.string().trim().optional().default(""),
+    AUTH_GOOGLE_CALLBACK_URL: z
+      .string()
+      .trim()
+      .url()
+      .default("http://localhost:3000/auth/google/callback"),
+    AUTH_GOOGLE_SUCCESS_REDIRECT_URL: z
+      .string()
+      .trim()
+      .url()
+      .default("http://localhost:3000/auth/google/success"),
+    AUTH_GOOGLE_ERROR_REDIRECT_URL: z
+      .string()
+      .trim()
+      .url()
+      .default("http://localhost:3000/auth/google/error"),
+    SESSION_SECRET: z.string().trim().optional().default(""),
+    AUTH_FACEBOOK_ENABLED: booleanFromEnv.default(false),
+    AUTH_MOBILE_OTP_ENABLED: booleanFromEnv.default(false),
+    AUTH_MAGIC_LINK_ENABLED: booleanFromEnv.default(false),
+    RBAC_CACHE_TTL_SECONDS: z.coerce.number().int().positive().default(60),
+    ORG_CONTEXT_MODE: z.literal("path").default("path"),
+  })
+  .superRefine((env, ctx) => {
+    if (!env.AUTH_GOOGLE_ENABLED) {
+      return;
+    }
+
+    if (!env.AUTH_GOOGLE_CLIENT_ID) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["AUTH_GOOGLE_CLIENT_ID"],
+        message:
+          "AUTH_GOOGLE_CLIENT_ID is required when AUTH_GOOGLE_ENABLED=true",
+      });
+    }
+
+    if (!env.AUTH_GOOGLE_CLIENT_SECRET) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["AUTH_GOOGLE_CLIENT_SECRET"],
+        message:
+          "AUTH_GOOGLE_CLIENT_SECRET is required when AUTH_GOOGLE_ENABLED=true",
+      });
+    }
+
+    if (env.SESSION_SECRET.length < 32) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["SESSION_SECRET"],
+        message:
+          "SESSION_SECRET must be at least 32 characters when AUTH_GOOGLE_ENABLED=true",
+      });
+    }
+  });
+
+export type Env = z.infer<typeof envSchema>;
+
+let validatedEnv: Env | undefined;
+
+function parseEnv(config: Record<string, unknown>): Env {
+  const parsed = envSchema.safeParse(config);
+
+  if (parsed.success) {
+    return parsed.data;
+  }
+
+  const details = parsed.error.issues
+    .map((issue) => `- ${issue.path.join(".") || "env"}: ${issue.message}`)
+    .join("\n");
+
+  throw new Error(`Environment validation failed:\n${details}`);
+}
+
+export function validate(config: Record<string, unknown>): Env {
+  validatedEnv = parseEnv(config);
+  return validatedEnv;
+}
+
+export function getEnv(): Env {
+  validatedEnv ??= parseEnv(process.env);
+  return validatedEnv;
+}

package/template/src/config/index.ts

@@ -0,0 +1,5 @@
+export { default as appConfig } from "./app.config";
+export { default as authConfig } from "./auth.config";
+export { default as databaseConfig } from "./database.config";
+export { default as rbacConfig } from "./rbac.config";
+export { validate } from "./env.validation";

package/template/src/config/rbac.config.ts

@@ -0,0 +1,6 @@
+import { registerAs } from "@nestjs/config";
+import { getEnv } from "./env.validation";
+
+export default registerAs("rbac", () => ({
+  cacheTtlSeconds: getEnv().RBAC_CACHE_TTL_SECONDS,
+}));

package/template/src/database/prisma/prisma-transaction.ts

@@ -0,0 +1,22 @@
+import { Prisma } from "@prisma/client";
+
+type TransactionOptions = {
+  maxWait?: number;
+  timeout?: number;
+  isolationLevel?: Prisma.TransactionIsolationLevel;
+};
+
+type TransactionCapablePrisma = {
+  $transaction<T>(
+    fn: (tx: Prisma.TransactionClient) => Promise<T>,
+    options?: TransactionOptions,
+  ): Promise<T>;
+};
+
+export function runInTransaction<T>(
+  prisma: TransactionCapablePrisma,
+  fn: (tx: Prisma.TransactionClient) => Promise<T>,
+  options?: TransactionOptions,
+) {
+  return prisma.$transaction(fn, options);
+}

package/template/src/database/prisma/prisma.module.ts

@@ -0,0 +1,9 @@
+import { Global, Module } from "@nestjs/common";
+import { PrismaService } from "./prisma.service";
+
+@Global()
+@Module({
+  providers: [PrismaService],
+  exports: [PrismaService],
+})
+export class PrismaModule {}

package/template/src/database/prisma/prisma.service.ts

@@ -0,0 +1,16 @@
+import { Injectable, OnModuleDestroy, OnModuleInit } from "@nestjs/common";
+import { PrismaClient } from "@prisma/client";
+
+@Injectable()
+export class PrismaService
+  extends PrismaClient
+  implements OnModuleInit, OnModuleDestroy
+{
+  async onModuleInit() {
+    await this.$connect();
+  }
+
+  async onModuleDestroy() {
+    await this.$disconnect();
+  }
+}

package/template/src/main.ts

@@ -0,0 +1,42 @@
+import { ValidationPipe } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { NestFactory } from "@nestjs/core";
+import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
+import { AppModule } from "./app.module";
+import { HttpExceptionFilter } from "./common/filters/http-exception.filter";
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  const config = app.get(ConfigService);
+  app.enableShutdownHooks();
+  app.useGlobalFilters(new HttpExceptionFilter());
+
+  app.useGlobalPipes(
+    new ValidationPipe({
+      forbidNonWhitelisted: true,
+      transform: true,
+      whitelist: true,
+    }),
+  );
+
+  const document = SwaggerModule.createDocument(
+    app,
+    new DocumentBuilder()
+      .setTitle("Foundation Starter API")
+      .setDescription(
+        "Modular-monolith starter API with auth, organisations, RBAC, audit, and settings.",
+      )
+      .setVersion("0.1.0")
+      .addBearerAuth()
+      .build(),
+  );
+  SwaggerModule.setup("docs", app, document, {
+    swaggerOptions: {
+      persistAuthorization: true,
+    },
+  });
+
+  await app.listen(config.get<number>("app.port") ?? 3000);
+}
+
+void bootstrap();

package/template/src/modules/access-control/access-control.module.ts

@@ -0,0 +1,24 @@
+import { Global, Module } from "@nestjs/common";
+import { DiscoveryModule } from "@nestjs/core";
+import { AuthModule } from "../auth/auth.module";
+import { RouteRegistryValidator } from "./application/route-registry.validator";
+import { AbilityFactory } from "./application/services/ability.factory";
+import { AccessControlService } from "./application/services/access-control.service";
+import { PermissionGuard } from "./application/services/permission.guard";
+import { RbacCacheService } from "./application/services/rbac-cache.service";
+import { AccessControlController } from "./presentation/access-control.controller";
+
+@Global()
+@Module({
+  imports: [AuthModule, DiscoveryModule],
+  controllers: [AccessControlController],
+  providers: [
+    AbilityFactory,
+    AccessControlService,
+    PermissionGuard,
+    RbacCacheService,
+    RouteRegistryValidator,
+  ],
+  exports: [AbilityFactory, PermissionGuard, RbacCacheService],
+})
+export class AccessControlModule {}