# @anishpras/rbac 中文文档

规范地址：https://npmcn.com/package/%40anishpras/rbac/

版本：2\.1\.1
npm 元数据更新时间：2025-03-27T22:08:33.148Z
中文译文更新时间：2026-11-06T15:10:08.156Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40anishpras/rbac
原文对照：https://npmcn.com/package/%40anishpras/rbac/?lang=original
项目主页：https://github.com/anishpras/rbac#readme
源码仓库：https://github.com/anishpras/rbac

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：43.8 kB，27 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=14\.0\.0
- 运行依赖：0 个
- 首次发布：2025-03-27T19:09:11.405Z
- 最新版本发布：2025-03-27T22:08:32.977Z
- 近 30 天下载量：2949（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 0 个）

## 中文简介

用于JavaScript/TypeScript应用的快速,灵活和可生产的角色访问控制(RBAC)系统.

## 安装

```sh
npm install @anishpras/rbac
```

也可以使用：`pnpm add @anishpras/rbac`、`yarn add @anishpras/rbac`、`bun add @anishpras/rbac`

## README

# @anishpras/rbac: 角色和属性基于访问控制

用于JavaScript/TypeScript应用的快速,灵活和可生产的角色访问控制(RBAC)系统.

## 特征

-   🚀 **快速高效**: 以 LRU 缓存方式优化速度
-   🔒 **类型安全**: 完整类型脚本支持
-   🧩 **弹性**: 定义自定义角色、资源和权限
-   🔄 **角色等级**: 支持角色继承,进行强力循环检测
-   🛠️ **中间软件支持**: 准备使用Express.js和其他框架
-   📝 **流利的 API**: 配置的直观构建器模式
-   📊 **运行时间更新**: 不重新启动而修改权限
-   🧪 **严格模式**: 对未识别角色/资源的可选投放
-   📈 **可缩放**: 为大规模应用设计

## 安装

```bash
npm install @anishpras/rbac
# or
yarn add @anishpras/rbac
# or
pnpm add @anishpras/rbac
```

## 快速启动

```typescript
import { RBACManager, RBACBuilder } from '@anishpras/rbac';

// Create a configuration using the builder
const config = new RBACBuilder()
  .role('ADMIN', 'Administrator with full access')
    .grantFullAccess('Products')
    .grantFullAccess('News')
    .grantFullAccess('Bookings')
    .done()
  .role('EDITOR', 'Editor with limited access')
    .forResource('Products').grantAll().and()
    .forResource('News').grantAll().and()
    .forResource('Bookings').grantReadOnly().done()
  .setDefaultRole('EDITOR')
  .build();

// Create the RBAC manager
const rbac = new RBACManager(config, {
  cache: {
    enabled: true,
    maxSize: 1000,
    ttl: 60 * 1000 // 1 minute
  },
  strict: false, // Avoid runtime errors in production
  logger: {
    debug: (msg) => console.debug(`[RBAC] ${msg}`),
    info: (msg) => console.info(`[RBAC] ${msg}`),
    warn: (msg) => console.warn(`[RBAC] ${msg}`),
    error: (msg) => console.error(`[RBAC] ${msg}`)
  }
});

// Check permissions
const user = {
  id: 1,
  roles: ['EDITOR']
};

// Check if a user can create a product
if (rbac.userCan(user, 'Products', 'CREATE')) {
  // User can create products
}

// Check if a user can update a booking
if (rbac.userCan(user, 'Bookings', 'UPDATE')) {
  // User cannot update bookings
}
```

## Express.js Midddleware 示例

