@ftisindia/create-app 0.1.0

package/template/src/modules/access-control/dto/access-control-response.dto.ts

@@ -0,0 +1,79 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+
+export class PermissionResponseDto {
+  @ApiProperty({
+    example: "47bf2e11-6849-49cf-9138-f57c4e7ec0ac",
+    format: "uuid",
+  })
+  id!: string;
+
+  @ApiProperty({ example: "memberships.read" })
+  key!: string;
+
+  @ApiProperty({ example: "memberships" })
+  module!: string;
+
+  @ApiProperty({ example: "read" })
+  action!: string;
+
+  @ApiProperty({ example: "Membership" })
+  subject!: string;
+
+  @ApiPropertyOptional({
+    example: "Read organisation memberships.",
+    nullable: true,
+  })
+  description?: string | null;
+
+  @ApiProperty({ example: "2026-06-01T10:30:00.000Z", format: "date-time" })
+  createdAt!: string;
+}
+
+export class RoutePermissionResponseDto {
+  @ApiProperty({ example: "GET" })
+  method!: string;
+
+  @ApiProperty({ example: "/organisations/:orgId/memberships" })
+  path!: string;
+
+  @ApiProperty({ example: ["memberships.read"], type: [String] })
+  permissions!: string[];
+}
+
+export class RoleResponseDto {
+  @ApiProperty({
+    example: "f602c057-04f4-4ef8-8c84-1b7c62fbf8c5",
+    format: "uuid",
+  })
+  id!: string;
+
+  @ApiProperty({
+    example: "2c67399d-670c-4025-a5fd-1ea9a211891e",
+    format: "uuid",
+  })
+  orgId!: string;
+
+  @ApiProperty({ example: "Support" })
+  name!: string;
+
+  @ApiPropertyOptional({
+    example: "Can review support-facing records.",
+    nullable: true,
+  })
+  description?: string | null;
+
+  @ApiProperty({ example: false })
+  isSystemSeeded!: boolean;
+
+  @ApiProperty({ example: 3 })
+  membershipCount!: number;
+
+  @ApiProperty({ type: [PermissionResponseDto] })
+  permissions!: PermissionResponseDto[];
+
+  @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/access-control/dto/create-role.dto.ts

@@ -0,0 +1,18 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { Transform } from "class-transformer";
+import { IsOptional, IsString, MaxLength, MinLength } from "class-validator";
+
+export class CreateRoleDto {
+  @ApiProperty({ example: "Support" })
+  @Transform(({ value }) => (typeof value === "string" ? value.trim() : value))
+  @IsString()
+  @MinLength(2)
+  @MaxLength(80)
+  name!: string;
+
+  @ApiPropertyOptional({ example: "Can review support-facing records." })
+  @IsOptional()
+  @IsString()
+  @MaxLength(240)
+  description?: string;
+}

package/template/src/modules/access-control/dto/update-role-permissions.dto.ts

@@ -0,0 +1,23 @@
+import { ApiProperty } from "@nestjs/swagger";
+import {
+  ArrayMaxSize,
+  ArrayUnique,
+  IsArray,
+  IsString,
+  Matches,
+  MaxLength,
+} from "class-validator";
+
+export class UpdateRolePermissionsDto {
+  @ApiProperty({
+    example: ["memberships.read", "settings.read"],
+    isArray: true,
+  })
+  @IsArray()
+  @ArrayUnique()
+  @ArrayMaxSize(100)
+  @IsString({ each: true })
+  @MaxLength(120, { each: true })
+  @Matches(/^[a-z][a-z0-9_-]*\.[a-z][a-z0-9_-]*$/, { each: true })
+  permissionKeys!: string[];
+}

package/template/src/modules/access-control/dto/update-role.dto.ts

@@ -0,0 +1,19 @@
+import { ApiPropertyOptional } from "@nestjs/swagger";
+import { Transform } from "class-transformer";
+import { IsOptional, IsString, MaxLength, MinLength } from "class-validator";
+
+export class UpdateRoleDto {
+  @ApiPropertyOptional({ example: "Support Lead" })
+  @IsOptional()
+  @Transform(({ value }) => (typeof value === "string" ? value.trim() : value))
+  @IsString()
+  @MinLength(2)
+  @MaxLength(80)
+  name?: string;
+
+  @ApiPropertyOptional({ example: "Can manage support-facing records." })
+  @IsOptional()
+  @IsString()
+  @MaxLength(240)
+  description?: string;
+}

package/template/src/modules/access-control/presentation/access-control.controller.ts

@@ -0,0 +1,157 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Param,
+  Patch,
+  Post,
+  Put,
+  UseGuards,
+} from "@nestjs/common";
+import {
+  ApiBearerAuth,
+  ApiCreatedResponse,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+} from "@nestjs/swagger";
+import { DeletedResponseDto } from "../../../common/dto/mutation-response.dto";
+import { ApiProtectedErrorResponses } from "../../../common/swagger/api-error-responses";
+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 { AccessControlService } from "../application/services/access-control.service";
+import { PermissionGuard } from "../application/services/permission.guard";
+import {
+  PermissionResponseDto,
+  RoleResponseDto,
+  RoutePermissionResponseDto,
+} from "../dto/access-control-response.dto";
+import { CreateRoleDto } from "../dto/create-role.dto";
+import { UpdateRolePermissionsDto } from "../dto/update-role-permissions.dto";
+import { UpdateRoleDto } from "../dto/update-role.dto";
+import { RequirePermissions } from "./permissions.decorator";
+
+@ApiTags("Access control")
+@ApiBearerAuth()
+@ApiParam({ name: "orgId", description: "Organisation ID.", format: "uuid" })
+@ApiProtectedErrorResponses(404, 409)
+@Controller("organisations/:orgId/access-control")
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class AccessControlController {
+  constructor(private readonly accessControlService: AccessControlService) {}
+
+  @Get("permissions")
+  @RequirePermissions("roles.read")
+  @ApiOperation({ summary: "List the seeded permission catalogue." })
+  @ApiOkResponse({
+    description: "Available permissions.",
+    type: [PermissionResponseDto],
+  })
+  listPermissions() {
+    return this.accessControlService.listPermissions();
+  }
+
+  @Get("route-permissions")
+  @RequirePermissions("roles.read")
+  @ApiOperation({
+    summary: "List permission requirements for protected routes.",
+  })
+  @ApiOkResponse({
+    description: "Protected route permission registry.",
+    type: [RoutePermissionResponseDto],
+  })
+  listRoutePermissions() {
+    return this.accessControlService.listRoutePermissions();
+  }
+
+  @Get("roles")
+  @RequirePermissions("roles.read")
+  @ApiOperation({ summary: "List organisation roles." })
+  @ApiOkResponse({
+    description: "Organisation roles.",
+    type: [RoleResponseDto],
+  })
+  listRoles(@Param("orgId") orgId: string) {
+    return this.accessControlService.listRoles(orgId);
+  }
+
+  @Post("roles")
+  @RequirePermissions("roles.manage")
+  @ApiOperation({ summary: "Create an organisation role." })
+  @ApiCreatedResponse({ description: "Role created.", type: RoleResponseDto })
+  createRole(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param("orgId") orgId: string,
+    @Body() dto: CreateRoleDto,
+  ) {
+    return this.accessControlService.createRole(user, orgId, dto);
+  }
+
+  @Patch("roles/:roleId")
+  @RequirePermissions("roles.manage")
+  @ApiParam({ name: "roleId", description: "Role ID.", format: "uuid" })
+  @ApiOperation({ summary: "Update role name or description." })
+  @ApiOkResponse({ description: "Role updated.", type: RoleResponseDto })
+  updateRole(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param("orgId") orgId: string,
+    @Param("roleId") roleId: string,
+    @Body() dto: UpdateRoleDto,
+  ) {
+    return this.accessControlService.updateRole(user, orgId, roleId, dto);
+  }
+
+  @Delete("roles/:roleId")
+  @RequirePermissions("roles.manage")
+  @ApiParam({ name: "roleId", description: "Role ID.", format: "uuid" })
+  @ApiOperation({ summary: "Delete an unused non-system role." })
+  @ApiOkResponse({ description: "Role deleted.", type: DeletedResponseDto })
+  deleteRole(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param("orgId") orgId: string,
+    @Param("roleId") roleId: string,
+  ) {
+    return this.accessControlService.deleteRole(user, orgId, roleId);
+  }
+
+  @Get("roles/:roleId/permissions")
+  @RequirePermissions("roles.read")
+  @ApiParam({ name: "roleId", description: "Role ID.", format: "uuid" })
+  @ApiOperation({ summary: "Return role permissions." })
+  @ApiOkResponse({
+    description: "Role with assigned permissions.",
+    type: RoleResponseDto,
+  })
+  listRolePermissions(
+    @Param("orgId") orgId: string,
+    @Param("roleId") roleId: string,
+  ) {
+    return this.accessControlService.listRolePermissions(orgId, roleId);
+  }
+
+  @Put("roles/:roleId/permissions")
+  @RequirePermissions("permissions.assign")
+  @ApiParam({ name: "roleId", description: "Role ID.", format: "uuid" })
+  @ApiOperation({ summary: "Replace all permissions assigned to a role." })
+  @ApiOkResponse({
+    description: "Role with replacement permissions.",
+    type: RoleResponseDto,
+  })
+  replaceRolePermissions(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param("orgId") orgId: string,
+    @Param("roleId") roleId: string,
+    @Body() dto: UpdateRolePermissionsDto,
+  ) {
+    return this.accessControlService.replaceRolePermissions(
+      user,
+      orgId,
+      roleId,
+      dto,
+    );
+  }
+}

