@ftisindia/create-app 0.1.0

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

@@ -0,0 +1,63 @@
+import {
+  Body,
+  Controller,
+  Get,
+  HttpCode,
+  Param,
+  Post,
+  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 { CurrentUser } from "../../auth/presentation/current-user.decorator";
+import { AuthenticatedUser } from "../../auth/types/authenticated-user";
+import { OrgScopeGuard } from "../../request-context/presentation/org-scope.guard";
+import { SampleEchoDto } from "../dto/sample-echo.dto";
+import {
+  SampleEchoResponseDto,
+  SampleStatusResponseDto,
+} from "../dto/sample-response.dto";
+import { SampleService } from "../application/services/sample.service";
+
+@ApiTags("Sample")
+@ApiBearerAuth()
+@ApiParam({ name: "orgId", description: "Organisation ID.", format: "uuid" })
+@ApiProtectedErrorResponses()
+@Controller("organisations/:orgId/sample")
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class SampleController {
+  constructor(private readonly sampleService: SampleService) {}
+
+  @Get("status")
+  @RequirePermissions("organisations.read")
+  @ApiOperation({ summary: "Return sample module status and request context." })
+  @ApiOkResponse({
+    description: "Sample status.",
+    type: SampleStatusResponseDto,
+  })
+  status(@Param("orgId") orgId: string) {
+    return this.sampleService.getStatus(orgId);
+  }
+
+  @Post("echo")
+  @HttpCode(200)
+  @RequirePermissions("organisations.update")
+  @ApiOperation({ summary: "Echo a message and write a sample audit record." })
+  @ApiOkResponse({ description: "Echo result.", type: SampleEchoResponseDto })
+  echo(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param("orgId") orgId: string,
+    @Body() dto: SampleEchoDto,
+  ) {
+    return this.sampleService.echo(user, orgId, dto);
+  }
+}

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

@@ -0,0 +1,11 @@
+import { Module } from "@nestjs/common";
+import { AuthModule } from "../auth/auth.module";
+import { SampleService } from "./application/services/sample.service";
+import { SampleController } from "./presentation/sample.controller";
+
+@Module({
+  imports: [AuthModule],
+  controllers: [SampleController],
+  providers: [SampleService],
+})
+export class SampleModule {}

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

@@ -0,0 +1,139 @@
+import {
+  BadRequestException,
+  Injectable,
+  NotFoundException,
+} from "@nestjs/common";
+import { Prisma } from "@prisma/client";
+import { PrismaService } from "../../../../database/prisma/prisma.service";
+import { AuditService } from "../../../audit/application/services/audit.service";
+import { AuthenticatedUser } from "../../../auth/types/authenticated-user";
+import { RequestContextService } from "../../../request-context/application/services/request-context.service";
+import { UpdateSettingDto } from "../../dto/update-setting.dto";
+import {
+  settingDefinitions,
+  SettingKey,
+} from "../../types/setting-definitions";
+
+@Injectable()
+export class SettingsService {
+  constructor(
+    private readonly auditService: AuditService,
+    private readonly prisma: PrismaService,
+    private readonly requestContext: RequestContextService,
+  ) {}
+
+  async listSettings(orgId: string) {
+    this.requestContext.assertOrgScope(orgId);
+
+    const settings = await this.prisma.organisationSetting.findMany({
+      where: { orgId },
+      orderBy: { key: "asc" },
+    });
+
+    return settings.map(serializeSetting);
+  }
+
+  async getSetting(orgId: string, key: string) {
+    this.requestContext.assertOrgScope(orgId);
+    assertKnownSettingKey(key);
+
+    const setting = await this.prisma.organisationSetting.findUnique({
+      where: {
+        orgId_key: {
+          orgId,
+          key,
+        },
+      },
+    });
+
+    if (!setting) {
+      throw new NotFoundException(
+        "Setting was not found for this organisation.",
+      );
+    }
+
+    return serializeSetting(setting);
+  }
+
+  async updateSetting(
+    currentUser: AuthenticatedUser,
+    orgId: string,
+    dto: UpdateSettingDto,
+  ) {
+    this.requestContext.assertOrgScope(orgId);
+    const definition = getSettingDefinition(dto.key);
+    const value = definition.parse(dto.value);
+
+    const updated = await this.prisma.$transaction(async (tx) => {
+      const previous = await tx.organisationSetting.findUnique({
+        where: {
+          orgId_key: {
+            orgId,
+            key: dto.key,
+          },
+        },
+      });
+
+      const setting = await tx.organisationSetting.upsert({
+        where: {
+          orgId_key: {
+            orgId,
+            key: dto.key,
+          },
+        },
+        update: { value },
+        create: {
+          orgId,
+          key: dto.key,
+          value,
+        },
+      });
+
+      await this.auditService.write(tx, {
+        orgId,
+        actorUserId: currentUser.id,
+        action: "organisation.setting.update",
+        targetType: "OrganisationSetting",
+        targetId: setting.id,
+        metadata: {
+          key: dto.key,
+          previousValue: previous?.value ?? null,
+          nextValue: value,
+        },
+      });
+
+      return setting;
+    });
+
+    return serializeSetting(updated);
+  }
+}
+
+function assertKnownSettingKey(key: string): asserts key is SettingKey {
+  if (!Object.hasOwn(settingDefinitions, key)) {
+    throw new BadRequestException("Unknown organisation setting key.");
+  }
+}
+
+function getSettingDefinition(key: string) {
+  assertKnownSettingKey(key);
+  return settingDefinitions[key];
+}
+
+function serializeSetting(setting: {
+  id: string;
+  orgId: string;
+  key: string;
+  value: Prisma.JsonValue;
+  createdAt: Date;
+  updatedAt: Date;
+}) {
+  return {
+    id: setting.id,
+    orgId: setting.orgId,
+    key: setting.key,
+    value: setting.value,
+    createdAt: setting.createdAt,
+    updatedAt: setting.updatedAt,
+  };
+}

package/template/src/modules/settings/dto/setting-response.dto.ts

@@ -0,0 +1,27 @@
+import { ApiProperty } from "@nestjs/swagger";
+
+export class SettingResponseDto {
+  @ApiProperty({
+    example: "949b2c7c-b6b4-4db6-a2ed-663fa5f6f877",
+    format: "uuid",
+  })
+  id!: string;
+
+  @ApiProperty({
+    example: "2c67399d-670c-4025-a5fd-1ea9a211891e",
+    format: "uuid",
+  })
+  orgId!: string;
+
+  @ApiProperty({ example: "timezone" })
+  key!: string;
+
+  @ApiProperty({ example: "UTC" })
+  value!: unknown;
+
+  @ApiProperty({ example: "2026-06-01T10:30:00.000Z", format: "date-time" })
+  createdAt!: string;
+
+  @ApiProperty({ example: "2026-06-01T10:30:00.000Z", format: "date-time" })
+  updatedAt!: string;
+}

package/template/src/modules/settings/dto/update-setting.dto.ts

@@ -0,0 +1,16 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsDefined, IsString, MaxLength } from "class-validator";
+
+export class UpdateSettingDto {
+  @ApiProperty({ example: "timezone", maxLength: 120 })
+  @IsString()
+  @MaxLength(120)
+  key!: string;
+
+  @ApiProperty({
+    description: "JSON value accepted by the setting definition.",
+    example: "UTC",
+  })
+  @IsDefined()
+  value!: unknown;
+}

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