```typescript
import express from 'express';
import { RBACManager } from '@anishpras/rbac';

const app = express();
const rbac = new RBACManager(config);

// Middleware to protect routes
app.get(
  '/api/products',
  rbac.middleware({
    getUserRoles: (req) => req.user.roles,
    resource: 'Products',
    permission: 'READ',
    onDenied: (req, res) => {
      res.status(403).json({ error: 'Access denied' });
    }
  }),
  (req, res) => {
    // Handle the request
  }
);

// Dynamic permission based on HTTP method
app.all(
  '/api/bookings/:id',
  rbac.middleware({
    getUserRoles: (req) => req.user.roles,
    resource: 'Bookings',
    permission: (req) => {
      // Map HTTP method to permission
      switch (req.method) {
        case 'GET': return 'READ';
        case 'POST': return 'CREATE';
        case 'PUT': case 'PATCH': return 'UPDATE';
        case 'DELETE': return 'DELETE';
        default: return 'READ';
      }
    },
    onDenied: (req, res) => {
      res.status(403).json({ 
        error: 'Access denied',
        message: `You don't have permission to ${req.method} bookings` 
      });
    }
  }),
  (req, res) => {
    // Handle the request
  }
);
```

## 理解角色等级( 继承)

角色等级特征允许角色从其他角色继承权限. 这是图书馆最强大但有时令人困惑的方面之一.

```typescript
// Define role hierarchy
rbac.setRoleHierarchy({
  'EDITOR': ['ADMIN'],  // EDITOR inherits all permissions from ADMIN
  'VIEWER': ['EDITOR']  // VIEWER inherits all permissions from EDITOR
});
```

**关于角色等级的重要澄清**数字 :

在角色等级配置中:

-   这个 `key` 这是 **儿童角色** (继承权限的)
-   这个 `array values` 这是 **父角色** (继承者)

这意味着:

-   `'EDITOR': ['ADMIN']` 表示EDITOR继承了行政主管的权限,而不是相反
-   `'VIEWER': ['EDITOR']` 表示VIEWER从EDITOR继承(并转自行政主管)

像这样想:

```
'CHILD_ROLE': ['PARENT_ROLE_1', 'PARENT_ROLE_2']
```

让我们看看一个更完整的例子,来说明角色等级如何发挥作用:

```typescript
// Define role hierarchy with more complex relationships
rbac.setRoleHierarchy({
  // Store roles inherit from more general roles
  'STORE_MANAGER': ['ADMIN'],      // Store Manager inherits from Admin
  'STORE_CLERK': ['STORE_MANAGER'], // Store Clerk inherits from Store Manager
  
  // Content roles also inherit
  'CONTENT_EDITOR': ['ADMIN'],     // Content Editor inherits from Admin
  'CONTENT_VIEWER': ['CONTENT_EDITOR'], // Content Viewer inherits from Content Editor
  
  // Special case: dual inheritance
  'SUPERVISOR': ['STORE_MANAGER', 'CONTENT_EDITOR'] // Inherits from both roles
});

// Let's test some permissions
console.log(rbac.can('STORE_CLERK', 'Products', 'READ')); // true if STORE_MANAGER has this permission
console.log(rbac.can('SUPERVISOR', 'Content', 'PUBLISH')); // true if either parent role has this permission
```

库会自动处理过渡性继承,并检测循环引用来防止无限循环.

## 动态权限更新

您可以在运行时修改权限而不重新启动您的应用程序 :

```typescript
// Add a new role
rbac.addRole('MANAGER', {
  description: 'Manager role',
  permissions: {
    'Products': ['READ', 'UPDATE'],
    'Bookings': ['READ', 'UPDATE', 'CREATE']
  }
});

// Grant new permissions
rbac.grant('EDITOR', 'Reports', ['READ']);

// Revoke permissions
rbac.revoke('EDITOR', 'Bookings', ['DELETE']);

// Revoke all permissions on a resource
rbac.revoke('EDITOR', 'Bookings');

// Remove a role entirely
rbac.removeRole('GUEST');

// Update the entire configuration
rbac.updateConfig(newConfig);
```

记住在权限更改后清除缓存( 内置方法如 `grant()` 财务报告和审定财务报表 `revoke()` 自动处理此选项 :

```typescript
// Manually clear the cache when needed
rbac.clearCache();
```

## 政策评价

您可直接评价相关政策:

```typescript
const policyResult = rbac.evaluatePolicy({
  role: 'EDITOR',
  resource: 'Products',
  permission: 'UPDATE'
});