package/template/src/modules/access-control/presentation/permissions.decorator.ts

@@ -0,0 +1,8 @@
+import { SetMetadata } from "@nestjs/common";
+import { PermissionKey } from "../types/permission-key";
+
+export const REQUIRED_PERMISSIONS_KEY = "requiredPermissions";
+
+export function RequirePermissions(...permissions: PermissionKey[]) {
+  return SetMetadata(REQUIRED_PERMISSIONS_KEY, permissions);
+}

package/template/src/modules/access-control/presentation/public.decorator.ts

@@ -0,0 +1,7 @@
+import { SetMetadata } from "@nestjs/common";
+
+export const IS_PUBLIC_KEY = "isPublic";
+
+export function Public() {
+  return SetMetadata(IS_PUBLIC_KEY, true);
+}

package/template/src/modules/access-control/types/permission-key.ts

@@ -0,0 +1,37 @@
+export const permissionKeys = [
+  "users.read",
+  "users.create",
+  "users.update",
+  "users.suspend",
+  "organisations.read",
+  "organisations.update",
+  "memberships.read",
+  "memberships.invite",
+  "memberships.revoke",
+  "roles.read",
+  "roles.manage",
+  "permissions.assign",
+  "billing.read",
+  "billing.manage",
+  "settings.read",
+  "settings.update",
+  "audit.read",
+  "platform.admin",
+] as const;
+
+export type PermissionKey = (typeof permissionKeys)[number];
+
+export type RoutePermissionEntry = {
+  method: string;
+  path: string;
+  permissions: PermissionKey[];
+};
+
+export function permissionKeyToRule(key: string) {
+  const [subject, action] = key.split(".", 2);
+  if (!subject || !action) {
+    throw new Error(`Invalid permission key: ${key}`);
+  }
+
+  return { action, subject };
+}