@@ -0,0 +1,66 @@
+import { Body, Controller, Get, Param, Patch, 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 { CurrentUser } from "../../auth/presentation/current-user.decorator";
+import { AuthenticatedUser } from "../../auth/types/authenticated-user";
+import { OrgScopeGuard } from "../../request-context/presentation/org-scope.guard";
+import { UpdateSettingDto } from "../dto/update-setting.dto";
+import { SettingsService } from "../application/services/settings.service";
+import { SettingResponseDto } from "../dto/setting-response.dto";
+
+@ApiTags("Settings")
+@ApiBearerAuth()
+@ApiParam({ name: "orgId", description: "Organisation ID.", format: "uuid" })
+@ApiProtectedErrorResponses(404)
+@Controller("organisations/:orgId/settings")
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class SettingsController {
+  constructor(private readonly settingsService: SettingsService) {}
+
+  @Get()
+  @RequirePermissions("settings.read")
+  @ApiOperation({ summary: "List organisation settings." })
+  @ApiOkResponse({
+    description: "Organisation settings.",
+    type: [SettingResponseDto],
+  })
+  list(@Param("orgId") orgId: string) {
+    return this.settingsService.listSettings(orgId);
+  }
+
+  @Get(":key")
+  @RequirePermissions("settings.read")
+  @ApiParam({ name: "key", description: "Setting key.", example: "timezone" })
+  @ApiOperation({ summary: "Return one organisation setting." })
+  @ApiOkResponse({
+    description: "Organisation setting.",
+    type: SettingResponseDto,
+  })
+  get(@Param("orgId") orgId: string, @Param("key") key: string) {
+    return this.settingsService.getSetting(orgId, key);
+  }
+
+  @Patch()
+  @RequirePermissions("settings.update")
+  @ApiOperation({ summary: "Update one organisation setting." })
+  @ApiOkResponse({
+    description: "Updated organisation setting.",
+    type: SettingResponseDto,
+  })
+  update(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param("orgId") orgId: string,
+    @Body() dto: UpdateSettingDto,
+  ) {
+    return this.settingsService.updateSetting(user, orgId, dto);
+  }
+}

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

@@ -0,0 +1,12 @@
+import { Module } from "@nestjs/common";
+import { AuditModule } from "../audit/audit.module";
+import { AuthModule } from "../auth/auth.module";
+import { SettingsService } from "./application/services/settings.service";
+import { SettingsController } from "./presentation/settings.controller";
+
+@Module({
+  imports: [AuditModule, AuthModule],
+  controllers: [SettingsController],
+  providers: [SettingsService],
+})
+export class SettingsModule {}

package/template/src/modules/settings/types/setting-definitions.ts

@@ -0,0 +1,104 @@
+import { BadRequestException } from "@nestjs/common";
+import { Prisma } from "@prisma/client";
+
+type SettingDefinition = {
+  defaultValue: Prisma.InputJsonValue;
+  parse: (value: unknown) => Prisma.InputJsonValue;
+};
+
+export const settingDefinitions = {
+  "billing.plan": {
+    defaultValue: "free",
+    parse: parseEnum(["free", "starter", "pro", "enterprise"]),
+  },
+  "features.inventory_enabled": {
+    defaultValue: false,
+    parse: parseBoolean,
+  },
+  "features.reports_enabled": {
+    defaultValue: false,
+    parse: parseBoolean,
+  },
+  "notifications.email_enabled": {
+    defaultValue: true,
+    parse: parseBoolean,
+  },
+  "invoice.prefix": {
+    defaultValue: "INV",
+    parse: parseShortString("invoice.prefix", 1, 20),
+  },
+  "invoice.approval_required": {
+    defaultValue: false,
+    parse: parseBoolean,
+  },
+  "branding.logo_url": {
+    defaultValue: "",
+    parse: parseOptionalUrl,
+  },
+} satisfies Record<string, SettingDefinition>;
+
+export type SettingKey = keyof typeof settingDefinitions;
+
+function parseBoolean(value: unknown) {
+  if (typeof value !== "boolean") {
+    throw new BadRequestException("Setting value must be a boolean.");
+  }
+
+  return value;
+}
+
+function parseEnum(allowed: string[]) {
+  return (value: unknown) => {
+    if (typeof value !== "string" || !allowed.includes(value)) {
+      throw new BadRequestException(
+        `Setting value must be one of: ${allowed.join(", ")}.`,
+      );
+    }
+
+    return value;
+  };
+}
+
+function parseShortString(key: string, min: number, max: number) {
+  return (value: unknown) => {
+    if (typeof value !== "string") {
+      throw new BadRequestException(`${key} must be a string.`);
+    }
+
+    const normalized = value.trim();
+    if (normalized.length < min || normalized.length > max) {
+      throw new BadRequestException(
+        `${key} must be between ${min} and ${max} characters.`,
+      );
+    }
+
+    return normalized;
+  };
+}
+
+function parseOptionalUrl(value: unknown) {
+  if (value === null || value === "") {
+    return "";
+  }
+
+  if (typeof value !== "string") {
+    throw new BadRequestException("branding.logo_url must be a URL string.");
+  }
+
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new BadRequestException(
+        "branding.logo_url must use http or https.",
+      );
+    }
+
+    return url.toString();
+  } catch (error) {
+    if (error instanceof BadRequestException) {
+      throw error;
+    }
+
+    throw new BadRequestException("branding.logo_url must be a valid URL.");
+  }
+}

