@elchinabilov/nestjs-ownership

A dynamic, recursive branch-based access control module for NestJS.

Installation

npm install @elchinabilov/nestjs-ownership

Nə edir?

Bu modul entitilərdə filial/şöbə (branch) əsaslı sahibliyi məcburi edir. İstifadəçi yalnız özünün aid olduğu branchId-ə sahib olan resurslara daxil ola bilir. Admin rollar üçün bypass var.

Tez başlanğıc

1. Modulu layihənizə qoşun (asinxron konfiqurasiya ilə):

// app.module.ts
import { Module } from "@nestjs/common";
import { TypeOrmModule, getDataSourceToken } from "@nestjs/typeorm";
import { OwnershipModule } from "@elchinabilov/nestjs-ownership";
import { DataSource } from "typeorm";

@Module({
  imports: [
    TypeOrmModule.forRoot({
      /* ... */
    }),
    OwnershipModule.forRootAsync({
      imports: [
        TypeOrmModule.forRoot({
          /* ... */
        }),
      ],
      inject: [getDataSourceToken()],
      useFactory: async (dataSource: DataSource) => ({
        dataSource,
        // İstədiyiniz qədər entity üçün xəritə
        map: {
          // Açarı entity adı və ya cədvəl adı ola bilər (bax: OwnershipService.getRepositoryByName)
          menu: {
            // entity-dən branch-a gedən əlaqələr zənciri
            // məsələn: Menu -> Restaurant -> Branch
            path: ["restaurant", "branch"],
            // route param-ın adı (default: "id")
            idParam: "id",
          },
        },
        // İstifadəçinin rolunun saxlandığı sahə (req.user[roleField])
        roleField: "role",
        // Sahibliyin müqayisə olunduğu sahə ( həm user, həm də owner obyektində )
        ownershipField: "branchId",
        // Admin rollar (tam bypass)
        adminRoles: ["admin"],
      }),
    }),
  ],
})
export class AppModule {}

2. Kontroller və ya metod səviyyəsində dekoratorla entity-ni qeyd edin:

import { Controller, Get, Param, UseGuards } from "@nestjs/common";
import { Ownership, OwnershipGuard } from "@elchinabilov/nestjs-ownership";

@Controller("menus")
@Ownership("menu") // bütün metodlara şamil olunur
@UseGuards(OwnershipGuard)
export class MenuController {
  @Get(":id")
  // İstəsəniz metod səviyyəsində də təyin edə bilərsiniz, idParam-ı override etmək mümkündür
  @Ownership("menu", { idParam: "id" })
  findOne(@Param("id") id: string) {
    // ...
  }
}

3. İstifadəçinin branchId və role məlumatı request.user daxilində olmalıdır.

Necə işləyir?

• Guard request.user içindəki roleField əsasında admin olub-olmadığını yoxlayır. Adminlər üçün bypass edilir.
• Dekoratordan oxunan entityKey və idParam əsasında resursun id-si params/body/query üzərindən götürülür.
• OwnershipService.loadOwnerThroughPath TypeORM vasitəsilə xəritədə verilmiş path üzrə LEFT JOIN edərək resursun sahibini (ownerObj) çıxarır.
• ownerObj[ownershipField] ilə user[ownershipField] müqayisə olunur. Uyğun deyilsə 403 Forbidden atılır.
• id verilməyən sorğular (məs: siyahı və ya create) guard tərəfindən buraxılır.

Konfiqurasiya parametrləri

• dataSource: DataSource — TypeORM DataSource obyekti (mütləq)
• map: OwnershipMap — entity -> { path, idParam } xəritəsi (mütləq)
• roleField?: string — istifadəçi rol sahəsi; default: "role"
• ownershipField?: string — müqayisə sahəsi; default: "branchId"
• adminRoles?: string[] — admin rollar; default: ["admin"]

OwnershipMap tipi:

type OwnershipMap = Record<
  string,
  {
    path?: string[]; // entity-dən branch-a gedən əlaqələr
    idParam?: string; // route param (default: "id")
  }
>;

Qeydlər

• Modul @Global() olduğu üçün OwnershipGuard qlobal qeydiyyatla gəlir; lakin istəsəniz kontroller səviyyəsində də @UseGuards(OwnershipGuard) ilə tətbiq edə bilərsiniz.
• Entity açarı olaraq həm entity adı, həm də cədvəl adı istifadə edilə bilər. Daxildə metadata ilə uyğunluq yoxlanılır.
• src/common/ownership.map.ts faylı geriyə uyğunluq üçün mövcuddur və tipləri src/common/interfaces.ts ilə eyni xəttə gətirilmişdir.

Lisenzya

ISC