package/template/src/modules/access-control/types/rbac-context.ts

@@ -0,0 +1,11 @@
+export type RbacContext = {
+  cacheKey: string;
+  userId: string;
+  orgId: string;
+  membershipId: string;
+  membershipStatus: string;
+  roleId: string;
+  isOwner: boolean;
+  isBillingContact: boolean;
+  permissionKeys: string[];
+};

package/template/src/modules/access-control/types/route-permission-registry.ts

@@ -0,0 +1,129 @@
+import { RoutePermissionEntry } from "./permission-key";
+
+export const routePermissionRegistry: RoutePermissionEntry[] = [
+  {
+    method: "GET",
+    path: "/organisations/:orgId/memberships/me",
+    permissions: ["memberships.read"],
+  },
+  {
+    method: "GET",
+    path: "/organisations/:orgId/memberships",
+    permissions: ["memberships.read"],
+  },
+  {
+    method: "PATCH",
+    path: "/organisations/:orgId/memberships/:membershipId/status",
+    permissions: ["memberships.revoke"],
+  },
+  {
+    method: "PATCH",
+    path: "/organisations/:orgId/memberships/:membershipId/role",
+    permissions: ["roles.manage"],
+  },
+  {
+    method: "PATCH",
+    path: "/organisations/:orgId/memberships/:membershipId/owner",
+    permissions: ["roles.manage"],
+  },
+  {
+    method: "PATCH",
+    path: "/organisations/:orgId/memberships/:membershipId/billing-contact",
+    permissions: ["billing.manage"],
+  },
+  {
+    method: "POST",
+    path: "/organisations/:orgId/memberships/transfer-owner",
+    permissions: ["roles.manage"],
+  },
+  {
+    method: "POST",
+    path: "/organisations/:orgId/invitations",
+    permissions: ["memberships.invite"],
+  },
+  {
+    method: "GET",
+    path: "/organisations/:orgId/invitations",
+    permissions: ["memberships.read"],
+  },
+  {
+    method: "POST",
+    path: "/organisations/:orgId/invitations/:invitationId/revoke",
+    permissions: ["memberships.revoke"],
+  },
+  {
+    method: "POST",
+    path: "/organisations/:orgId/invitations/:invitationId/resend",
+    permissions: ["memberships.invite"],
+  },
+  {
+    method: "GET",
+    path: "/organisations/:orgId/access-control/permissions",
+    permissions: ["roles.read"],
+  },
+  {
+    method: "GET",
+    path: "/organisations/:orgId/access-control/roles",
+    permissions: ["roles.read"],
+  },
+  {
+    method: "POST",
+    path: "/organisations/:orgId/access-control/roles",
+    permissions: ["roles.manage"],
+  },
+  {
+    method: "PATCH",
+    path: "/organisations/:orgId/access-control/roles/:roleId",
+    permissions: ["roles.manage"],
+  },
+  {
+    method: "DELETE",
+    path: "/organisations/:orgId/access-control/roles/:roleId",
+    permissions: ["roles.manage"],
+  },
+  {
+    method: "GET",
+    path: "/organisations/:orgId/access-control/roles/:roleId/permissions",
+    permissions: ["roles.read"],
+  },
+  {
+    method: "PUT",
+    path: "/organisations/:orgId/access-control/roles/:roleId/permissions",
+    permissions: ["permissions.assign"],
+  },
+  {
+    method: "GET",
+    path: "/organisations/:orgId/access-control/route-permissions",
+    permissions: ["roles.read"],
+  },
+  {
+    method: "GET",
+    path: "/organisations/:orgId/audit",
+    permissions: ["audit.read"],
+  },
+  {
+    method: "GET",
+    path: "/organisations/:orgId/settings",
+    permissions: ["settings.read"],
+  },
+  {
+    method: "GET",
+    path: "/organisations/:orgId/settings/:key",
+    permissions: ["settings.read"],
+  },
+  {
+    method: "PATCH",
+    path: "/organisations/:orgId/settings",
+    permissions: ["settings.update"],
+  },
+  {
+    method: "GET",
+    path: "/organisations/:orgId/sample/status",
+    permissions: ["organisations.read"],
+  },
+  {
+    method: "POST",
+    path: "/organisations/:orgId/sample/echo",
+    permissions: ["organisations.update"],
+  },
+];

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