package/template/src/modules/users/.gitkeep

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

package/template/test/.gitkeep

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

package/template/test/jest-e2e.json

@@ -0,0 +1,9 @@
+{
+  "moduleFileExtensions": ["js", "json", "ts"],
+  "rootDir": "..",
+  "testEnvironment": "node",
+  "testRegex": ".e2e-spec.ts$",
+  "transform": {
+    "^.+\\.(t|j)s$": "ts-jest"
+  }
+}

package/template/test/permission.guard.spec.ts

@@ -0,0 +1,22 @@
+import { ExecutionContext, ForbiddenException } from '@nestjs/common';
+import { PermissionGuard } from '../src/modules/access-control/application/services/permission.guard';
+
+describe('PermissionGuard', () => {
+  it('fails closed when a protected route has no permission metadata', async () => {
+    const guard = new PermissionGuard(
+      {} as never,
+      {
+        getAllAndOverride: () => undefined,
+      } as never,
+      {} as never,
+      {} as never,
+    );
+
+    const context = {
+      getHandler: () => function handler() {},
+      getClass: () => class Controller {},
+    } as unknown as ExecutionContext;
+
+    await expect(guard.canActivate(context)).rejects.toBeInstanceOf(ForbiddenException);
+  });
+});

package/template/test/route-registry.validator.spec.ts

