# @authup/access 中文文档

规范地址：https://npmcn.com/package/%40authup/access/

版本：1\.0\.0-beta\.73
npm 元数据更新时间：2026-11-01T20:46:04.822Z
中文译文更新时间：2026-11-07T06:14:07.040Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：532 kB，203 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=26\.0\.0
- 运行依赖：10 个
- 首次发布：2025-01-20T20:59:01.533Z
- 最新版本发布：2026-11-01T20:46:04.467Z
- 近 30 天下载量：4081（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 44 个）

## 中文简介

在您自己的进程中评价 Authup 权限和政策, 服务器使用的引擎相同 .

## 安装

```sh
npm install @authup/access
```

也可以使用：`pnpm add @authup/access`、`yarn add @authup/access`、`bun add @authup/access`

## README

![Authup logo](https://raw.githubusercontent.com/authup/authup/master/.github/assets/logo.svg)

# @ authup/ 访问

**在您自己的进程中评价 Authup 权限和政策, 服务器使用的引擎相同 .**  
您的 API 决定“ 可以更新此符号吗 ” , 而不是向 Authup 请求 .

[![npm version](https://img.shields.io/npm/v/@authup/access)](https://www.npmjs.com/package/@authup/access) [![CI](https://github.com/authup/authup/actions/workflows/main.yml/badge.svg)](https://github.com/authup/authup/actions/workflows/main.yml) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://npmcn.com/package/%40authup/access/LICENSE)

[**安装**](https://npmcn.com/package/%40authup/access/#readme-installation) • 妇女 [使用量](https://npmcn.com/package/%40authup/access/#readme-usage) • 妇女 [API 密码](https://npmcn.com/package/%40authup/access/#readme-api) • 妇女 [文档](https://authup.org/)

* * *

## 为什么?

在Authup中,赠款不仅仅是许可名称。 每笔赠款都涉及一个领域(`own`, (中文(简体) ), `ownOrNull`, (中文(简体) ), `any`)和可选政策(属性,身份,时间,日期,域匹配,复合材料),许可可以携带自己的政策. 在每一个接收 Authup 令牌的API 中重新执行该模型,是 API 和服务器最终如何不同意的. 这个软件包就是模型本身:服务器-核心服务用它来评价每个管理API请求,你也可以.

| 关切 | 没有它 | 用这个 |
| --- | --- | --- |
| **权限检查** | `if (token.permissions.includes('user_update'))`,而忽略了领域范围和政策 | `evaluateRecord(evaluator, { name: 'user_update', realm })` 响应服务器的方式 |
| **真实范围** | 每条路线手写租户比较 | `own`, (中文(简体) ), `ownOrNull` 财务报告和审定财务报表 `any` 根据记录领域对每笔赠款进行评估 |
| **政策** | 第二,部分执行属性、时间和身份规则 | 内置政策评价员,加上你们自己的类型 `PolicyEngine` |
| **数据** | 在服务器上添加权限后无声拒绝 | `AuthorizationCatalogStaleError` 说拷贝是旧的,所以你调试 |
| **列表查询** | 获取所有信息, 然后过滤内存 | `compile()` 将决定降低到一个 rapiq 条件, 您可以推动查询 |

## 安装

```shell
npm install @authup/access
```

仅限无害环境管理。 节点.js `>=26.0.0`。没有同伴依赖关系;政策引擎也在浏览器中运行.

## 使用量

### 评估您定义的权限

```typescript
import {
    BuiltInPolicyType,
    PermissionEvaluator,
    PermissionMemoryProvider,
    defineAttributesPolicy,
    definePolicyData,
} from '@authup/access';

const evaluator = new PermissionEvaluator({
    provider: new PermissionMemoryProvider([
        { permission: { name: 'report_read' } },
        {
            permission: { name: 'report_update' },
            policies: [defineAttributesPolicy({ type: BuiltInPolicyType.ATTRIBUTES, query: { ownerId: 'u1' } })],
        },
    ]),
});

await evaluator.evaluate({ name: 'report_read' });

await evaluator.evaluate({
    name: 'report_update',
    data: definePolicyData({ [BuiltInPolicyType.ATTRIBUTES]: { ownerId: 'u1' } }),
});

await evaluator.preEvaluate({ name: 'report_update' }); // passes: the row is not known yet
```

-   `evaluate` 解决或丢出 `PermissionError` (单位:千美元)`isPermissionError`) (中文(简体) ). 有几个名字,它需要所有的名字; `evaluateOneOf` 需要一个.
-   `preEvaluate` 是数据存在的前门 : 缺少数据密钥的政策会算数, 只有已经失败的政策会否认. `evaluate` 同样的密钥缺失 .
-   提供者不知道否认的许可.
-   一个 `attributes` 保险单 `query` 是一个 MongoDB 风格的过滤器 (`{ ownerId: 'u1' }`, (中文(简体) ), `{ age: { $gte: 18 } }`与 `attributes` 数据键.

### 根据 Authup 的目录决定

资源服务器读取一次无身份目录( I)`GET /authorization`,拥有自己的客户资格 `permission_read`),并从它收到的纪念物的回想中取出赠款和身份(`POST /token/introspect`数字 : `permissions`, (中文(简体) ), `sub`, (中文(简体) ), `sub_kind`, (中文(简体) ), `realm_id`, (中文(简体) ), `realm_name`:

```typescript
import {
    createAuthorizationEvaluator,
    evaluateRecord,
    isAuthorizationCatalogStaleError,
    reachesRecord,
} from '@authup/access';

declare const catalog: unknown;
declare const grants: unknown;
declare function refetchCatalog(): Promise<unknown>;

const identity = {
    type: 'user',
    id: '7c9e6679-7425-40de-944b-e07fc1f099d6',
    realmId: '4c8e0f9e-6c0a-4b1e-9d31-2a6f0b1c7e11',
};

let evaluator;
try {
    evaluator = await createAuthorizationEvaluator({ catalog, grants, identity });
} catch (error) {
    if (!isAuthorizationCatalogStaleError(error)) {
        throw error;
    }

    evaluator = await createAuthorizationEvaluator({ catalog: await refetchCatalog(), grants, identity });
}

await evaluateRecord(evaluator, {
    name: 'user_update',
    realm: '4c8e0f9e-6c0a-4b1e-9d31-2a6f0b1c7e11',
    data: { attributes: { name: 'alice' } },
});

const canDelete = await reachesRecord(evaluator, { name: 'user_delete', realm: null });
```

-   `catalog` 财务报告和审定财务报表 `grants` 被验证,这样您就可以通过解析后的响应机构。 一个错误的文档丢出 .
-   指定授权或政策名称的赠款目录缺少丢弃 `AuthorizationCatalogStaleError`:你的目录比赠款大。 复取还取并建.
-   服务器无法预测到的定义 `policies: null`,而您的副本无法投影的政策树(未知类型,配置其验证符拒绝)则拒绝使用它的权限。 无论是投出还是其他权限都不受影响.
-   没有 `identity` 只有其政策不需要认同的定义才能通过。 没有身份的赠款被拒绝.
-   自定义政策类型需要两个部分: `createAuthorizationEvaluator(input, { validators, evaluators })`,每个替换内置登记册(扩展) `PolicyDefaultValidators` 编号 : `PolicyDefaultEvaluators` 以扩大范围).

### 检查一个记录

`evaluateRecord`, (中文(简体) ), `evaluateRecordOneOf`, (中文(简体) ), `reachesRecord`, (中文(简体) ), `reachesRecordOneOf` 财务报告和审定财务报表 `evaluateRecordUpdate` 明确记录的范围:

| `realm` | 手段 |
| --- | --- |
| `'<realm id>'` | 这世界的一行 |
| `null` | 全球行 |
| `['<id>', null]` | 横跨多个领域的一行;必须达到每一行 |
| `undefined` | 抛出:一个缺失的域是一个bug,从不"全球" |

-   `realmId` 财务报告和审定财务报表 `clientId` 命名域和客户端 OWING 权限定义,而不是记录的域. 缺席是指一个全球定义;没有这种定义,自有定义就无法实现.
-   `data` 是一个 `PolicyData` 或简单记录 不得携带 `realmMatch` 自己; 助手从 `realm`它被克隆了,从来没有写给.
-   `reachesRecord*` 返回时 `false` (单位:千美元) `PermissionError` 并重新扔任何东西.
-   `evaluateRecordUpdate(evaluator, { name, current, next })` 评估所存储行和更新行,因此更新既不能将一行移入,也不能将其移出.
-   `hasUnboundedReach(evaluator, name, owner?)` 当 `compile` 答题 `allow`页:1 `any` 赠款,没有缩小政策。 过 `{ realmId, clientId }` 作为 `owner` 为自定义.

### 使用批次检查答案

一个公共客户端(一个浏览器应用)没有秘密,因此无法读取目录. 它问 `POST /authorization/check` 以他们的判决代替他们的判决,并以他们的私密判决

```typescript
import { createAuthorizationCheckEvaluator, reachesRecord } from '@authup/access';

declare const permissions: unknown; // the response body

const evaluator = await createAuthorizationCheckEvaluator({
    permissions,
    identity: {
        type: 'user',
        id: '7c9e6679-7425-40de-944b-e07fc1f099d6',
        realmId: '4c8e0f9e-6c0a-4b1e-9d31-2a6f0b1c7e11',
        realmName: 'acme',
    },
});

const canEdit = await reachesRecord(evaluator, { name: 'user_update', realm: 'acme' });

// a definition owned by a realm or a client is named with its owner
const canExport = await reachesRecord(evaluator, {
    name: 'report_export',
    realmId: '4c8e0f9e-6c0a-4b1e-9d31-2a6f0b1c7e11',
    clientId: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',
    realm: 'acme',
});
```

答案列出了每个许可定义,由 `name`, (中文(简体) ), `realmId` 财务报告和审定财务报表 `clientId`,带有目标域;缺失的条目是否定. 其中包含哪些定义是请求 `realms` 编号 : `clients` 选择器 : `own`, (中文(简体) ), `ownOrNull`, (中文(简体) ), `granted` (每个定义的拥有者 身份持有一个授予,在之外 `ownOrNull`)或一一一一一一一一一一. 一个记录域与自己的条目相匹配,或者身份的自身域由id或取名. 请求中并没有提出否认的问题。 结果是一个上行:服务器仍然决定每行.

## 真实范围

| `realmScope` | 范围 |
| --- | --- |
| `none` | 没什么 |
| `own` (默认) | 身份所在域的行 |
| `ownOrNull` | 自有领域和全球行`realm: null`(中文(简体) ) |
| `any` | 每个域和全球行 |

无赠款 `realmScope` 实值 `own`。一个没有地盘的身份在下面没有任何意义 `any`。 。 。 .

## 政策类型

| `BuiltInPolicyType` | 数值 | 决定: |
| --- | --- | --- |
| `ATTRIBUTES` | `attributes` | 一个蒙哥DB风格 `query` 超过 `attributes` 数据 |
| `ATTRIBUTE_NAMES` | `attributeNames` | 哪个字段 `names` 数据可能携带(带有: `invert`,拒绝列表) |
| `IDENTITY` | `identity` | 这个身份 `types` (单位:千美元)`user`, (中文(简体) ), `client`(中文(简体) ) |
| `REALM_MATCH` | `realmMatch` | 记录域与身份域相对 |
| `DATE` | `date` | A 类 `start` 编号 : `end` 日期窗口 |
| `TIME` | `time` | A 类 `start` 编号 : `end` 天数(`HH:MM`),可选限制 `interval` 与 `dayOfWeek`, (中文(简体) ), `dayOfMonth` 或者说 `dayOfYear` |
| `COMPOSITE` | `composite` | 内容 `children`合并 `unanimous`, (中文(简体) ), `affirmative` 或者说 `consensus` |
| `PERMISSION_BINDING` | `permissionBinding` | 身份是否持有达到记录的捐赠 |

每个政策都接受 `invert`政策数据是 `PolicyData` 由类型名称键入的 bag (`attributes`, (中文(简体) ), `identity`, (中文(简体) ), `realmMatch`(......) ; (......); `definePolicyData` 使用已知的密钥类型检查后构建一个 .

## API 密码

| 导出 | 仁爱 | 目的 |
| --- | --- | --- |
| `PermissionEvaluator`, (中文(简体) ), `IPermissionEvaluator` | 类,接口 | `evaluate`, (中文(简体) ), `evaluateOneOf`, (中文(简体) ), `preEvaluate`, (中文(简体) ), `preEvaluateOneOf`, (中文(简体) ), `compile` |
| `PermissionMemoryProvider`, (中文(简体) ), `IPermissionProvider` | 类,接口 | 在评估者查看许可定义时 |
| `evaluateRecord`, (中文(简体) ), `evaluateRecordOneOf`, (中文(简体) ), `reachesRecord`, (中文(简体) ), `reachesRecordOneOf`, (中文(简体) ), `evaluateRecordUpdate`, (中文(简体) ), `hasUnboundedReach` | 函数 | 具有明确领域的单一记录检查 |
| `createAuthorizationEvaluator` | 函数 | 评估目录、内审赠款和身份 |
| `createAuthorizationCheckEvaluator` | 函数 | 对批量检查答案进行评估 |
| `AuthorizationCatalogStaleError`, (中文(简体) ), `isAuthorizationCatalogStaleError` | 类, 函数 | 反射信号 |
| `projectAuthorizationPolicy`, (中文(简体) ), `AUTHORIZATION_POLICY_WITHHELD_TYPE` | 函数, const | 策略树的电线投影, 以及服务器发送的取而代之的节点 |
| `AuthorizationCatalog`, (中文(简体) ), `AuthorizationGrant`, (中文(简体) ), `AuthorizationCheckPermissions`, (中文(简体) ), `authorizationCatalogSchema`,, , , , , , , , . | 类型、计划 | 电线类型及其 Zod 计划 |
| `PolicyEngine`, (中文(简体) ), `IPolicyEngine`, (中文(简体) ), `IPolicyEvaluator` | 类,接口 | 评价一棵政策树; `registerEvaluator(type, evaluator)` 添加类型 |
| `PolicyDefaultEvaluators`, (中文(简体) ), `PolicyDefaultValidators` | 针头 | 内部登记册 |
| `BuiltInPolicyType`, (中文(简体) ), `SystemPolicyName` | enum, 康斯特语 | 政策类型名称; 提供系统政策的名称(`system.default`, (...) (中文(简体) ) |
| `<Type>Policy`, (中文(简体) ), `<Type>PolicyEvaluator`, (中文(简体) ), `<Type>PolicyValidator` | 类型,类 | 每个内置政策类型1个三重奏 |
| `IdentityPermissionBindingPolicyEvaluator` | 类 | 决定 `permissionBinding` 身份数据上发放的补助金 |
| `PolicyData`, (中文(简体) ), `definePolicyData`, (中文(简体) ), `PolicyInput`, (中文(简体) ), `IdentityPolicyData` | 类、 函数、 类型 | 评价数据包 |
| `RealmScope`, (中文(简体) ), `realmScopeMatches`, (中文(简体) ), `normalizeRealmScope`, (中文(简体) ), `compareRealmScope`, (中文(简体) ), `minRealmScope`, (中文(简体) ), `maxRealmScope` | enum, 函数 | 真实范围 |
| `aggregatePermissionPolicyBindings`, (中文(简体) ), `grantDominates`, (中文(简体) ), `buildPermissionKey` | 函数 | 赠款汇总和比较 |
| `PermissionError`, (中文(简体) ), `PolicyError`, (中文(简体) ), `isPermissionError`, (中文(简体) ), `isPolicyError` | 类, 函数 | 错误( 都延伸) `AuthupError` 从 `@authup/errors`(中文(简体) ) |
| `createPolicyTransitionCollector`, (中文(简体) ), `PolicyTransitionSink` | 函数,类型 | 收集一个瞬间 `date` 或者说 `time` 判决可能改变 |

## 页:1

-   **王国的影响力由 `permissionBinding` 政策.** A 类 `PermissionEvaluator` 结束 `PermissionMemoryProvider` 忽略绑定的 `realmScope`及其默认值 `permissionBinding` 评估员总是通过. `createAuthorizationEvaluator` 电线 `IdentityPermissionBindingPolicyEvaluator`,并绑定 `system.default` (其中包含 `permissionBinding` 因此,它创建的每一个权限,也就是检查范围的地方。 到达时从目录中构建 .
-   **身份数据使用UUID.** 身份数据验证器检查 `id`, (中文(简体) ), `clientId` 财务报告和审定财务报表 `realmId` 作为UUUID; 任何其他值都使每个 `identity` 政策失败.
-   **`compile` 能够回答 `post`。 。 。 .** 这意味着不能将决定表达为查询条件;在您页面之前评价每个候选行,或者该页面及其总数是错误的.
-   **每个 `PolicyEngine` 拥有其评估地图.** 构造者复制地图,所以 `registerEvaluator` 一个引擎永远无法到达另一个引擎.

## 许可证

由 所制

现按 [Apache 2.0 许可证](https://npmcn.com/package/%40authup/access/LICENSE)。 。 。 .

## 常见问题

### @authup/access 是什么？

在您自己的进程中评价 Authup 权限和政策, 服务器使用的引擎相同 \.

### 如何安装 @authup/access？

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

### @authup/access 支持 TypeScript 吗？

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

### @authup/access 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @authup/access 需要什么版本的 Node\.js？

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

### @authup/access 可以商用吗？

@authup/access 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @authup/access 的下载量有多少？

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

### @authup/access 还在维护吗？

最新版本 1\.0\.0-beta\.73 发布于 2026/11/02（5 天前）；至今共发布 48 个版本，其中过去 12 个月发布了 44 个；首次发布于 2025/01/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。