@ftisindia/create-app 0.1.0

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

@@ -0,0 +1,478 @@
+import {
+  BadRequestException,
+  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";
+
+const roleInclude = {
+  permissions: {
+    include: {
+      permission: true,
+    },
+    orderBy: {
+      permissionId: "asc",
+    },
+  },
+  _count: {
+    select: {
+      memberships: true,
+    },
+  },
+} satisfies Prisma.RoleInclude;
+
+type PrismaClient = Prisma.TransactionClient | PrismaService;
+
+@Injectable()
+export class AccessControlService {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly requestContext: RequestContextService,
+    private readonly rbacCache: RbacCacheService,
+  ) {}
+
+  listPermissions() {
+    return this.prisma.permission.findMany({
+      orderBy: [{ module: "asc" }, { action: "asc" }],
+    });
+  }
+
+  listRoutePermissions() {
+    return routePermissionRegistry;
+  }
+
+  async listRoles(orgId: string) {
+    this.requestContext.assertOrgScope(orgId);
+
+    const roles = await this.prisma.role.findMany({
+      where: { orgId },
+      include: roleInclude,
+      orderBy: [{ isSystemSeeded: "desc" }, { name: "asc" }],
+    });
+
+    return roles.map(serializeRole);
+  }
+
+  async createRole(
+    currentUser: AuthenticatedUser,
+    orgId: string,
+    dto: CreateRoleDto,
+  ) {
+    this.requestContext.assertOrgScope(orgId);
+
+    const name = normalizeRoleName(dto.name);
+    assertValidRoleName(name);
+
+    try {
+      const role = await this.prisma.$transaction(async (tx) => {
+        const created = await tx.role.create({
+          data: {
+            orgId,
+            name,
+            description: normalizeOptionalString(dto.description),
+          },
+          include: roleInclude,
+        });
+
+        await this.writeAudit(tx, {
+          orgId,
+          actorUserId: currentUser.id,
+          action: "role.create",
+          targetId: created.id,
+          metadata: {
+            name: created.name,
+            description: created.description,
+          },
+        });
+
+        return created;
+      });
+
+      return serializeRole(role);
+    } catch (error) {
+      if (isPrismaUniqueError(error)) {
+        throw new ConflictException(
+          "Role name is already in use in this organisation.",
+        );
+      }
+
+      throw error;
+    }
+  }
+
+  async updateRole(
+    currentUser: AuthenticatedUser,
+    orgId: string,
+    roleId: string,
+    dto: UpdateRoleDto,
+  ) {
+    this.requestContext.assertOrgScope(orgId);
+
+    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.",
+      );
+    }
+
+    try {
+      const result = await this.prisma.$transaction(async (tx) => {
+        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
+        ) {
+          const role = await tx.role.findUniqueOrThrow({
+            where: { id: existing.id },
+            include: roleInclude,
+          });
+
+          return { role, changed: false };
+        }
+
+        const updated = await tx.role.update({
+          where: { id: existing.id },
+          data: {
+            name: nextName,
+            description: nextDescription,
+          },
+          include: roleInclude,
+        });
+
+        await this.writeAudit(tx, {
+          orgId,
+          actorUserId: currentUser.id,
+          action: "role.update",
+          targetId: updated.id,
+          metadata: {
+            previousName: existing.name,
+            nextName: updated.name,
+            previousDescription: existing.description,
+            nextDescription: updated.description,
+          },
+        });
+
+        return { role: updated, changed: true };
+      });
+
+      if (result.changed) {
+        await this.rbacCache.invalidateRole(orgId, roleId);
+      }
+
+      return serializeRole(result.role);
+    } catch (error) {
+      if (isPrismaUniqueError(error)) {
+        throw new ConflictException(
+          "Role name is already in use in this organisation.",
+        );
+      }
+
+      throw error;
+    }
+  }
+
+  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.");
+    }
+
+    try {
+      await this.prisma.$transaction(async (tx) => {
+        const membershipCount = await tx.membership.count({
+          where: {
+            orgId,
+            roleId,
+          },
+        });
+        if (membershipCount > 0) {
+          throw new ConflictException(
+            "Role cannot be deleted while memberships still use it.",
+          );
+        }
+
+        const invitationCount = await tx.invitation.count({
+          where: {
+            orgId,
+            roleId,
+          },
+        });
+        if (invitationCount > 0) {
+          throw new ConflictException(
+            "Role cannot be deleted while invitations reference it.",
+          );
+        }
+
+        await tx.rolePermission.deleteMany({
+          where: { roleId },
+        });
+
+        await tx.role.delete({
+          where: { id: roleId },
+        });
+
+        await this.writeAudit(tx, {
+          orgId,
+          actorUserId: currentUser.id,
+          action: "role.delete",
+          targetId: roleId,
+          metadata: {
+            name: existing.name,
+          },
+        });
+      });
+    } catch (error) {
+      if (isPrismaForeignKeyError(error)) {
+        throw new ConflictException(
+          "Role cannot be deleted while other records reference it.",
+        );
+      }
+
+      throw error;
+    }
+
+    await this.rbacCache.invalidateRole(orgId, roleId);
+    return { deleted: true };
+  }
+
+  async listRolePermissions(orgId: string, roleId: string) {
+    this.requestContext.assertOrgScope(orgId);
+
+    const role = await this.prisma.role.findUnique({
+      where: {
+        id_orgId: {
+          id: roleId,
+          orgId,
+        },
+      },
+      include: roleInclude,
+    });
+
+    if (!role) {
+      throw new NotFoundException("Role was not found in this organisation.");
+    }
+
+    return serializeRole(role);
+  }
+
+  async replaceRolePermissions(
+    currentUser: AuthenticatedUser,
+    orgId: string,
+    roleId: string,
+    dto: UpdateRolePermissionsDto,
+  ) {
+    this.requestContext.assertOrgScope(orgId);
+
+    const role = await this.findRoleInOrg(this.prisma, orgId, roleId);
+    const permissionKeys = [...dto.permissionKeys].sort();
+
+    try {
+      const result = await this.prisma.$transaction(async (tx) => {
+        const permissions = await tx.permission.findMany({
+          where: {
+            key: {
+              in: permissionKeys,
+            },
+          },
+          select: {
+            id: true,
+            key: true,
+          },
+        });
+        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(", ")}`,
+          );
+        }
+
+        const previousPermissions = await tx.rolePermission.findMany({
+          where: { roleId },
+          include: { permission: true },
+        });
+        const previousPermissionKeys = previousPermissions
+          .map((rolePermission) => rolePermission.permission.key)
+          .sort();
+
+        if (arraysEqual(previousPermissionKeys, permissionKeys)) {
+          const unchanged = await tx.role.findUniqueOrThrow({
+            where: { id: roleId },
+            include: roleInclude,
+          });
+
+          return { role: unchanged, changed: false };
+        }
+
+        await tx.rolePermission.deleteMany({
+          where: { roleId },
+        });
+
+        if (permissions.length > 0) {
+          await tx.rolePermission.createMany({
+            data: permissions.map((permission) => ({
+              roleId,
+              permissionId: permission.id,
+            })),
+            skipDuplicates: true,
+          });
+        }
+
+        await this.writeAudit(tx, {
+          orgId,
+          actorUserId: currentUser.id,
+          action: "role.permissions.replace",
+          targetId: roleId,
+          metadata: {
+            roleName: role.name,
+            previousPermissionKeys,
+            nextPermissionKeys: permissionKeys,
+          },
+        });
+
+        const updated = await tx.role.findUniqueOrThrow({
+          where: { id: roleId },
+          include: roleInclude,
+        });
+
+        return { role: updated, changed: true };
+      });
+
+      if (result.changed) {
+        await this.rbacCache.invalidateRole(orgId, roleId);
+      }
+
+      return serializeRole(result.role);
+    } catch (error) {
+      if (isPrismaForeignKeyError(error)) {
+        throw new ConflictException(
+          "Role permissions could not be updated because referenced data changed.",
+        );
+      }
+
+      throw error;
+    }
+  }
+
+  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: {
+          id: roleId,
+          orgId,
+        },
+      },
+      include,
+    });
+
+    if (!role) {
+      throw new NotFoundException("Role was not found in this organisation.");
+    }
+
+    return role;
+  }
+
+  private async writeAudit(
+    client: PrismaClient,
+    data: {
+      orgId: string;
+      actorUserId: string;
+      action: string;
+      targetId: string;
+      metadata?: Prisma.InputJsonObject;
+    },
+  ) {
+    await client.auditLog.create({
+      data: {
+        orgId: data.orgId,
+        actorUserId: data.actorUserId,
+        action: data.action,
+        targetType: "Role",
+        targetId: data.targetId,
+        metadata: data.metadata,
+      },
+    });
+  }
+}
+
+function arraysEqual(left: string[], right: string[]) {
+  return (
+    left.length === right.length &&
+    left.every((value, index) => value === right[index])
+  );
+}
+
+function normalizeRoleName(name: string) {
+  return name.trim();
+}
+
+function assertValidRoleName(name: string) {
+  if (name.length < 2) {
+    throw new BadRequestException(
+      "Role name must contain at least 2 non-whitespace characters.",
+    );
+  }
+}
+
+function normalizeOptionalString(value: string | undefined) {
+  const normalized = value?.trim();
+  return normalized || null;
+}
+
+function isPrismaUniqueError(error: unknown) {
+  return (
+    error instanceof Prisma.PrismaClientKnownRequestError &&
+    error.code === "P2002"
+  );
+}
+
+function isPrismaForeignKeyError(error: unknown) {
+  return (
+    error instanceof Prisma.PrismaClientKnownRequestError &&
+    error.code === "P2003"
+  );
+}
+
+function serializeRole(
+  role: Prisma.RoleGetPayload<{ include: typeof roleInclude }>,
+) {
+  return {
+    id: role.id,
+    orgId: role.orgId,
+    name: role.name,
+    description: role.description,
+    isSystemSeeded: role.isSystemSeeded,
+    membershipCount: role._count.memberships,
+    permissions: role.permissions
+      .map((rolePermission) => rolePermission.permission)
+      .sort((a, b) => a.key.localeCompare(b.key)),
+    createdAt: role.createdAt,
+    updatedAt: role.updatedAt,
+  };
+}

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

@@ -0,0 +1,77 @@
+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;
+  params?: Record<string, string | undefined>;
+  rbac?: unknown;
+  user?: AuthenticatedUser;
+};
+
+@Injectable()
+export class PermissionGuard implements CanActivate {
+  constructor(
+    private readonly abilityFactory: AbilityFactory,
+    private readonly reflector: Reflector,
+    private readonly requestContext: RequestContextService,
+    private readonly rbacCache: RbacCacheService,
+  ) {}
+
+  async canActivate(context: ExecutionContext) {
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    if (isPublic) {
+      return true;
+    }
+
+    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.");
+    }
+
+    const request = context.switchToHttp().getRequest<RequestWithUser>();
+    const user = request.user;
+    const orgId = request.orgId ?? request.params?.orgId;
+
+    if (!user || !orgId) {
+      throw new ForbiddenException("Active organisation context is required.");
+    }
+
+    const rbac = await this.rbacCache.getContext(user.id, orgId);
+    const ability = this.abilityFactory.createForContext(rbac);
+
+    const allowed = required.every((permission) => {
+      const { action, subject } = permissionKeyToRule(permission);
+      return ability.can(action, subject);
+    });
+
+    if (!allowed) {
+      throw new ForbiddenException("Required permission is missing.");
+    }
+
+    request.rbac = rbac;
+    this.requestContext.merge({
+      userId: user.id,
+      orgId,
+      rbac,
+    });
+    return true;
+  }
+}

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

@@ -0,0 +1,148 @@
+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;
+  value: RbacContext;
+};
+
+const MAX_CACHE_ENTRIES = 5000;
+
+@Injectable()
+export class RbacCacheService {
+  private readonly cache = new Map<string, CacheEntry>();
+
+  constructor(
+    private readonly config: ConfigService,
+    private readonly prisma: PrismaService,
+  ) {}
+
+  async getContext(userId: string, orgId: string) {
+    const key = this.key(userId, orgId);
+    const cached = this.cache.get(key);
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.value;
+    }
+
+    if (cached) {
+      this.cache.delete(key);
+    }
+    this.sweepExpiredEntries();
+
+    const membership = await this.prisma.membership.findUnique({
+      where: {
+        userId_orgId: {
+          userId,
+          orgId,
+        },
+      },
+      include: {
+        role: {
+          include: {
+            permissions: {
+              include: {
+                permission: true,
+              },
+            },
+          },
+        },
+      },
+    });
+
+    if (!membership || membership.status !== MembershipStatus.ACTIVE) {
+      throw new ForbiddenException(
+        "Active organisation membership is required.",
+      );
+    }
+
+    const value: RbacContext = {
+      cacheKey: key,
+      userId,
+      orgId,
+      membershipId: membership.id,
+      membershipStatus: membership.status,
+      roleId: membership.roleId,
+      isOwner: membership.isOwner,
+      isBillingContact: membership.isBillingContact,
+      permissionKeys: membership.role.permissions.map(
+        (rolePermission) => rolePermission.permission.key,
+      ),
+    };
+
+    this.cache.set(key, {
+      value,
+      expiresAt: Date.now() + this.ttlMs(),
+    });
+    this.enforceEntryLimit();
+
+    return value;
+  }
+
+  key(userId: string, orgId: string) {
+    return `rbac:${userId}:${orgId}`;
+  }
+
+  invalidate(userId: string, orgId: string) {
+    this.cache.delete(this.key(userId, orgId));
+  }
+
+  invalidateMany(items: Array<{ userId: string; orgId: string }>) {
+    for (const item of items) {
+      this.invalidate(item.userId, item.orgId);
+    }
+  }
+
+  async invalidateRole(orgId: string, roleId: string) {
+    const memberships = await this.prisma.membership.findMany({
+      where: {
+        orgId,
+        roleId,
+      },
+      select: {
+        userId: true,
+        orgId: true,
+      },
+    });
+
+    this.invalidateMany(memberships);
+  }
+
+  async invalidateOrg(orgId: string) {
+    const memberships = await this.prisma.membership.findMany({
+      where: { orgId },
+      select: {
+        userId: true,
+        orgId: true,
+      },
+    });
+
+    this.invalidateMany(memberships);
+  }
+
+  private ttlMs() {
+    return (this.config.get<number>("rbac.cacheTtlSeconds") ?? 60) * 1000;
+  }
+
+  private sweepExpiredEntries() {
+    const now = Date.now();
+    for (const [key, entry] of this.cache) {
+      if (entry.expiresAt <= now) {
+        this.cache.delete(key);
+      }
+    }
+  }
+
+  private enforceEntryLimit() {
+    while (this.cache.size > MAX_CACHE_ENTRIES) {
+      const oldestKey = this.cache.keys().next().value as string | undefined;
+      if (!oldestKey) {
+        return;
+      }
+
+      this.cache.delete(oldestKey);
+    }
+  }
+}