@@ -0,0 +1,90 @@
+import { Controller, Get } from '@nestjs/common';
+import { MetadataScanner, Reflector } from '@nestjs/core';
+import { AccessControlController } from '../src/modules/access-control/presentation/access-control.controller';
+import { RequirePermissions } from '../src/modules/access-control/presentation/permissions.decorator';
+import { RouteRegistryValidator } from '../src/modules/access-control/application/route-registry.validator';
+import { PermissionKey } from '../src/modules/access-control/types/permission-key';
+import { AuditController } from '../src/modules/audit/presentation/audit.controller';
+import { AuthController } from '../src/modules/auth/presentation/auth.controller';
+import { InvitationsController } from '../src/modules/invitations/presentation/invitations.controller';
+import { MembershipsController } from '../src/modules/memberships/presentation/memberships.controller';
+import { OrganisationsController } from '../src/modules/organisations/presentation/organisations.controller';
+import { SampleController } from '../src/modules/sample/presentation/sample.controller';
+import { SettingsController } from '../src/modules/settings/presentation/settings.controller';
+
+const controllers = [
+  AccessControlController,
+  AuditController,
+  AuthController,
+  InvitationsController,
+  MembershipsController,
+  OrganisationsController,
+  SampleController,
+  SettingsController,
+];
+
+describe('RouteRegistryValidator', () => {
+  it('accepts the checked-in route permission registry', () => {
+    expect(() => createValidator(controllers).onApplicationBootstrap()).not.toThrow();
+  });
+
+  it('fails when a permission-gated route is missing from the registry', () => {
+    class DriftController {
+      probe() {
+        return undefined;
+      }
+    }
+
+    const descriptor = Object.getOwnPropertyDescriptor(
+      DriftController.prototype,
+      'probe',
+    ) as TypedPropertyDescriptor<() => undefined>;
+    Controller('organisations/:orgId/drift')(DriftController);
+    Get('probe')(DriftController.prototype, 'probe', descriptor);
+    RequirePermissions('users.read')(DriftController.prototype, 'probe', descriptor);
+
+    expect(() =>
+      createValidator([...controllers, DriftController]).onApplicationBootstrap(),
+    ).toThrow(/GET \/organisations\/:orgId\/drift\/probe/u);
+  });
+
+  it('fails when a route references an unknown permission key', () => {
+    class UnknownPermissionController {
+      probe() {
+        return undefined;
+      }
+    }
+
+    const descriptor = Object.getOwnPropertyDescriptor(
+      UnknownPermissionController.prototype,
+      'probe',
+    ) as TypedPropertyDescriptor<() => undefined>;
+    Controller('organisations/:orgId/unknown-permission')(UnknownPermissionController);
+    Get('probe')(UnknownPermissionController.prototype, 'probe', descriptor);
+    RequirePermissions('unknown.read' as PermissionKey)(
+      UnknownPermissionController.prototype,
+      'probe',
+      descriptor,
+    );
+
+    expect(() =>
+      createValidator([...controllers, UnknownPermissionController]).onApplicationBootstrap(),
+    ).toThrow(/unknown\.read/u);
+  });
+});
+
+type ControllerType = new (...args: never[]) => object;
+
+function createValidator(metatypes: ControllerType[]) {
+  return new RouteRegistryValidator(
+    {
+      getControllers: () =>
+        metatypes.map((metatype) => ({
+          instance: Object.create(metatype.prototype),
+          metatype,
+        })),
+    } as never,
+    new MetadataScanner(),
+    new Reflector(),
+  );
+}

