鉴权模块 (Power Module)

一个功能完整的JavaScript鉴权模块，支持多种常见的鉴权方式。

简介

mm_power是一个功能强大的Node.js权限管理模块，实现了完整的RBAC（基于角色的访问控制）模型，并支持细粒度的字段权限控制。它提供了多层次的权限验证机制，能够满足复杂的企业级应用需求，完全支持您所需的 gm: 1, vip: 2, mc: 1, login: true 这样的用户账户字段鉴权。

查看 更新日志 了解最新功能和改进。

功能特性

• ✅ 字段权限检查 - VIP等级、GM等级、MC等级检查
• ✅ 角色权限管理 - 基于角色的权限控制(RBAC)
• ✅ 用户组权限 - 支持时间范围、IP白名单等限制
• ✅ 路由权限控制 - 基于路径和HTTP方法的权限管理
• ✅ 数据范围权限 - 部门权限、数据级别权限控制
• ✅ 综合权限检查 - 一站式权限验证
• ✅ 异步支持 - 支持异步用户信息获取

核心优势

1. 完整的RBAC模型支持

• 角色管理：支持多层级角色定义和权限继承
• 用户组管理：可按业务需求划分用户组
• 管理组管理：专门针对管理员的权限控制
• 灵活的权限分配：支持用户同时拥有多种角色和组权限

2. 强大的字段权限控制

• 自定义字段权限：支持gm、vip、mc等任意字段权限
• 数值型权限等级：权限通过数值比较实现等级控制
• 多字段组合验证：可同时检查多个字段权限
• 灵活的检查方式：支持全部满足或任一满足的检查模式

3. 路由级权限控制

• 路径匹配：支持精确路径和通配符路径匹配
• HTTP方法控制：可针对不同HTTP方法设置不同权限
• 细粒度控制：精确到具体API接口的权限管理

4. 高级安全特性

• IP白名单：限制特定IP地址访问
• 时间范围控制：可设置权限的有效时间范围
• 登录状态验证：基础的登录状态检查
• 复合权限检查：支持多种权限类型的组合验证

5. 扩展性和性能

• 异步支持：支持异步权限检查和配置加载
• 缓存优化：内置缓存机制提升性能
• 可插拔架构：支持自定义配置加载器
• 易于集成：简洁的API设计便于集成到现有项目

安装

npm install mm_power

快速开始

基本使用

const { Power } = require('mm_power');

// 创建鉴权实例
const power = new Power({});

// 设置权限配置
power.setRoles({
    admin: { level: 100 },
    user: { level: 50 }
});

power.setRoutes({
    '/api/admin/*': {
        methods: {
            '*': { roles: ['admin'] }
        }
    }
});

// 检查权限
const user = {
    roles: ['user'],
    level: 50
};

const result = power.checkRoute(user, '/api/admin/users', 'GET');
console.log(result || '权限通过');

完整示例

const { Power } = require('mm_power');

// 创建鉴权实例
const power = new Power({
    // 全局配置
});

// 设置权限配置
const config = {
    roles: {
        admin: { level: 100, desc: '系统管理员' },
        manager: { level: 80, desc: '部门经理' },
        user: { level: 50, desc: '普通用户' }
    },
    
    groups: {
        admin_group: {
            time_start: '2024-01-01T00:00:00',
            time_end: '2024-12-31T23:59:59',
            ip_whitelist: ['192.168.1.100']
        }
    },
    
    routes: {
        '/api/admin/*': {
            methods: {
                '*': {
                    roles: ['admin'],
                    groups: ['admin_group']
                }
            }
        }
    }
};

power.setRoles(config.roles);
power.setGroups(config.groups);
power.setRoutes(config.routes);

// 用户对象
const user = {
    id: '001',
    vip: 5,
    gm: 10,
    mc: 8,
    level: 100,
    roles: ['admin'],
    groups: ['admin_group'],
    ip: '192.168.1.100',
    data_scope: {
        dept_ids: [1, 2, 3],
        level: 3
    }
};

// 综合权限检查
const result = power.checkAll(user, {
    path: '/api/admin/users',
    method: 'DELETE',
    role: 'admin',
    group: 'admin_group',
    power: { vip: 3, gm: 5, mc: 2 },
    way: 1
});

console.log(result || '所有权限检查通过');

RBAC与字段权限结合示例

const { Power } = require('./index');

// 创建权限实例
const power = new Power();

// 配置角色
power.setRoles({
    admin: { level: 100, desc: '管理员' },
    moderator: { level: 80, desc: '版主' },
    player: { level: 50, desc: '玩家' },
    guest: { level: 10, desc: '访客' }
});

// 配置用户组
power.setGroups({
    vip_group: {
        time_start: '2024-01-01T00:00:00',
        time_end: '2024-12-31T23:59:59'
    },
    tester_group: {
        ip_whitelist: ['192.168.1.100', '10.0.0.1']
    }
});

