@open-kingdom/shared-backend-util-rbac 0.0.2-17

package/README.md

@@ -0,0 +1,41 @@
+# @open-kingdom/shared-backend-util-rbac
+
+Decorators, guards, and tokens for role-based access control in NestJS.
+
+## Setup
+
+Register both guards globally in `AppModule`. `JwtAuthGuard` must run first to populate `req.user`.
+
+```typescript
+import { APP_GUARD } from '@nestjs/core';
+import { JwtAuthGuard } from '@open-kingdom/shared-backend-feature-authentication';
+import { PermissionGuard, ROLE_RESOLVER } from '@open-kingdom/shared-backend-util-rbac';
+import { UserRolesService } from '@open-kingdom/shared-backend-feature-user-management';
+
+providers: [
+  { provide: APP_GUARD, useClass: JwtAuthGuard },
+  { provide: APP_GUARD, useClass: PermissionGuard },
+  { provide: ROLE_RESOLVER, useExisting: UserRolesService },
+];
+```
+
+## Usage
+
+```typescript
+import { Public, RequirePermission } from '@open-kingdom/shared-backend-util-rbac';
+
+@Controller('users')
+export class UsersController {
+  @Public()
+  @Post('login')
+  login() { ... }
+
+  @RequirePermission('users', 'read')
+  @Get()
+  findAll() { ... }
+}
+```
+
+`@Public()` bypasses both JWT auth and permission checks. It takes precedence over `@RequirePermission()`.
+
+Permissions are checked against the database on every request via `ROLE_RESOLVER.findPermissions(userId)` — not from the JWT.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { RequirePermission, REQUIRED_PERMISSION_KEY, } from './lib/decorators/require-permission.decorator.js';
+export { Public, IS_PUBLIC_KEY } from './lib/decorators/public.decorator.js';
+export { PermissionGuard } from './lib/guards/permission.guard.js';
+export { ROLE_RESOLVER } from './lib/role-resolver.js';
+export type { RoleResolver } from './lib/role-resolver.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { RequirePermission, REQUIRED_PERMISSION_KEY, } from './lib/decorators/require-permission.decorator.js';
+export { Public, IS_PUBLIC_KEY } from './lib/decorators/public.decorator.js';
+export { PermissionGuard } from './lib/guards/permission.guard.js';
+export { ROLE_RESOLVER } from './lib/role-resolver.js';

package/dist/lib/decorators/public.decorator.d.ts

@@ -0,0 +1,3 @@
+export declare const IS_PUBLIC_KEY = "isPublic";
+export declare const Public: () => import("@nestjs/common").CustomDecorator<string>;
+//# sourceMappingURL=public.decorator.d.ts.map

package/dist/lib/decorators/public.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.decorator.d.ts","sourceRoot":"","sources":["../../../src/lib/decorators/public.decorator.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,eAAO,MAAM,MAAM,wDAAyC,CAAC"}

package/dist/lib/decorators/public.decorator.js

@@ -0,0 +1,3 @@
+import { SetMetadata } from '@nestjs/common';
+export const IS_PUBLIC_KEY = 'isPublic';
+export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

package/dist/lib/decorators/require-permission.decorator.d.ts

@@ -0,0 +1,3 @@
+export declare const REQUIRED_PERMISSION_KEY = "requiredPermission";
+export declare const RequirePermission: (resource: string, action: string) => import("@nestjs/common").CustomDecorator<string>;
+//# sourceMappingURL=require-permission.decorator.d.ts.map

package/dist/lib/decorators/require-permission.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-permission.decorator.d.ts","sourceRoot":"","sources":["../../../src/lib/decorators/require-permission.decorator.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAE5D,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,EAAE,QAAQ,MAAM,qDACH,CAAC"}

package/dist/lib/decorators/require-permission.decorator.js

@@ -0,0 +1,3 @@
+import { SetMetadata } from '@nestjs/common';
+export const REQUIRED_PERMISSION_KEY = 'requiredPermission';
+export const RequirePermission = (resource, action) => SetMetadata(REQUIRED_PERMISSION_KEY, `${resource}:${action}`);

package/dist/lib/guards/permission.guard.d.ts

