{"_id":"@bvhoach2393/nest-check-uma","name":"@bvhoach2393/nest-check-uma","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.1":{"name":"@bvhoach2393/nest-check-uma","version":"1.0.1","description":"NestJS library for UMA (User Managed Access) permission checking","main":"dist/index.js","types":"dist/index.d.ts","author":{"name":"bvhoach2393"},"license":"MIT","keywords":["nestjs","uma","permission","authorization","access-control"],"scripts":{"build":"tsc","test":"jest","test:watch":"jest --watch","test:cov":"jest --coverage"},"peerDependencies":{"@nestjs/common":"^11.0.0","@nestjs/config":"^4.0.0","@nestjs/core":"^11.0.0","reflect-metadata":"^0.2.0","rxjs":"^7.8.0"},"dependencies":{"@types/express":"^5.0.0"},"devDependencies":{"@nestjs/testing":"^11.0.0","@types/jest":"^30.0.0","@types/node":"^24.0.0","jest":"^30.0.0","ts-jest":"^29.0.0","typescript":"^5.0.0"},"jest":{"moduleFileExtensions":["js","json","ts"],"rootDir":"src","testRegex":".*\\.spec\\.ts$","transform":{"^.+\\.(t|j)s$":"ts-jest"},"collectCoverageFrom":["**/*.(t|j)s"],"coverageDirectory":"../coverage","testEnvironment":"node"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/bvhoach2393/common-lib.git","directory":"libs/nest-check-uma"},"bugs":{"url":"https://github.com/bvhoach2393/common-lib/issues"},"homepage":"https://github.com/bvhoach2393/common-lib#readme","_id":"@bvhoach2393/nest-check-uma@1.0.1","gitHead":"3cf9709bae0f25abf14c6e2824c117fc6e713e0a","_nodeVersion":"24.5.0","_npmVersion":"11.5.1","dist":{"integrity":"sha512-ormphl8NhvaP90K5Wd1ZdM4VZUxyATpyaWvgr+uua5mM+jdrjpA+a9SbM32fhbVEoalbJObzBaeWYQjUkt8u+A==","shasum":"ec33571d8b7bfb583a055a224235eb8547e161d6","tarball":"https://registry.npmjs.org/@bvhoach2393/nest-check-uma/-/nest-check-uma-1.0.1.tgz","fileCount":22,"unpackedSize":209616,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD5Gy4MH0TIFs/ldKHUQG74jrvqUD043bzGKkDYv0xZkgIgWBJHnOkU9XVkaB6h4iBJxyWDp67Toa79Zh6clQKcreg="}]},"_npmUser":{"name":"bvhoach2393","email":"bvhoach2393@gmail.com"},"directories":{},"maintainers":[{"name":"bvhoach2393","email":"bvhoach2393@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/nest-check-uma_1.0.1_1757531596941_0.9126387861547183"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-10T19:13:16.838Z","1.0.1":"2025-09-10T19:13:17.166Z","modified":"2025-09-10T19:13:17.459Z"},"maintainers":[{"name":"bvhoach2393","email":"bvhoach2393@gmail.com"}],"description":"NestJS library for UMA (User Managed Access) permission checking","homepage":"https://github.com/bvhoach2393/common-lib#readme","keywords":["nestjs","uma","permission","authorization","access-control"],"repository":{"type":"git","url":"git+https://github.com/bvhoach2393/common-lib.git","directory":"libs/nest-check-uma"},"author":{"name":"bvhoach2393"},"bugs":{"url":"https://github.com/bvhoach2393/common-lib/issues"},"license":"MIT","readme":"# @bvhoach2393/nest-check-uma\n\nNestJS library for UMA (User Managed Access) permission checking\n\n## Description\n\nLibrary `nest-check-uma` được sử dụng để thực hiện việc kiểm tra quyền UMA trước khi thực hiện các hành động khác trong ứng dụng NestJS. Library hỗ trợ việc kiểm tra Authorization header, lấy thông tin environment và gọi API UMA để xác thực quyền truy cập.\n\n## Features\n\n- ✅ **Decorator Pattern**: Sử dụng `@UmaCheck(resource, scope)` decorator để bảo vệ endpoints\n- ✅ **Global Guard**: Tự động kiểm tra UMA cho tất cả endpoints có decorator\n- ✅ **Authorization Header**: Kiểm tra và xử lý Bearer token\n- ✅ **Environment Configuration**: UMA_URL và UMA_REALM từ environment variables\n- ✅ **UMA API Integration**: Gọi API UMA để kiểm tra quyền truy cập\n- ✅ **Error Handling**: Xử lý lỗi và trả về ForbiddenException chuẩn NestJS\n- ✅ **Logging**: Chi tiết log cho việc debug\n- ✅ **TypeScript Support**: Interfaces và types đầy đủ\n- ✅ **Flexible Usage**: Cả decorator và manual service injection\n\n## Installation\n\n### NPM\n```bash\nnpm install @bvhoach2393/nest-check-uma\n```\n\n### Yarn\n```bash\nyarn add @bvhoach2393/nest-check-uma\n```\n\n### Peer Dependencies\n\nLibrary này yêu cầu các peer dependencies sau:\n\n```bash\nnpm install @nestjs/common @nestjs/config @nestjs/core reflect-metadata rxjs\n```\n\n## Environment Variables\n\nTrước khi sử dụng library, bạn cần cấu hình các environment variables sau:\n\n```env\nUMA_URL=https://your-uma-server.com\nUMA_REALM=your-realm-name\nUMA_AUDIENCE=your-audience-name\n```\n\n## Usage\n\n### 1. Import Module\n\n```typescript\nimport { Module } from '@nestjs/common';\nimport { ConfigModule } from '@nestjs/config';\nimport { NestCheckUmaModule } from '@bvhoach2393/nest-check-uma';\n\n@Module({\n  imports: [\n    ConfigModule.forRoot({\n      isGlobal: true,\n    }),\n    NestCheckUmaModule,\n  ],\n})\nexport class AppModule {}\n```\n\n### 2. Using UMA Decorator (Recommended)\n\nThe easiest way to protect your endpoints is using the `@UmaCheck` decorator:\n\n```typescript\nimport { Controller, Get } from '@nestjs/common';\nimport { UmaCheck } from '@bvhoach2393/nest-check-uma';\n\n@Controller('protected')\nexport class ProtectedController {\n  \n  @Get('users')\n  @UmaCheck('user-data', 'read')  // resource, scope\n  async getUsers() {\n    // Logic được bảo vệ bởi UMA\n    // Guard sẽ tự động kiểm tra quyền trước khi vào method này\n    return { users: ['user1', 'user2'] };\n  }\n\n  @Get('admin')\n  @UmaCheck('admin-panel', 'write')\n  async adminAction() {\n    return { message: 'Admin action performed' };\n  }\n\n  @Get('public')\n  // Không có @UmaCheck decorator = endpoint công khai\n  async publicData() {\n    return { message: 'This is public data' };\n  }\n}\n```\n\n### 3. Manual Service Usage\n\nBạn cũng có thể sử dụng service trực tiếp:\n\n```typescript\nimport { Injectable } from '@nestjs/common';\nimport { NestCheckUmaService } from '@bvhoach2393/nest-check-uma';\n\n@Injectable()\nexport class YourService {\n  constructor(private readonly umaService: NestCheckUmaService) {}\n\n  async performAction(authorizationHeader: string) {\n    const hasPermission = await this.umaService.hasPermission(\n      'resource-name', \n      'scope-name', \n      authorizationHeader\n    );\n\n    if (!hasPermission) {\n      throw new Error('Access denied');\n    }\n\n    // Thực hiện hành động khi có quyền\n    return 'Action performed successfully';\n  }\n}\n```\n\n### 4. Advanced Controller Usage\n\n```typescript\nimport { Controller, Get, Headers } from '@nestjs/common';\nimport { NestCheckUmaService, UmaCheckResponse } from '@bvhoach2393/nest-check-uma';\n\n@Controller('advanced')\nexport class AdvancedController {\n  constructor(private readonly umaService: NestCheckUmaService) {}\n\n  @Get('manual-check')\n  async manualCheck(@Headers('authorization') authHeader: string) {\n    const checkResult: UmaCheckResponse = await this.umaService.checkUmaPermission({\n      resource: 'protected-data',\n      scope: 'read',\n      authorizationHeader: authHeader\n    });\n\n    if (!checkResult.hasAccess) {\n      return { error: checkResult.message };\n    }\n\n    return { data: 'This is protected data' };\n  }\n}\n```\n\n## API Reference\n\n### Decorator\n\n#### @UmaCheck(resource: string, scope: string)\nDecorator để bảo vệ endpoints với UMA authorization.\n\n```typescript\n@UmaCheck('user-data', 'read')\n@Get('/users')\nasync getUsers() {\n  // Endpoint được bảo vệ\n}\n```\n\n**Parameters:**\n- `resource` (string): Tên tài nguyên cần kiểm tra quyền\n- `scope` (string): Phạm vi quyền (read, write, delete, etc.)\n\n**Behavior:**\n- Tự động kiểm tra Authorization header\n- Gọi UMA API để xác thực quyền\n- Throw `ForbiddenException` nếu không có quyền\n- Cho phép request tiếp tục nếu có quyền\n\n### Guard\n\n#### UmaGuard\nGlobal guard được tự động áp dụng cho tất cả endpoints có `@UmaCheck` decorator.\n\n**Features:**\n- Reflection metadata để lấy thông tin resource/scope\n- Tự động inject và sử dụng NestCheckUmaService\n- Standard NestJS exception handling\n\n### Service\n\n#### NestCheckUmaService\n\n**Methods:**\n\n##### checkUmaPermission(params: UmaCheckParams): Promise<UmaCheckResponse>\nPhương thức chính để kiểm tra quyền UMA với các tham số chi tiết.\n\n##### hasPermission(resource: string, scope: string, authorizationHeader?: string): Promise<boolean>\nPhương thức helper trả về boolean đơn giản để kiểm tra quyền.\n\n### Interfaces\n\n#### UmaCheckParams\n```typescript\ninterface UmaCheckParams {\n  resource: string;           // Tên tài nguyên cần kiểm tra\n  scope: string;             // Phạm vi quyền (read, write, delete, etc.)\n  authorizationHeader?: string; // Header Authorization với Bearer token\n}\n```\n\n#### UmaCheckResponse\n```typescript\ninterface UmaCheckResponse {\n  hasAccess: boolean;        // Kết quả kiểm tra quyền\n  message?: string;          // Thông báo chi tiết\n}\n```\n\n#### UmaCheckMetadata\n```typescript\ninterface UmaCheckMetadata {\n  resource: string;          // Resource từ decorator\n  scope: string;             // Scope từ decorator\n}\n```\n\n## Testing\n\n### Unit Tests\n\n```bash\nnpm run test\n```\n\n### Test Coverage\n\n```bash\nnpm run test:cov\n```\n\n### Watch Mode\n\n```bash\nnpm run test:watch\n```\n\n## UMA API Integration\n\nLibrary gọi đến endpoint UMA với format:\n```\nPOST {{UMA_URL}}/auth/uma-check\n```\n\nRequest body:\n```json\n{\n  \"realm\": \"{{UMA_REALM}}\",\n  \"token\": \"user-token-from-authorization-header\",\n  \"audience\": \"{{UMA_REALM}}\",\n  \"resource\": \"resource-name\",\n  \"scope\": \"scope-name\"\n}\n```\n\nResponse:\n```json\ntrue // hoặc false\n```\n\n## Error Handling\n\nLibrary xử lý các lỗi phổ biến:\n\n- ❌ Authorization header không tồn tại\n- ❌ UMA_URL hoặc UMA_REALM không được cấu hình\n- ❌ Token không hợp lệ\n- ❌ Lỗi kết nối đến UMA server\n- ❌ Response không hợp lệ từ UMA API\n\n## Publishing\n\n### Build\n```bash\nnpm run build\n```\n\n### Publish to NPM\n```bash\nnpm publish\n```\n\n## License\n\nMIT\n\n## Author\n\nbvhoach2393\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## Support\n\nFor issues and questions, please create an issue on the GitHub repository.\n","readmeFilename":"README.md","_rev":"1-e2f64a0ee9eaefb7cbc2794d6273814f"}