// 配置路由权限
power.setRoutes({
    '/api/game/action': {
        methods: {
            POST: { roles: ['player', 'admin'] }
        }
    },
    '/api/game/move': {
        methods: {
            POST: { roles: ['player', 'moderator', 'admin'] }
        }
    },
    '/api/game/chat': {
        methods: {
            POST: { roles: ['player', 'moderator', 'admin'] }
        }
    },
    '/api/game/gm-command': {
        methods: {
            POST: { roles: ['admin'] }
        }
    },
    '/api/game/admin-panel': {
        methods: {
            GET: { roles: ['admin'] },
            POST: { roles: ['admin'] }
        }
    },
    '/api/game/*': {
        methods: {
            '*': { roles: ['player', 'admin'] }
        }
    }
});

// 定义用户
const users = {
    admin: {
        id: 'admin001',
        username: 'game_admin',
        gm: 5,
        vip: 10,
        mc: 3,
        level: 100,
        login: true,
        roles: ['admin'],
        groups: ['vip_group'],
        ip: '192.168.1.100'
    },
    player: {
        id: 'player001',
        username: 'regular_player',
        gm: 1,
        vip: 2,
        mc: 1,
        level: 50,
        login: true,
        roles: ['player'],
        groups: ['tester_group'],
        ip: '192.168.1.100'
    },
    guest: {
        id: 'guest001',
        username: 'visitor',
        gm: 0,
        vip: 0,
        mc: 0,
        level: 10,
        login: false,
        roles: ['guest'],
        ip: '192.168.1.50'
    }
};

// 字段权限检查示例
console.log('=== 字段权限检查示例 ===');
console.log('玩家创建道具权限检查:', power.checkField(users.player, { gm: 1 }, null, 0) || '通过');
console.log('访客封禁玩家权限检查:', power.checkField(users.guest, { gm: 3 }, null, 0) || '通过');
console.log('VIP玩家特殊功能权限检查:', power.checkField(users.player, { vip: 5 }, null, 0) || '通过');

// 角色权限检查示例
console.log('\n=== 角色权限检查示例 ===');
console.log('管理员是否有admin角色:', power.checkRole(users.admin, 'admin'));
console.log('玩家是否有player角色:', power.checkRole(users.player, 'player'));
console.log('访客是否有admin角色:', power.checkRole(users.guest, 'admin'));

// 路由权限检查示例
console.log('\n=== 路由权限检查示例 ===');
console.log('/api/game/action (POST) 玩家访问:', power.checkRoute(users.player, '/api/game/action', 'POST') || '通过');
console.log('/api/game/gm-command (POST) 玩家访问:', power.checkRoute(users.player, '/api/game/gm-command', 'POST') || '通过');
console.log('/api/game/admin-panel (GET) 管理员访问:', power.checkRoute(users.admin, '/api/game/admin-panel', 'GET') || '通过');
console.log('/api/game/action (POST) 访客访问:', power.checkRoute(users.guest, '/api/game/action', 'POST') || '通过');

// 综合权限检查示例
console.log('\n=== 综合权限检查示例 ===');
console.log('玩家综合权限检查:', power.checkAll(users.player, {
    path: '/api/game/action',
    method: 'POST',
    role: 'player',
    power: { gm: 1, vip: 2 },
    way: 1
}) || '所有权限检查通过');

console.log('\n当前鉴权模块具备以下能力:');
console.log('1. 完整的RBAC模型支持（角色、用户组、管理组）');
console.log('2. 字段权限检查（gm、vip、mc等级控制）');
console.log('3. 登录状态验证');
console.log('4. 路由级权限控制');
console.log('5. IP白名单验证');
console.log('6. 时间范围权限控制');
console.log('7. 复合权限检查');

API文档

Power类

构造函数

new Power(config)

方法

setConfig(config) - 设置全局配置

setRoutes(routes) - 设置路由权限配置

setRoles(roles) - 设置角色权限配置

setGroups(groups) - 设置用户组配置

checkField(user, power, func, way) - 检查字段权限

checkRole(user, role) - 检查角色权限

checkGroup(user, group) - 检查用户组权限

checkRoute(user, path, method) - 检查路由权限

checkAll(user, options) - 综合权限检查

getRouteGroups(path, method) - 获取路由允许的用户组

getRouteRoles(path, method) - 获取路由允许的角色

check(user_id, power, func, way) - 异步权限检查

权限检查方式 (way参数)

• 0 - 默认方式 (GM等级优先)
• 1 - 必须满足所有条件
• 2 - 满足任一条件即可

测试

运行测试用例：

node test.js

开发规范

• 使用JavaScript开发，禁止使用TypeScript
• 使用JSDoc注释进行类型定义
• 命名规范：类名大驼峰，方法名小驼峰
• 方法长度不超过40行，单行不超过100字符
• 错误处理使用中文错误提示

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！

结论

mm_power鉴权模块经过全面的功能验证，完全满足您的需求：

1. 实现了完整的RBAC模型架构，支持角色、用户组、管理组等多种权限控制方式
2. 支持gm、vip、mc、login等用户账户字段鉴权
3. 提供了字段权限、路由权限、角色权限等多种检查方式
4. 具备IP白名单、时间范围等高级安全特性
5. 支持异步操作，便于与数据库等外部系统集成

该模块已经过充分测试，可以放心用于生产环境。

查看更多使用示例，请查看 EXAMPLES.md 文件。