package/template/test/security.e2e-spec.ts

@@ -0,0 +1,102 @@
+import { INestApplication, ValidationPipe } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+import { MembershipStatus } from '@prisma/client';
+import request from 'supertest';
+import { HttpExceptionFilter } from '../src/common/filters/http-exception.filter';
+import { PrismaService } from '../src/database/prisma/prisma.service';
+
+describe('Security invariants (e2e)', () => {
+  let app: INestApplication;
+  let prisma: PrismaService;
+
+  beforeAll(async () => {
+    process.env.DATABASE_URL = process.env.TEST_DATABASE_URL ?? process.env.DATABASE_URL;
+    process.env.JWT_SECRET ||= 'test-jwt-secret-at-least-16-chars';
+    process.env.AUTH_GOOGLE_ENABLED ||= 'false';
+    process.env.AUTH_EMAIL_PASSWORD_ENABLED ||= 'true';
+    process.env.NODE_ENV = 'test';
+
+    const { AppModule } = await import('../src/app.module');
+    const moduleRef = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleRef.createNestApplication();
+    app.useGlobalFilters(new HttpExceptionFilter());
+    app.useGlobalPipes(
+      new ValidationPipe({
+        forbidNonWhitelisted: true,
+        transform: true,
+        whitelist: true,
+      }),
+    );
+    await app.init();
+    prisma = app.get(PrismaService);
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('denies cross-organisation access', async () => {
+    const first = await createUserAndOrg('cross-a');
+    const second = await createUserAndOrg('cross-b');
+
+    await request(app.getHttpServer())
+      .get(`/organisations/${second.orgId}/sample/status`)
+      .set('Authorization', `Bearer ${first.accessToken}`)
+      .expect(403);
+  });
+
+  it('prevents removing the last active owner', async () => {
+    const { accessToken, orgId, membershipId } = await createUserAndOrg('last-owner');
+
+    await request(app.getHttpServer())
+      .patch(`/organisations/${orgId}/memberships/${membershipId}/owner`)
+      .set('Authorization', `Bearer ${accessToken}`)
+      .send({ isOwner: false })
+      .expect(409);
+  });
+
+  it('blocks suspended memberships in OrgScopeGuard/RBAC flow', async () => {
+    const { accessToken, orgId, membershipId } = await createUserAndOrg('suspended');
+
+    await prisma.membership.update({
+      where: { id: membershipId },
+      data: { status: MembershipStatus.SUSPENDED },
+    });
+
+    await request(app.getHttpServer())
+      .get(`/organisations/${orgId}/sample/status`)
+      .set('Authorization', `Bearer ${accessToken}`)
+      .expect(403);
+  });
+
+  async function createUserAndOrg(label: string) {
+    const suffix = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const signup = await request(app.getHttpServer())
+      .post('/auth/signup')
+      .send({
+        email: `${label}-${suffix}@example.com`,
+        password: 'test-password-123',
+        displayName: label,
+      })
+      .expect(201);
+
+    const accessToken = signup.body.accessToken as string;
+    const org = await request(app.getHttpServer())
+      .post('/organisations')
+      .set('Authorization', `Bearer ${accessToken}`)
+      .send({
+        name: `${label} ${suffix}`,
+        slug: `${label}-${suffix}`,
+      })
+      .expect(201);
+
+    return {
+      accessToken,
+      orgId: org.body.organisation.id as string,
+      membershipId: org.body.membership.id as string,
+    };
+  }
+});

package/template/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["node_modules", "test", "dist", "prisma", "scripts", "**/*spec.ts"]
+}