permission-core

    • 简介

    permission-core 是面向 MonSQLize 3.1 Node.js 应用的细粒度授权库，将持久化 RBAC 管理与接口、菜单、API、数据行和字段的运行时检查统一起来。

    模块负责什么

    • 带租户范围的角色、单父角色继承和用户直接角色绑定
    • 基于类型化 action + resource 的 allow 与 deny 规则
    • 菜单节点、接口绑定、角色菜单授权、修订和审计记录
    • 用户决策、解释、可见菜单投影和授权集合
    • 可选的语义缓存，底层复用宿主 MonSQLize 缓存

    每次管理写入都通过 MonSQLize 事务持久化，并返回修订与审计证据。必要的 scope、策略上下文、数据库状态或来源完整性不可用时，运行时默认拒绝。

    宿主负责什么

    应用仍然负责认证、请求身份、密钥、MonSQLize 连接、业务集合、HTTP 错误序列化和运维策略。宿主必须构造可信的 PermissionSubject；模块不会自动信任任意租户或用户请求头。

    permission-core 不是身份提供方、登录模块、ORM、API 网关，也不是只在前端隐藏菜单的工具。

    四层能力怎样选择

    层级解决的问题是否必须
    核心 RBAC角色拥有哪些规则，用户绑定哪些角色，后端请求是否允许是
    菜单与接口绑定后台菜单、页面、按钮怎样关联真实接口并授权给角色否
    行级与字段级数据权限同一个集合中能访问哪些记录、读取或写入哪些字段否
    Vext 与生产运维框架接入、缓存、审计、健康检查和安全变更流程按部署需要

    先完成核心 RBAC，再按业务需要增加其他层。菜单权限不会代替后端接口判断，数据权限也不要求先使用菜单模块。

    对象怎样协作

    对象/方法输入输出典型使用方
    new PermissionCore(options) / init()已连接 MonSQLize 3.1 与 core 配置ready core 与 PermissionCoreHealth应用启动代码
    pc.scope(scope, defaults?)可信完整 scope；管理写入可一次绑定 actorId/requestIdScopedPermissionContext管理后台服务层
    pc.forSubject(subject, context?)已认证 user/scope/claimsSubjectPermissionContextHTTP handler、任务处理器
    subject.can/assert/explainaction/resource/可选 contextboolean、void/error 或解释 envelope后端授权点
    subject.menus.*已绑定 subject可见树、按钮表、路由状态前端 BFF/导航接口
    subject.data.collection()collection 名、逻辑资源、scopeFields受保护数据 facade业务 repository/service

    scope() 与 forSubject() 都是同步创建 facade，不查询数据库；真正的读取发生在后续管理/判定方法。后台管理请求建议在 scope(scope, defaults) 里一次绑定 actorId/requestId，普通写入就不需要反复传审计人或手写幂等键。逐参数说明见核心与上下文 API。

    运行模型

    文字等价说明。宿主把已认证身份转换成带完整 scope 的 `PermissionSubject`。permission-core 在该范围内解析角色和有效 allow/deny 规则，再用同一份授权状态处理路由与接口判定、可见菜单和按钮，以及受授权保护的 Mongo 集合操作。

    scope 至少包含 tenantId，还可以包含 appId、moduleId 或 namespace。另一个 scope 可以使用相同 userId 和 roleId，但不会共享绑定或规则。

    支持边界

    范围支持契约
    运行时Node.js 18 或更高版本
    持久化已连接的 monsqlize@3.1.0 实例；MongoDB 是当前支持的数据库路径
    框架框架无关核心，以及可选的 permission-core/plugins/vext
    缓存默认关闭；可选择使用调用方确认一致性的 MonSQLize 缓存
    认证由宿主提供；登录不属于本包职责

    选择下一项任务

    不熟悉 scope、subject、直接与有效的区别时，先读核心术语与心智模型。然后完成快速开始与管理角色与用户授权。核心已经运行时，再继续处理权限检查、数据权限或菜单管理。