console.log(policyResult.allowed); // boolean
console.log(policyResult.reason);  // explanation string
```

## 查询可用的权限和资源

```typescript
// Get all permissions a role has on a resource
const permissions = rbac.getPermissions('EDITOR', 'Products');
// Returns: ['CREATE', 'READ', 'UPDATE', 'DELETE']

// Get all resources a role has access to
const resources = rbac.getResources('ADMIN');
// Returns: ['Products', 'News', 'Bookings', ...]

// Get all roles in the system
const roles = rbac.getRoles();
// Returns: ['ADMIN', 'EDITOR', 'VIEWER', ...]

// Get cache statistics
const cacheStats = rbac.getCacheStats();
// Returns: { enabled: true, size: 42 }
```

## 最佳做法

### 1\. 作用、资源和权限使用常量

定义常数,以防止打字并确保一致性:

```typescript
// Define constants
const ROLES = {
  ADMIN: 'ADMIN',
  EDITOR: 'EDITOR',
  VIEWER: 'VIEWER'
} as const;

const RESOURCES = {
  PRODUCTS: 'Products',
  USERS: 'Users',
  ORDERS: 'Orders'
} as const;

const PERMISSIONS = {
  CREATE: 'CREATE',
  READ: 'READ',
  UPDATE: 'UPDATE',
  DELETE: 'DELETE'
} as const;

// Use constants in your code
rbac.grant(ROLES.EDITOR, RESOURCES.PRODUCTS, [PERMISSIONS.READ, PERMISSIONS.UPDATE]);
```

### 2\. 非限制性生产方式

设定 `strict: false` 在生产中防止为未定义的角色或资源扔出错误。 如果一个角色被引用而不存在,这可以防止服务中断.

```typescript
const rbac = new RBACManager(config, {
  strict: process.env.NODE_ENV === 'development'
});
```

### 3\. 启用缓存

生产中总是使用缓冲来提高性能:

```typescript
const rbac = new RBACManager(config, {
  cache: {
    enabled: true,
    maxSize: 1000, // Limit cache size to prevent memory issues
    ttl: 5 * 60 * 1000 // Cache TTL of 5 minutes
  }
});
```

### 4\. 适当设置角色等级

记住在等级对象中:

-   关键是孩子的角色(继承权限的)
-   数组值为父角色( 从中继承)

```typescript
// CORRECT:
rbac.setRoleHierarchy({
  'EDITOR': ['ADMIN'], // EDITOR inherits from ADMIN
});

// INCORRECT (would mean ADMIN inherits from EDITOR):
rbac.setRoleHierarchy({
  'ADMIN': ['EDITOR']
});
```

### 5\. 使用自定义记录器

配置自定义日志以整合您的应用程序的日志系统 :

```typescript
const rbac = new RBACManager(config, {
  logger: {
    debug: (msg) => myLogger.debug(`[RBAC] ${msg}`),
    info: (msg) => myLogger.info(`[RBAC] ${msg}`),
    warn: (msg) => myLogger.warn(`[RBAC] ${msg}`),
    error: (msg) => myLogger.error(`[RBAC] ${msg}`)
  }
});
```

### 6\. 落实资源所有权

关于多租户系统,结合非洲区域局和资源所有权检查:

```typescript
// Middleware to check both permissions and ownership
const checkPermissionAndOwnership = (req, res, next) => {
  const resourceId = req.params.id;
  const userId = req.user.id;
  
  // First check RBAC permissions
  if (!rbac.userCan(req.user, 'Orders', 'UPDATE')) {
    return res.status(403).json({ error: 'Permission denied' });
  }
  
  // Then check ownership
  orderService.getOrderById(resourceId)
    .then(order => {
      if (order.userId !== userId) {
        return res.status(403).json({ error: 'Not your order' });
      }
      next();
    });
};
```

## 安全特性

此软件包包含安全性重点功能,以保护您的应用程序的许可系统:

1.  **输入验证**:所有角色,资源和许可输入都经过验证,以防止注射攻击和操纵.
    
2.  **循环参考检测**:在角色等级中自动检测并预防循环引用.
    
3.  **默认拒绝**:当出错或角色/许可未定义时,系统总是默认拒绝访问.
    
4.  **深克隆**:所有配置对象被深克隆来防止外部突变攻击.
    
5.  **保护缓存密钥**:缓存系统使用已消毒的密钥来防止缓存中毒.
    
6.  **安全中间软件**:"快递"中间软件的设计是为了安全地处理出错,总是默认访问拒绝.
    
7.  **审计日志**:为关键许可更改和访问尝试而构建的审计记录.
    
8.  **类型安全**: TypeScript类型执行适当的结构并预防常见的错误.
    
9.  **种族条件保护**: 特殊处理,在许可更新期间防止种族条件.
    
10.  **安全错误处理**:错误消息的设计是为了避免泄露敏感信息.
     

## 高级示例

对于更高级的用法示例,请检查 `examples` 存储器中的目录 :

-   `product-shop.ts`:具有标准作用的基本电子商务实例
-   `express-integration.ts`: 与 Express.js 中间软件的示例集成
-   `advanced-example.ts`: 具有综合权限的复杂角色等级

## API 参考

### 非洲区域局经理

管理RBAC功能的主要类.

```typescript
// Create a new instance
const rbac = new RBACManager(config, options);