@@ -0,0 +1,97 @@
+import { BadRequestException, Injectable } from "@nestjs/common";
+import { Prisma } from "@prisma/client";
+import { PrismaService } from "../../../../database/prisma/prisma.service";
+import { RequestContextService } from "../../../request-context/application/services/request-context.service";
+import { ListAuditLogsQueryDto } from "../../dto/list-audit-logs-query.dto";
+
+type PrismaClient = Prisma.TransactionClient | PrismaService;
+
+export type AuditWriteInput = {
+  orgId?: string | null;
+  actorUserId?: string | null;
+  action: string;
+  targetType: string;
+  targetId?: string | null;
+  metadata?: Prisma.InputJsonValue;
+};
+
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 100;
+
+@Injectable()
+export class AuditService {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly requestContext: RequestContextService,
+  ) {}
+
+  async write(client: PrismaClient, data: AuditWriteInput) {
+    const context = this.requestContext.get();
+
+    await client.auditLog.create({
+      data: {
+        orgId: data.orgId ?? null,
+        actorUserId: data.actorUserId ?? context?.userId ?? null,
+        action: data.action,
+        targetType: data.targetType,
+        targetId: data.targetId ?? null,
+        metadata: data.metadata === undefined ? Prisma.JsonNull : data.metadata,
+        ipAddress: context?.ipAddress,
+        userAgent: context?.userAgent,
+      },
+    });
+  }
+
+  async listOrgLogs(orgId: string, query: ListAuditLogsQueryDto) {
+    this.requestContext.assertOrgScope(orgId);
+
+    const limit = Math.min(query.limit ?? DEFAULT_LIMIT, MAX_LIMIT);
+    if (query.from && query.to && new Date(query.from) > new Date(query.to)) {
+      throw new BadRequestException("from must be before or equal to to.");
+    }
+
+    const createdAt: Prisma.DateTimeFilter =
+      query.from || query.to
+        ? {
+            gte: query.from ? new Date(query.from) : undefined,
+            lte: query.to ? new Date(query.to) : undefined,
+          }
+        : {};
+    const where: Prisma.AuditLogWhereInput = {
+      orgId,
+      action: query.action,
+      actorUserId: query.actorUserId,
+      targetType: query.targetType,
+      targetId: query.targetId,
+      ...(query.from || query.to ? { createdAt } : {}),
+    };
+
+    const rows = await this.prisma.auditLog.findMany({
+      where,
+      include: {
+        actorUser: {
+          select: {
+            id: true,
+            displayName: true,
+          },
+        },
+      },
+      orderBy: [{ createdAt: "desc" }, { id: "desc" }],
+      take: limit + 1,
+      ...(query.cursor
+        ? {
+            cursor: { id: query.cursor },
+            skip: 1,
+          }
+        : {}),
+    });
+
+    const hasMore = rows.length > limit;
+    const items = rows.slice(0, limit);
+
+    return {
+      items,
+      nextCursor: hasMore ? items[items.length - 1]?.id : null,
+    };
+  }
+}

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

