@ftisindia/create-app 0.1.0

package/template/src/modules/access-control/application/route-registry.validator.ts

@@ -0,0 +1,289 @@
+import {
+  Injectable,
+  OnApplicationBootstrap,
+  RequestMethod,
+} from "@nestjs/common";
+import { METHOD_METADATA, PATH_METADATA } from "@nestjs/common/constants";
+import { DiscoveryService, MetadataScanner, Reflector } from "@nestjs/core";
+import { REQUIRED_PERMISSIONS_KEY } from "../presentation/permissions.decorator";
+import {
+  PermissionKey,
+  permissionKeys,
+  RoutePermissionEntry,
+} from "../types/permission-key";
+import { routePermissionRegistry } from "../types/route-permission-registry";
+
+type ControllerInstance = Record<string, unknown>;
+type RouteHandler = (...args: unknown[]) => unknown;
+type RoutePermissionDiff = {
+  key: string;
+  registryPermissions: PermissionKey[];
+  enforcedPermissions: PermissionKey[];
+};
+
+@Injectable()
+export class RouteRegistryValidator implements OnApplicationBootstrap {
+  constructor(
+    private readonly discovery: DiscoveryService,
+    private readonly metadataScanner: MetadataScanner,
+    private readonly reflector: Reflector,
+  ) {}
+
+  onApplicationBootstrap() {
+    const enforcedRoutes = this.discoverPermissionRoutes();
+    const registryRoutes = routePermissionRegistry.map(normalizeEntry);
+
+    const enforcedByRoute = mapByRoute(
+      enforcedRoutes,
+      "enforced route metadata",
+    );
+    const registryByRoute = mapByRoute(
+      registryRoutes,
+      "routePermissionRegistry",
+    );
+    const missingFromRegistry = enforcedRoutes.filter(
+      (entry) => !registryByRoute.has(routeKey(entry)),
+    );
+    const staleRegistryEntries = registryRoutes.filter(
+      (entry) => !enforcedByRoute.has(routeKey(entry)),
+    );
+    const permissionMismatches = collectPermissionMismatches(
+      registryByRoute,
+      enforcedByRoute,
+    );
+    const unknownPermissions = collectUnknownPermissions([
+      ...registryRoutes,
+      ...enforcedRoutes,
+    ]);
+
+    if (
+      missingFromRegistry.length > 0 ||
+      staleRegistryEntries.length > 0 ||
+      permissionMismatches.length > 0 ||
+      unknownPermissions.length > 0
+    ) {
+      throw new Error(
+        formatRegistryDriftError({
+          missingFromRegistry,
+          staleRegistryEntries,
+          permissionMismatches,
+          unknownPermissions,
+        }),
+      );
+    }
+  }
+
+  private discoverPermissionRoutes() {
+    const entries: RoutePermissionEntry[] = [];
+
+    for (const wrapper of this.discovery.getControllers()) {
+      const instance = wrapper.instance as ControllerInstance | undefined;
+      const metatype = wrapper.metatype;
+      if (!instance || !metatype) {
+        continue;
+      }
+
+      const controllerPaths = toPathParts(
+        this.reflector.get(PATH_METADATA, metatype),
+      );
+      const prototype = Object.getPrototypeOf(instance) as object | null;
+
+      for (const methodName of this.metadataScanner.getAllMethodNames(
+        prototype,
+      )) {
+        const handler = instance[methodName];
+        if (typeof handler !== "function") {
+          continue;
+        }
+
+        const requestMethod = this.reflector.get<RequestMethod | undefined>(
+          METHOD_METADATA,
+          handler,
+        );
+        if (requestMethod === undefined) {
+          continue;
+        }
+
+        const permissions = this.reflector.getAllAndOverride<PermissionKey[]>(
+          REQUIRED_PERMISSIONS_KEY,
+          [handler as RouteHandler, metatype],
+        );
+        if (!permissions || permissions.length === 0) {
+          continue;
+        }
+
+        const methodPaths = toPathParts(
+          this.reflector.get(PATH_METADATA, handler),
+        );
+        for (const path of combinePaths(controllerPaths, methodPaths)) {
+          entries.push(
+            normalizeEntry({
+              method: requestMethodToString(requestMethod),
+              path,
+              permissions,
+            }),
+          );
+        }
+      }
+    }
+
+    return entries;
+  }
+}
+
+function collectPermissionMismatches(
+  registryByRoute: Map<string, RoutePermissionEntry>,
+  enforcedByRoute: Map<string, RoutePermissionEntry>,
+) {
+  const mismatches: RoutePermissionDiff[] = [];
+
+  for (const [key, enforced] of enforcedByRoute) {
+    const registered = registryByRoute.get(key);
+    if (!registered) {
+      continue;
+    }
+
+    if (
+      permissionListKey(registered.permissions) !==
+      permissionListKey(enforced.permissions)
+    ) {
+      mismatches.push({
+        key,
+        registryPermissions: registered.permissions,
+        enforcedPermissions: enforced.permissions,
+      });
+    }
+  }
+
+  return mismatches;
+}
+
+function collectUnknownPermissions(entries: RoutePermissionEntry[]) {
+  const known = new Set<string>(permissionKeys);
+  return [...new Set(entries.flatMap((entry) => entry.permissions))].filter(
+    (permission) => !known.has(permission),
+  );
+}
+
+function formatRegistryDriftError({
+  missingFromRegistry,
+  staleRegistryEntries,
+  permissionMismatches,
+  unknownPermissions,
+}: {
+  missingFromRegistry: RoutePermissionEntry[];
+  staleRegistryEntries: RoutePermissionEntry[];
+  permissionMismatches: RoutePermissionDiff[];
+  unknownPermissions: string[];
+}) {
+  const sections = ["Route permission registry drift detected."];
+
+  if (missingFromRegistry.length > 0) {
+    sections.push(
+      [
+        "Permission-gated routes missing from routePermissionRegistry:",
+        ...missingFromRegistry.map(formatEntry),
+      ].join("\n"),
+    );
+  }
+
+  if (staleRegistryEntries.length > 0) {
+    sections.push(
+      [
+        "routePermissionRegistry entries without matching permission-gated routes:",
+        ...staleRegistryEntries.map(formatEntry),
+      ].join("\n"),
+    );
+  }
+
+  if (permissionMismatches.length > 0) {
+    sections.push(
+      [
+        "routePermissionRegistry permission mismatches:",
+        ...permissionMismatches.map(
+          (diff) =>
+            `- ${diff.key}: registry [${diff.registryPermissions.join(", ")}], enforced [${diff.enforcedPermissions.join(", ")}]`,
+        ),
+      ].join("\n"),
+    );
+  }
+
+  if (unknownPermissions.length > 0) {
+    sections.push(
+      [
+        "Unknown permission keys referenced by guarded routes or routePermissionRegistry:",
+        ...unknownPermissions.map((permission) => `- ${permission}`),
+      ].join("\n"),
+    );
+  }
+
+  return sections.join("\n\n");
+}
+
+function mapByRoute(entries: RoutePermissionEntry[], source: string) {
+  const byRoute = new Map<string, RoutePermissionEntry>();
+
+  for (const entry of entries) {
+    const key = routeKey(entry);
+    if (byRoute.has(key)) {
+      throw new Error(`Duplicate ${source} entry for ${key}.`);
+    }
+
+    byRoute.set(key, entry);
+  }
+
+  return byRoute;
+}
+
+function normalizeEntry(entry: RoutePermissionEntry): RoutePermissionEntry {
+  return {
+    method: entry.method.toUpperCase(),
+    path: normalizePath(entry.path),
+    permissions: [...new Set(entry.permissions)].sort(),
+  };
+}
+
+function combinePaths(controllerPaths: string[], methodPaths: string[]) {
+  const paths: string[] = [];
+
+  for (const controllerPath of controllerPaths) {
+    for (const methodPath of methodPaths) {
+      paths.push(normalizePath([controllerPath, methodPath].join("/")));
+    }
+  }
+
+  return paths;
+}
+
+function toPathParts(metadata: string | string[] | undefined) {
+  if (Array.isArray(metadata)) {
+    return metadata.length > 0 ? metadata : [""];
+  }
+
+  return [metadata ?? ""];
+}
+
+function normalizePath(path: string) {
+  const trimmed = path
+    .split("/")
+    .filter((part) => part.length > 0)
+    .join("/");
+
+  return trimmed ? `/${trimmed}` : "/";
+}
+
+function requestMethodToString(method: RequestMethod) {
+  return RequestMethod[method];
+}
+
+function routeKey(entry: RoutePermissionEntry) {
+  return `${entry.method} ${entry.path}`;
+}
+
+function permissionListKey(permissions: PermissionKey[]) {
+  return permissions.join("\0");
+}
+
+function formatEntry(entry: RoutePermissionEntry) {
+  return `- ${routeKey(entry)} -> [${entry.permissions.join(", ")}]`;
+}

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

@@ -0,0 +1,28 @@
+import {
+  AbilityBuilder,
+  createMongoAbility,
+  MongoAbility,
+} from "@casl/ability";
+import { Injectable } from "@nestjs/common";
+import { permissionKeyToRule } from "../../types/permission-key";
+import { RbacContext } from "../../types/rbac-context";
+
+export type AppAbility = MongoAbility<[string, string]>;
+
+@Injectable()
+export class AbilityFactory {
+  createForContext(context: RbacContext): AppAbility {
+    const { can, build } = new AbilityBuilder<AppAbility>(createMongoAbility);
+
+    if (context.isOwner) {
+      can("manage", "all");
+    }
+
+    for (const key of context.permissionKeys) {
+      const { action, subject } = permissionKeyToRule(key);
+      can(action, subject);
+    }
+
+    return build();
+  }
+}