// Check if a role has permission
rbac.can(role, resource, permission);

// Check if a user has permission
rbac.userCan(user, resource, permission);

// Set role hierarchy
rbac.setRoleHierarchy(hierarchy);

// Update configuration
rbac.updateConfig(config);

// Add a new role
rbac.addRole(role, definition);

// Remove a role
rbac.removeRole(role);

// Grant permissions
rbac.grant(role, resource, permission);

// Revoke permissions
rbac.revoke(role, resource, permission);

// Evaluate a policy
rbac.evaluatePolicy(policy);

// Get permissions for a role on a resource
rbac.getPermissions(role, resource);

// Get all resources a role has access to
rbac.getResources(role);

// Get all roles
rbac.getRoles();

// Get the complete configuration
rbac.getConfig();

// Clear the permission cache
rbac.clearCache();

// Get cache statistics
rbac.getCacheStats();

// Create middleware
rbac.middleware(options);
```

### 非洲区域局

用于构建RBAC配置的流利API.

```typescript
// Create a new builder
const builder = new RBACBuilder();

// Define roles and permissions
builder
  .role('ADMIN')
    .grantFullAccess('Products')
    .done()
  .role('EDITOR')
    .forResource('Products').grant('READ', 'UPDATE').and()
    .forResource('News').grantAll().done()
  .setDefaultRole('EDITOR');

// Build the configuration
const config = builder.build();
```

## 建设与发展

### 项目建设

该项目提供了开发和生产建设的备选方案:

```bash
# Development build (with source maps and comments)
npm run build

# Production build (minified with source maps)
npm run build:prod
```

### 缩小

生产构造用特尔泽自动将JavaScript输出分解,优化如下:

-   代码压缩( 删除白空间, 缩短可变名称)
-   取消死亡代码
-   为较小的文件大小管理可变名称
-   保留许可证/版权评论
-   调试的 sourcemap 生成

这导致文件大小明显较小,同时保持了完整的功能.

## 许可证

麻省理工学院

## 常见问题

### @anishpras/rbac 是什么？

用于JavaScript/TypeScript应用的快速,灵活和可生产的角色访问控制\(RBAC\)系统\.

### 如何安装 @anishpras/rbac？

在项目目录运行 npm install @anishpras/rbac，或使用 pnpm add / yarn add / bun add。

### @anishpras/rbac 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @anishpras/rbac 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @anishpras/rbac 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=14\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @anishpras/rbac 可以商用吗？

@anishpras/rbac 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @anishpras/rbac 的下载量有多少？

根据 npm 官方下载统计，@anishpras/rbac 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,949 次，日均约 98 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @anishpras/rbac 还在维护吗？

最新版本 2\.1\.1 发布于 2025/03/28（1\.6 年前）；至今共发布 7 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/03/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。