@@ -0,0 +1,13 @@
+import { Global, Module } from "@nestjs/common";
+import { AuthModule } from "../auth/auth.module";
+import { AuditService } from "./application/services/audit.service";
+import { AuditController } from "./presentation/audit.controller";
+
+@Global()
+@Module({
+  imports: [AuthModule],
+  controllers: [AuditController],
+  providers: [AuditService],
+  exports: [AuditService],
+})
+export class AuditModule {}

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

@@ -0,0 +1,75 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+
+class AuditActorResponseDto {
+  @ApiProperty({
+    example: "4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456",
+    format: "uuid",
+  })
+  id!: string;
+
+  @ApiPropertyOptional({ example: "Starter Owner", nullable: true })
+  displayName?: string | null;
+}
+
+export class AuditLogResponseDto {
+  @ApiProperty({
+    example: "df6537c4-f58b-452e-a67e-18ec528d0f0f",
+    format: "uuid",
+  })
+  id!: string;
+
+  @ApiPropertyOptional({
+    example: "2c67399d-670c-4025-a5fd-1ea9a211891e",
+    format: "uuid",
+    nullable: true,
+  })
+  orgId?: string | null;
+
+  @ApiPropertyOptional({
+    example: "4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456",
+    format: "uuid",
+    nullable: true,
+  })
+  actorUserId?: string | null;
+
+  @ApiProperty({ example: "membership.status.update" })
+  action!: string;
+
+  @ApiProperty({ example: "Membership" })
+  targetType!: string;
+
+  @ApiPropertyOptional({
+    example: "0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3",
+    nullable: true,
+  })
+  targetId?: string | null;
+
+  @ApiPropertyOptional({
+    example: { previousStatus: "ACTIVE", nextStatus: "SUSPENDED" },
+    nullable: true,
+  })
+  metadata?: Record<string, unknown> | null;
+
+  @ApiPropertyOptional({ example: "127.0.0.1", nullable: true })
+  ipAddress?: string | null;
+
+  @ApiPropertyOptional({ example: "Mozilla/5.0", nullable: true })
+  userAgent?: string | null;
+
+  @ApiProperty({ example: "2026-06-01T10:30:00.000Z", format: "date-time" })
+  createdAt!: string;
+
+  @ApiPropertyOptional({ type: AuditActorResponseDto, nullable: true })
+  actorUser?: AuditActorResponseDto | null;
+}
+
+export class AuditLogListResponseDto {
+  @ApiProperty({ type: [AuditLogResponseDto] })
+  items!: AuditLogResponseDto[];
+
+  @ApiPropertyOptional({
+    example: "df6537c4-f58b-452e-a67e-18ec528d0f0f",
+    nullable: true,
+  })
+  nextCursor?: string | null;
+}