@ftisindia/create-app 0.1.3 → 0.1.5

package/template/src/modules/access-control/application/services/access-control.service.ts

@@ -3,16 +3,23 @@ import {
   ConflictException,
   Injectable,
   NotFoundException,
-} from "@nestjs/common";
-import { Prisma } from "@prisma/client";
-import { PrismaService } from "../../../../database/prisma/prisma.service";
-import { AuthenticatedUser } from "../../../auth/types/authenticated-user";
-import { RequestContextService } from "../../../request-context/application/services/request-context.service";
-import { CreateRoleDto } from "../../dto/create-role.dto";
-import { UpdateRolePermissionsDto } from "../../dto/update-role-permissions.dto";
-import { UpdateRoleDto } from "../../dto/update-role.dto";
-import { routePermissionRegistry } from "../../types/route-permission-registry";
-import { RbacCacheService } from "./rbac-cache.service";
+} from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import {
+  PaginationQueryDto,
+  resolvePageLimit,
+  toPage,
+} from '../../../../common/dto/pagination-query.dto';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+import { AuthenticatedUser } from '../../../auth/types/authenticated-user';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { CreateRoleDto } from '../../dto/create-role.dto';
+import { UpdateRolePermissionsDto } from '../../dto/update-role-permissions.dto';
+import { UpdateRoleDto } from '../../dto/update-role.dto';
+import { permissionKeys } from '../../types/permission-key';
+import { routePermissionRegistry } from '../../types/route-permission-registry';
+import { assertPermissionChangeWithinActor } from '../role-permission-policy';
+import { RbacCacheService } from './rbac-cache.service';
 
 const roleInclude = {
   permissions: {
@@ -20,7 +27,7 @@ const roleInclude = {
       permission: true,
     },
     orderBy: {
-      permissionId: "asc",
+      permissionId: 'asc',
     },
   },
   _count: {
@@ -42,7 +49,8 @@ export class AccessControlService {
 
   listPermissions() {
     return this.prisma.permission.findMany({
-      orderBy: [{ module: "asc" }, { action: "asc" }],
+      orderBy: [{ module: 'asc' }, { action: 'asc' }],
+      take: permissionKeys.length,
     });
   }
 
@@ -50,23 +58,27 @@ export class AccessControlService {
     return routePermissionRegistry;
   }
 
-  async listRoles(orgId: string) {
+  async listRoles(orgId: string, query: PaginationQueryDto) {
     this.requestContext.assertOrgScope(orgId);
+    const limit = resolvePageLimit(query.limit);
 
     const roles = await this.prisma.role.findMany({
       where: { orgId },
       include: roleInclude,
-      orderBy: [{ isSystemSeeded: "desc" }, { name: "asc" }],
+      orderBy: [{ isSystemSeeded: 'desc' }, { name: 'asc' }],
+      take: limit + 1,
+      ...(query.cursor
+        ? {
+            cursor: { id: query.cursor },
+            skip: 1,
+          }
+        : {}),
     });
 
-    return roles.map(serializeRole);
+    return toPage(roles.map(serializeRole), limit);
   }
 
-  async createRole(
-    currentUser: AuthenticatedUser,
-    orgId: string,
-    dto: CreateRoleDto,
-  ) {
+  async createRole(currentUser: AuthenticatedUser, orgId: string, dto: CreateRoleDto) {
     this.requestContext.assertOrgScope(orgId);
 
     const name = normalizeRoleName(dto.name);
@@ -86,7 +98,7 @@ export class AccessControlService {
         await this.writeAudit(tx, {
           orgId,
           actorUserId: currentUser.id,
-          action: "role.create",
+          action: 'role.create',
           targetId: created.id,
           metadata: {
             name: created.name,
@@ -100,9 +112,7 @@ export class AccessControlService {
       return serializeRole(role);
     } catch (error) {
       if (isPrismaUniqueError(error)) {
-        throw new ConflictException(
-          "Role name is already in use in this organisation.",
-        );
+        throw new ConflictException('Role name is already in use in this organisation.');
       }
 
       throw error;
@@ -119,25 +129,19 @@ export class AccessControlService {
 
     const existing = await this.findRoleInOrg(this.prisma, orgId, roleId);
     if (dto.name === undefined && dto.description === undefined) {
-      throw new BadRequestException(
-        "At least one role field must be provided.",
-      );
+      throw new BadRequestException('At least one role field must be provided.');
     }
 
     try {
       const result = await this.prisma.$transaction(async (tx) => {
-        const nextName =
-          dto.name === undefined ? existing.name : normalizeRoleName(dto.name);
+        const nextName = dto.name === undefined ? existing.name : normalizeRoleName(dto.name);
         assertValidRoleName(nextName);
         const nextDescription =
           dto.description === undefined
             ? existing.description
             : normalizeOptionalString(dto.description);
 
-        if (
-          nextName === existing.name &&
-          nextDescription === existing.description
-        ) {
+        if (nextName === existing.name && nextDescription === existing.description) {
           const role = await tx.role.findUniqueOrThrow({
             where: { id: existing.id },
             include: roleInclude,
@@ -158,7 +162,7 @@ export class AccessControlService {
         await this.writeAudit(tx, {
           orgId,
           actorUserId: currentUser.id,
-          action: "role.update",
+          action: 'role.update',
           targetId: updated.id,
           metadata: {
             previousName: existing.name,
@@ -178,25 +182,19 @@ export class AccessControlService {
       return serializeRole(result.role);
     } catch (error) {
       if (isPrismaUniqueError(error)) {
-        throw new ConflictException(
-          "Role name is already in use in this organisation.",
-        );
+        throw new ConflictException('Role name is already in use in this organisation.');
       }
 
       throw error;
     }
   }
 
-  async deleteRole(
-    currentUser: AuthenticatedUser,
-    orgId: string,
-    roleId: string,
-  ) {
+  async deleteRole(currentUser: AuthenticatedUser, orgId: string, roleId: string) {
     this.requestContext.assertOrgScope(orgId);
 
     const existing = await this.findRoleInOrg(this.prisma, orgId, roleId);
     if (existing.isSystemSeeded) {
-      throw new ConflictException("System-seeded roles cannot be deleted.");
+      throw new ConflictException('System-seeded roles cannot be deleted.');
     }
 
     try {
@@ -208,9 +206,7 @@ export class AccessControlService {
           },
         });
         if (membershipCount > 0) {
-          throw new ConflictException(
-            "Role cannot be deleted while memberships still use it.",
-          );
+          throw new ConflictException('Role cannot be deleted while memberships still use it.');
         }
 
         const invitationCount = await tx.invitation.count({
@@ -220,9 +216,7 @@ export class AccessControlService {
           },
         });
         if (invitationCount > 0) {
-          throw new ConflictException(
-            "Role cannot be deleted while invitations reference it.",
-          );
+          throw new ConflictException('Role cannot be deleted while invitations reference it.');
         }
 
         await tx.rolePermission.deleteMany({
@@ -236,7 +230,7 @@ export class AccessControlService {
         await this.writeAudit(tx, {
           orgId,
           actorUserId: currentUser.id,
-          action: "role.delete",
+          action: 'role.delete',
           targetId: roleId,
           metadata: {
             name: existing.name,
@@ -245,9 +239,7 @@ export class AccessControlService {
       });
     } catch (error) {
       if (isPrismaForeignKeyError(error)) {
-        throw new ConflictException(
-          "Role cannot be deleted while other records reference it.",
-        );
+        throw new ConflictException('Role cannot be deleted while other records reference it.');
       }
 
       throw error;
@@ -271,7 +263,7 @@ export class AccessControlService {
     });
 
     if (!role) {
-      throw new NotFoundException("Role was not found in this organisation.");
+      throw new NotFoundException('Role was not found in this organisation.');
     }
 
     return serializeRole(role);
@@ -301,14 +293,10 @@ export class AccessControlService {
             key: true,
           },
         });
-        const foundKeys = new Set(
-          permissions.map((permission) => permission.key),
-        );
+        const foundKeys = new Set(permissions.map((permission) => permission.key));
         const missingKeys = permissionKeys.filter((key) => !foundKeys.has(key));
         if (missingKeys.length > 0) {
-          throw new NotFoundException(
-            `Unknown permission keys: ${missingKeys.join(", ")}`,
-          );
+          throw new NotFoundException(`Unknown permission keys: ${missingKeys.join(', ')}`);
         }
 
         const previousPermissions = await tx.rolePermission.findMany({
@@ -328,6 +316,19 @@ export class AccessControlService {
           return { role: unchanged, changed: false };
         }
 
+        // Prevent privilege escalation: a non-owner actor may only add or
+        // remove permission keys they themselves hold (owners bypass). Without
+        // this, anyone with permissions.assign could rewrite a role to include
+        // permissions they lack and then assign it — bypassing the no-escalation
+        // checks on assignRole / createInvitation.
+        const actorContext = await this.rbacCache.getContext(currentUser.id, orgId);
+        assertPermissionChangeWithinActor({
+          actorIsOwner: actorContext.isOwner,
+          actorPermissionKeys: actorContext.permissionKeys,
+          previousPermissionKeys,
+          nextPermissionKeys: permissionKeys,
+        });
+
         await tx.rolePermission.deleteMany({
           where: { roleId },
         });
@@ -345,7 +346,7 @@ export class AccessControlService {
         await this.writeAudit(tx, {
           orgId,
           actorUserId: currentUser.id,
-          action: "role.permissions.replace",
+          action: 'role.permissions.replace',
           targetId: roleId,
           metadata: {
             roleName: role.name,
@@ -370,7 +371,7 @@ export class AccessControlService {
     } catch (error) {
       if (isPrismaForeignKeyError(error)) {
         throw new ConflictException(
-          "Role permissions could not be updated because referenced data changed.",
+          'Role permissions could not be updated because referenced data changed.',
         );
       }
 
@@ -378,9 +379,12 @@ export class AccessControlService {
     }
   }
 
-  private async findRoleInOrg<
-    TInclude extends Prisma.RoleInclude | undefined = undefined,
-  >(client: PrismaClient, orgId: string, roleId: string, include?: TInclude) {
+  private async findRoleInOrg<TInclude extends Prisma.RoleInclude | undefined = undefined>(
+    client: PrismaClient,
+    orgId: string,
+    roleId: string,
+    include?: TInclude,
+  ) {
     const role = await client.role.findUnique({
       where: {
         id_orgId: {
@@ -392,7 +396,7 @@ export class AccessControlService {
     });
 
     if (!role) {
-      throw new NotFoundException("Role was not found in this organisation.");
+      throw new NotFoundException('Role was not found in this organisation.');
     }
 
     return role;
@@ -413,19 +417,18 @@ export class AccessControlService {
         orgId: data.orgId,
         actorUserId: data.actorUserId,
         action: data.action,
-        targetType: "Role",
+        targetType: 'Role',
         targetId: data.targetId,
         metadata: data.metadata,
+        ipAddress: this.requestContext.getIpAddress(),
+        userAgent: this.requestContext.getUserAgent(),
       },
     });
   }
 }
 
 function arraysEqual(left: string[], right: string[]) {
-  return (
-    left.length === right.length &&
-    left.every((value, index) => value === right[index])
-  );
+  return left.length === right.length && left.every((value, index) => value === right[index]);
 }
 
 function normalizeRoleName(name: string) {
@@ -434,9 +437,7 @@ function normalizeRoleName(name: string) {
 
 function assertValidRoleName(name: string) {
   if (name.length < 2) {
-    throw new BadRequestException(
-      "Role name must contain at least 2 non-whitespace characters.",
-    );
+    throw new BadRequestException('Role name must contain at least 2 non-whitespace characters.');
   }
 }
 
@@ -446,22 +447,14 @@ function normalizeOptionalString(value: string | undefined) {
 }
 
 function isPrismaUniqueError(error: unknown) {
-  return (
-    error instanceof Prisma.PrismaClientKnownRequestError &&
-    error.code === "P2002"
-  );
+  return error instanceof Prisma.PrismaClientKnownRequestError && error.code === 'P2002';
 }
 
 function isPrismaForeignKeyError(error: unknown) {
-  return (
-    error instanceof Prisma.PrismaClientKnownRequestError &&
-    error.code === "P2003"
-  );
+  return error instanceof Prisma.PrismaClientKnownRequestError && error.code === 'P2003';
 }
 
-function serializeRole(
-  role: Prisma.RoleGetPayload<{ include: typeof roleInclude }>,
-) {
+function serializeRole(role: Prisma.RoleGetPayload<{ include: typeof roleInclude }>) {
   return {
     id: role.id,
     orgId: role.orgId,

package/template/src/modules/access-control/application/services/permission.guard.ts

@@ -1,17 +1,12 @@
-import {
-  CanActivate,
-  ExecutionContext,
-  ForbiddenException,
-  Injectable,
-} from "@nestjs/common";
-import { Reflector } from "@nestjs/core";
-import { AuthenticatedUser } from "../../../auth/types/authenticated-user";
-import { RequestContextService } from "../../../request-context/application/services/request-context.service";
-import { REQUIRED_PERMISSIONS_KEY } from "../../presentation/permissions.decorator";
-import { IS_PUBLIC_KEY } from "../../presentation/public.decorator";
-import { PermissionKey, permissionKeyToRule } from "../../types/permission-key";
-import { AbilityFactory } from "./ability.factory";
-import { RbacCacheService } from "./rbac-cache.service";
+import { CanActivate, ExecutionContext, ForbiddenException, Injectable } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { AuthenticatedUser } from '../../../auth/types/authenticated-user';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { REQUIRED_PERMISSIONS_KEY } from '../../presentation/permissions.decorator';
+import { IS_PUBLIC_KEY } from '../../presentation/public.decorator';
+import { PermissionKey, permissionKeyToRule } from '../../types/permission-key';
+import { AbilityFactory } from './ability.factory';
+import { RbacCacheService } from './rbac-cache.service';
 
 type RequestWithUser = {
   orgId?: string;
@@ -38,12 +33,12 @@ export class PermissionGuard implements CanActivate {
       return true;
     }
 
-    const required = this.reflector.getAllAndOverride<PermissionKey[]>(
-      REQUIRED_PERMISSIONS_KEY,
-      [context.getHandler(), context.getClass()],
-    );
+    const required = this.reflector.getAllAndOverride<PermissionKey[]>(REQUIRED_PERMISSIONS_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
     if (!required || required.length === 0) {
-      throw new ForbiddenException("Permission metadata is required.");
+      throw new ForbiddenException('Permission metadata is required.');
     }
 
     const request = context.switchToHttp().getRequest<RequestWithUser>();
@@ -51,7 +46,7 @@ export class PermissionGuard implements CanActivate {
     const orgId = request.orgId ?? request.params?.orgId;
 
     if (!user || !orgId) {
-      throw new ForbiddenException("Active organisation context is required.");
+      throw new ForbiddenException('Active organisation context is required.');
     }
 
     const rbac = await this.rbacCache.getContext(user.id, orgId);
@@ -63,7 +58,7 @@ export class PermissionGuard implements CanActivate {
     });
 
     if (!allowed) {
-      throw new ForbiddenException("Required permission is missing.");
+      throw new ForbiddenException('Required permission is missing.');
     }
 
     request.rbac = rbac;

package/template/src/modules/access-control/application/services/rbac-cache.service.ts

@@ -1,8 +1,8 @@
-import { ForbiddenException, Injectable } from "@nestjs/common";
-import { ConfigService } from "@nestjs/config";
-import { MembershipStatus } from "@prisma/client";
-import { PrismaService } from "../../../../database/prisma/prisma.service";
-import { RbacContext } from "../../types/rbac-context";
+import { ForbiddenException, Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { MembershipStatus } from '@prisma/client';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+import { RbacContext } from '../../types/rbac-context';
 
 type CacheEntry = {
   expiresAt: number;
@@ -53,9 +53,7 @@ export class RbacCacheService {
     });
 
     if (!membership || membership.status !== MembershipStatus.ACTIVE) {
-      throw new ForbiddenException(
-        "Active organisation membership is required.",
-      );
+      throw new ForbiddenException('Active organisation membership is required.');
     }
 
     const value: RbacContext = {
@@ -123,7 +121,7 @@ export class RbacCacheService {
   }
 
   private ttlMs() {
-    return (this.config.get<number>("rbac.cacheTtlSeconds") ?? 60) * 1000;
+    return (this.config.get<number>('rbac.cacheTtlSeconds') ?? 60) * 1000;
   }
 
   private sweepExpiredEntries() {

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

@@ -1,63 +1,63 @@
-import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 
 export class PermissionResponseDto {
   @ApiProperty({
-    example: "47bf2e11-6849-49cf-9138-f57c4e7ec0ac",
-    format: "uuid",
+    example: '47bf2e11-6849-49cf-9138-f57c4e7ec0ac',
+    format: 'uuid',
   })
   id!: string;
 
-  @ApiProperty({ example: "memberships.read" })
+  @ApiProperty({ example: 'memberships.read' })
   key!: string;
 
-  @ApiProperty({ example: "memberships" })
+  @ApiProperty({ example: 'memberships' })
   module!: string;
 
-  @ApiProperty({ example: "read" })
+  @ApiProperty({ example: 'read' })
   action!: string;
 
-  @ApiProperty({ example: "Membership" })
+  @ApiProperty({ example: 'Membership' })
   subject!: string;
 
   @ApiPropertyOptional({
-    example: "Read organisation memberships.",
+    example: 'Read organisation memberships.',
     nullable: true,
   })
   description?: string | null;
 
-  @ApiProperty({ example: "2026-06-01T10:30:00.000Z", format: "date-time" })
+  @ApiProperty({ example: '2026-06-01T10:30:00.000Z', format: 'date-time' })
   createdAt!: string;
 }
 
 export class RoutePermissionResponseDto {
-  @ApiProperty({ example: "GET" })
+  @ApiProperty({ example: 'GET' })
   method!: string;
 
-  @ApiProperty({ example: "/organisations/:orgId/memberships" })
+  @ApiProperty({ example: '/organisations/:orgId/memberships' })
   path!: string;
 
-  @ApiProperty({ example: ["memberships.read"], type: [String] })
+  @ApiProperty({ example: ['memberships.read'], type: [String] })
   permissions!: string[];
 }
 
 export class RoleResponseDto {
   @ApiProperty({
-    example: "f602c057-04f4-4ef8-8c84-1b7c62fbf8c5",
-    format: "uuid",
+    example: 'f602c057-04f4-4ef8-8c84-1b7c62fbf8c5',
+    format: 'uuid',
   })
   id!: string;
 
   @ApiProperty({
-    example: "2c67399d-670c-4025-a5fd-1ea9a211891e",
-    format: "uuid",
+    example: '2c67399d-670c-4025-a5fd-1ea9a211891e',
+    format: 'uuid',
   })
   orgId!: string;
 
-  @ApiProperty({ example: "Support" })
+  @ApiProperty({ example: 'Support' })
   name!: string;
 
   @ApiPropertyOptional({
-    example: "Can review support-facing records.",
+    example: 'Can review support-facing records.',
     nullable: true,
   })
   description?: string | null;
@@ -71,9 +71,21 @@ export class RoleResponseDto {
   @ApiProperty({ type: [PermissionResponseDto] })
   permissions!: PermissionResponseDto[];
 
-  @ApiProperty({ example: "2026-06-01T10:30:00.000Z", format: "date-time" })
+  @ApiProperty({ example: '2026-06-01T10:30:00.000Z', format: 'date-time' })
   createdAt!: string;
 
-  @ApiProperty({ example: "2026-06-01T10:30:00.000Z", format: "date-time" })
+  @ApiProperty({ example: '2026-06-01T10:30:00.000Z', format: 'date-time' })
   updatedAt!: string;
 }
+
+export class RoleListResponseDto {
+  @ApiProperty({ type: [RoleResponseDto] })
+  items!: RoleResponseDto[];
+
+  @ApiPropertyOptional({
+    example: 'f602c057-04f4-4ef8-8c84-1b7c62fbf8c5',
+    format: 'uuid',
+    nullable: true,
+  })
+  nextCursor!: string | null;
+}

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

@@ -1,16 +1,16 @@
-import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
-import { Transform } from "class-transformer";
-import { IsOptional, IsString, MaxLength, MinLength } from "class-validator";
+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))
+  @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." })
+  @ApiPropertyOptional({ example: 'Can review support-facing records.' })
   @IsOptional()
   @IsString()
   @MaxLength(240)

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

@@ -0,0 +1,31 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { PermissionKey, permissionKeys } from '../types/permission-key';
+
+export class CurrentAccessControlResponseDto {
+  @ApiProperty({
+    example: '2c67399d-670c-4025-a5fd-1ea9a211891e',
+    format: 'uuid',
+  })
+  orgId!: string;
+
+  @ApiProperty({
+    example: '0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3',
+    format: 'uuid',
+  })
+  membershipId!: string;
+
+  @ApiProperty({
+    example: 'f602c057-04f4-4ef8-8c84-1b7c62fbf8c5',
+    format: 'uuid',
+  })
+  roleId!: string;
+
+  @ApiProperty({ example: true })
+  isOwner!: boolean;
+
+  @ApiProperty({ example: true })
+  isBillingContact!: boolean;
+
+  @ApiProperty({ enum: permissionKeys, example: ['organisations.read', 'settings.read'] })
+  permissionKeys!: PermissionKey[];
+}

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

@@ -1,16 +1,9 @@
-import { ApiProperty } from "@nestjs/swagger";
-import {
-  ArrayMaxSize,
-  ArrayUnique,
-  IsArray,
-  IsString,
-  Matches,
-  MaxLength,
-} from "class-validator";
+import { ApiProperty } from '@nestjs/swagger';
+import { ArrayMaxSize, ArrayUnique, IsArray, IsString, Matches, MaxLength } from 'class-validator';
 
 export class UpdateRolePermissionsDto {
   @ApiProperty({
-    example: ["memberships.read", "settings.read"],
+    example: ['memberships.read', 'settings.read'],
     isArray: true,
   })
   @IsArray()

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

@@ -1,17 +1,17 @@
-import { ApiPropertyOptional } from "@nestjs/swagger";
-import { Transform } from "class-transformer";
-import { IsOptional, IsString, MaxLength, MinLength } from "class-validator";
+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" })
+  @ApiPropertyOptional({ example: 'Support Lead' })
   @IsOptional()
-  @Transform(({ value }) => (typeof value === "string" ? value.trim() : value))
+  @Transform(({ value }) => (typeof value === 'string' ? value.trim() : value))
   @IsString()
   @MinLength(2)
   @MaxLength(80)
   name?: string;
 
-  @ApiPropertyOptional({ example: "Can manage support-facing records." })
+  @ApiPropertyOptional({ example: 'Can manage support-facing records.' })
   @IsOptional()
   @IsString()
   @MaxLength(240)