@@ -0,0 +1,12 @@
+import { CanActivate, ExecutionContext, OnModuleInit } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import type { RoleResolver } from '../role-resolver.js';
+export declare class PermissionGuard implements CanActivate, OnModuleInit {
+    private readonly reflector;
+    private readonly roleResolver?;
+    private resolvedRoleResolver;
+    constructor(reflector: Reflector, roleResolver?: RoleResolver | undefined);
+    onModuleInit(): void;
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+//# sourceMappingURL=permission.guard.d.ts.map

package/dist/lib/guards/permission.guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.guard.d.ts","sourceRoot":"","sources":["../../../src/lib/guards/permission.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,gBAAgB,EAIhB,YAAY,EAGb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAKzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,qBACa,eAAgB,YAAW,WAAW,EAAE,YAAY;IAI7D,OAAO,CAAC,QAAQ,CAAC,SAAS;IAG1B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IANhC,OAAO,CAAC,oBAAoB,CAAgB;gBAGzB,SAAS,EAAE,SAAS,EAGpB,YAAY,CAAC,EAAE,YAAY,YAAA;IAG9C,YAAY;IAUN,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;CAgC/D"}

package/dist/lib/guards/permission.guard.js

@@ -0,0 +1,49 @@
+import { __decorate, __metadata, __param } from "tslib";
+import { ForbiddenException, Inject, Injectable, Optional, UnauthorizedException, } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { IS_PUBLIC_KEY } from '../decorators/public.decorator.js';
+import { REQUIRED_PERMISSION_KEY } from '../decorators/require-permission.decorator.js';
+import { ROLE_RESOLVER } from '../role-resolver.js';
+let PermissionGuard = class PermissionGuard {
+    constructor(reflector, roleResolver) {
+        this.reflector = reflector;
+        this.roleResolver = roleResolver;
+    }
+    onModuleInit() {
+        if (!this.roleResolver) {
+            throw new Error('PermissionGuard requires ROLE_RESOLVER to be provided. ' +
+                'Register a provider: { provide: ROLE_RESOLVER, useExisting: YourRoleResolverService }');
+        }
+        this.resolvedRoleResolver = this.roleResolver;
+    }
+    async canActivate(context) {
+        const isPublic = this.reflector.getAllAndOverride(IS_PUBLIC_KEY, [
+            context.getHandler(),
+            context.getClass(),
+        ]);
+        if (isPublic)
+            return true;
+        const { user } = context.switchToHttp().getRequest();
+        if (!user?.id) {
+            throw new UnauthorizedException();
+        }
+        const [role, permissions] = await Promise.all([
+            this.resolvedRoleResolver.findPrimaryRole(user.id),
+            this.resolvedRoleResolver.findPermissions(user.id),
+        ]);
+        user.role = role;
+        user.permissions = permissions;
+        const requiredPermission = this.reflector.getAllAndOverride(REQUIRED_PERMISSION_KEY, [context.getHandler(), context.getClass()]);
+        if (requiredPermission && !permissions.includes(requiredPermission)) {
+            throw new ForbiddenException('Insufficient permissions');
+        }
+        return true;
+    }
+};
+PermissionGuard = __decorate([
+    Injectable(),
+    __param(1, Optional()),
+    __param(1, Inject(ROLE_RESOLVER)),
+    __metadata("design:paramtypes", [Reflector, Object])
+], PermissionGuard);
+export { PermissionGuard };

package/dist/lib/role-resolver.d.ts

@@ -0,0 +1,6 @@
+export declare const ROLE_RESOLVER = "ROLE_RESOLVER";
+export interface RoleResolver {
+    findPrimaryRole(userId: number): Promise<string | null>;
+    findPermissions(userId: number): Promise<string[]>;
+}
+//# sourceMappingURL=role-resolver.d.ts.map

package/dist/lib/role-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-resolver.d.ts","sourceRoot":"","sources":["../../src/lib/role-resolver.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C,MAAM,WAAW,YAAY;IAC3B,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxD,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACpD"}

package/dist/lib/role-resolver.js

@@ -0,0 +1 @@
+export const ROLE_RESOLVER = 'ROLE_RESOLVER';

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@open-kingdom/shared-backend-util-rbac",
+  "version": "0.0.2-17",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@open-kingdom/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "nx": {
+    "tags": [
+      "scope:shared",
+      "type:util",
+      "environment:backend"
+    ]
+  },
+  "dependencies": {
+    "tslib": "^2.3.0",
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0"
+  }
+}