# @authx/scopes 中文文档 规范地址：https://npmcn.com/package/%40authx/scopes/ 版本：3\.1\.0-alpha\.56 npm 元数据更新时间：2025-09-10T18:24:16.019Z 中文译文更新时间：2026-11-07T06:17:29.395Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40authx/scopes 原文对照：https://npmcn.com/package/%40authx/scopes/?lang=original 项目主页：https://github.com/the-control-group/authx#readme 源码仓库：https://github.com/the-control-group/authx ## 关键信息（来自 npm 元数据） - 包体积（解压后）：139 kB，32 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=6 - 运行依赖：0 个 - 首次发布：2019-04-30T16:03:45.511Z - 最新版本发布：2024-06-06T22:58:45.045Z - 近 30 天下载量：3853（2026-10-07 至 2026-11-05，npm 官方下载统计） - 已发布版本数：56（近 12 个月 0 个） ## 中文简介 这是AuthX范围功能的小集合. 这些瞄准镜是人可读取的,完全OAuth2-相容的,支持模式匹配和设置代数. ## 安装 ```sh npm install @authx/scopes ``` 也可以使用：`pnpm add @authx/scopes`、`yarn add @authx/scopes`、`bun add @authx/scopes` ## README # 范围 这是AuthX范围功能的小集合. 这些瞄准镜是人可读取的,完全OAuth2-相容的,支持模式匹配和设置代数. * * * [范围解剖](https://npmcn.com/package/%40authx/scopes/#readme-anatomy-of-a-scope) | [安装](https://npmcn.com/package/%40authx/scopes/#readme-installation) | [API 密码](https://npmcn.com/package/%40authx/scopes/#readme-api) | [发展](https://npmcn.com/package/%40authx/scopes/#readme-development) * * * ## 范围解剖 范围由3个领域组成,分别由 `:` 字符 : ``` billing:customer.abc:read.basic |_____| |__________| |________| | | | realm context action ``` 每个域包含部分,由 `.` 字符键. ### 范围 A 类 _范围文字_ 范围总是以象征性、赠款或授权的形式存在,它已得到充分界定,随时可供资源使用. 范围文字中的分节可以是: - "单一的"符号: `*` - "多倍任意"符号: `**` - 匹配图案的"替换段" : `/[a-zA-Z0-9_-]*/` 例如,这些都是合法的 _范围文字_数字 : ``` billing:customer.abc:read.basic billing:customer.*:*.basic billing:**:read.* ``` ### 范围模板 A 类 _范围模板_ 是一个反相(超相) _范围文字_中的值 _范围文字_,a部分 _范围模板_ 可包含: - 匹配图案的“ 超时段 ” : `/^\{[a-zA-Z0-9_-]+\}$/` 例如,这些都是合法的 _范围模板_数字 : ``` billing:customer.{current_user_id}:read.basic authx:v2.authorization..*.{current_client_id}..{current_grant_id}..{current_user_id}:** ``` 范围模板的目的是描述一个范围,即一个价值目前尚不为人所知,但在创建赠款或授权时将会知道的范围。 范围模板从未以符号或授权方式被传递. ### 参数化范围 A 类 _参数化范围_ 是一种双变量(一种方式的超集,另一种方式的子集) _范围文字_中的值 _范围文字_,a部分 _参数化范围_ 可包含: - 匹配图案的"参数化段": `/^\([a-zA-Z0-9_-]+\)$/` A 中的一个域 _参数化范围_ 不得在"参数化部分"两侧含有"多相"符号,因为"参数化部分"的位置会变得模糊. 例如,这些都是合法的 _参数化范围_数字 : ``` billing:customer.(user_id):read.basic authx:v2.authorization..*.(client_id)..(grant_id)..(current_user_id):** authx:v2.**.(client_id)..(grant_id)..(current_user_id):** ``` 但以下内容无效: ``` authx:v2.**.(client_id)..**:** ``` 参数化范围的目的是从特定范围文字中取出一个值. 这对于资源是有用的,在资源中,在行动开始之前知道某一数值比在行动开始之后检查范围好。 例如,一个应用程序可能想要知道所有可能的值: `user_id` 参数化范围 `billing:customer.(user_id):read.basic` 在查询数据库前 . 参数化的瞄准镜从未通过任何标志或授权. ### 参数化范围模板 某些功能接受一个参数化的范围模板,既允许"参数化部分",也允许"元件化部分". ## 安装 安装方式 `npm install --save @authx/scopes` ## API 密码 请看 [测试](https://npmcn.com/package/%40authx/scopes/src/index.test.ts) 用于完整的例子. ### 是 Valid 范围 - ```ts isValidScope(scope: string): boolean isValidScope(collection: string[]): boolean ``` 验证一个范围的格式是否正确. ```js import { validate } from "@authx/scopes"; validate("realm:context.identifier:action.**"); // => true validate("realm:context.{identifier}:action"); // => false validate("realm:context.***:action"); // => false ``` ### 是 ValidScope 模板 - ```ts isValidScope(scope: string): boolean isValidScope(collection: string[]): boolean ``` 验证范围模板的格式是否正确. ```js import { validate } from "@authx/scopes"; validate("realm:context.identifier:action.**"); // => true validate("realm:context.{identifier}:action"); // => true validate("realm:context.***:action"); // => false ``` ### 常态 - ```ts normalize(scope: string): string normalize(collection: string[]): string[] ``` - **_掷出 `InvalidScopeError` 如果范围无效._** 将范围正常化为最简单的代表. ```js import { normalize } from "@authx/scopes"; normalize("realm:**.**:action"); // => 'realm:*.**:action' ``` ### 简化 - ```ts simplify(collection: string[]): string[] ``` - **_掷出 `InvalidScopeError` 如果在 `collection` 无效._** 简化范围收集 `collection` ,省略任何被收藏中另一个范围所使冗余的范围。 返回的收藏中的所有范围都实现了正常化. ```js import { simplify } from "@authx/scopes"; simplify(["realm:resource.*:action", "realm:**:action"]); // => ["realm:**:action"] ``` ### 等价键 - ```ts isEqual(scopeOrCollectionA: string[] | string, scopeOrCollectionB: string[] | string): boolean ``` - **_掷出 `InvalidScopeError` 如果在 `scopeOrCollectionA` 或者说 `scopeOrCollectionB` 无效._** 检查是否 `scopeOrCollectionA` 财务报告和审定财务报表 `scopeOrCollectionB` 都是一样的,忽略了多余的范围. ```js import { getIntersection } from "@authx/scopes"; getIntersection(["realm:**:*"], ["realm:**:action", "realm:**:*"]); // => true ``` ### 超级集 - ```ts isSuperset(scopeOrCollectionA: string[] | string, scopeOrCollectionB: string[] | string): boolean ``` - **_掷出 `InvalidScopeError` 如果在 `scopeOrCollectionA` 或者说 `scopeOrCollectionB` 无效._** 检查是否 `scopeOrCollectionA` 等于,或一个超集 `scopeOrCollectionB`。用于检查用户是否能够执行特定动作. ```js import { isSuperset } from "@authx/scopes"; isSuperset(["realm:**:*"], ["realm:**:action", "realm:**:*"]); // => true ``` ### 是 Strict 超级集 - ```ts isStrictSuperset(scopeOrCollectionA: string[] | string, scopeOrCollectionB: string[] | string): boolean ``` - **_掷出 `InvalidScopeError` 如果在 `scopeOrCollectionA` 或者说 `scopeOrCollectionB` 无效._** 检查是否 `scopeOrCollectionA` 是一个严格的超级集 `scopeOrCollectionB`。 。 。 . ```js import { isStrictSuperset } from "@authx/scopes"; isStrictSuperset(["realm:**:*"], ["realm:**:action", "realm:**:*"]); // => false ``` ### 子集 - ```ts isSubset(scopeOrCollectionA: string[] | string, scopeOrCollectionB: string[] | string): boolean ``` - **_掷出 `InvalidScopeError` 如果在 `scopeOrCollectionA` 或者说 `scopeOrCollectionB` 无效._** 检查是否 `scopeOrCollectionA` 等于或子集为 `scopeOrCollectionB`。 。 。 . ```js import { isSubset } from "@authx/scopes"; isSubset(["realm:**:action", "realm:**:*"], ["realm:**:*"]); // => true ``` ### 是 Strict 子集 - ```ts isStrictSubset(scopeOrCollectionA: string[] | string, scopeOrCollectionB: string[] | string): boolean ``` - **_掷出 `InvalidScopeError` 如果在 `scopeOrCollectionA` 或者说 `scopeOrCollectionB` 无效._** 检查是否 `scopeOrCollectionA` 是一个严格的子集 `scopeOrCollectionB`。 。 。 . ```js import { isStrictSubset } from "@authx/scopes"; isStrictSubset(["realm:**:action", "realm:**:*"], ["realm:**:*"]); // => false ``` ### 获取接口 - ```ts getIntersection(scopeOrCollectionA: string[] | string, scopeOrCollectionB: string[] | string): string[] ``` - **_掷出 `InvalidScopeError` 如果在 `scopeOrCollectionA` 或者说 `scopeOrCollectionB` 无效._** 获取交叉点 `scopeOrCollectionA` 财务报告和审定财务报表 `scopeOrCollectionB`,返回一组代表所有相交点的瞄准镜,或两种输入都具有的每一种能力. ```js import { getIntersection } from "@authx/scopes"; getIntersection(["realm:resource.*:action.*"], ["realm:**:action.read"]); // => ["realm:resource.*:action.read"] ``` ### 获取偏差 - ```ts getDifference(collectionA: string[], collectionB: string[]): string[] ``` - **_掷出 `InvalidScopeError` 如果在 `collectionA` 或者说 `collectionB` 无效._** 获取 `collectionA` 财务报告和审定财务报表 `collectionB`,返回在 `collectionB` 但是没有 `collectionA`。返回的收藏中包含规范范围 _已写入 `collectionB`_,即使返回范围与 `collectionA`。 。 。 . ```js import { getDifference } from "@authx/scopes"; getDifference( ["realm:resource.*:action.*"], ["realm:resource.foo:action.read", "realm:other:action.read"], ); // => ["realm:other:action.read"] ``` ### 有接口 - ```ts hasIntersection(scopeOrCollectionA: string[] | string, scopeOrCollectionB: string[] | string): string[] ``` - **_掷出 `InvalidScopeError` 如果在 `scopeOrCollectionA` 或者说 `scopeOrCollectionB` 无效._** 检查是否 `scopeOrCollectionA` 财务报告和审定财务报表 `scopeOrCollectionB` 交叉键。 在检查用户是否能够执行由该选项所代表的动作的任何子集时,此功能是有用的 `subject` 范围. ```js import { hasIntersection } from "@authx/scopes"; hasIntersection(["realm:resource.*:action.*"], ["realm:**:action.read"]); // => true ``` ## 发展 ### 脚本 这些脚本可以使用 `npm run