# @astram/guard 中文文档

规范地址：https://npmcn.com/package/%40astram/guard/

版本：0\.34\.0
npm 元数据更新时间：2026-11-06T15:56:22.609Z
中文译文更新时间：2026-11-07T00:57:15.640Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40astram/guard
原文对照：https://npmcn.com/package/%40astram/guard/?lang=original
项目主页：https://github.com/ASTRAM-2-0/astram-framework#readme
源码仓库：https://github.com/ASTRAM-2-0/astram-framework

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

- 包体积（解压后）：2.2 MB，460 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：rxjs ^7，@nestjs/core ^11，@nestjs/common ^11，reflect-metadata ^0\.2，@astram/messaging ^0\.1\.22，@nestjs/platform-express ^11
- 首次发布：2026-07-10T14:21:37.549Z
- 最新版本发布：2026-11-06T15:56:22.420Z
- 近 30 天下载量：6554（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 47 个）

## 中文简介

Astram框架——执行后卫+现实世界适配器("手"). 每个请求都经过一个全球性的逐一拒绝闸门(ADR-0002)、分类装饰器、靴子池主张(ADR-0018)、Root()注册接头和DB/R

## 安装

```sh
npm install @astram/guard
```

也可以使用：`pnpm add @astram/guard`、`yarn add @astram/guard`、`bun add @astram/guard`

## README

# @astram/guard — 执行门+巢JS适配器

这个 **执法门+薄巢JS集成** astram 框架—— 可装入可装入可装入胶水的消费应用软件(它运行在/与NestJS集成). 人数 [ADR-0023 (英语)](https://npmcn.com/package/docs/Shield/ADR/0023-framework-model-publishable-core.md) 这是 **框架代码, 自有 + 锁定**,不能消费-编辑:它生活在 消费者 `node_modules`,并升级流经 `npm update`它取决于 [`@astram/core`](https://npmcn.com/package/%40astram/core) (框架-不可知内核)和PEER-依赖 主机"巢穴JS"运行时间.

## 这里面是什么

| 块 | 文件 | 目的 |
| --- | --- | --- |
| **`ShieldModule`** | `src/module/shield.module.ts` | 这个 **一个注册接头** —— 说 `forRoot()` 编号 : `forRootAsync()`消费者进口一次;框架拥有构成. |
| 全球执法警卫 | `src/enforcement/global-enforcement.guard.ts` | 逐一否认 `APP_GUARD` (ADR-0002)每条路线都经过. |
| 分类装饰 | `src/enforcement/classification.decorator.ts` | `@Public()` 编号 : `@Classified()` 消费者作者在控制器上写这些. |
| 核心连接 | `src/enforcement/core-seam.ts` | 仅导入类型 `@astram/core`是因为 `DecisionAuthority` (ADR-0003) + 故障闭塞活塞. |
| 靴子池论 | `src/boot/boot-sequence.ts` | ATR-0018 连接池预算在启动时检查(未关闭). |
| 应用配置 | `src/config/app-config.ts` | 港口/环境/ADR-0018池预算(env加载器,纯). |
| 请求本金 | `src/request-auth/request-principal-als.ts` | 只读 `currentRequestPrincipal()`: 当前的请求 `{ tenantId, userId }` (下关. |

## 登记连接(ADR-0023§4)

一个消费者应用 电线Astram与一个 **单导入** 在其根模块中,它从来没有 编辑框架 :

```ts
import { Module } from '@nestjs/common';
import { ShieldModule } from '@astram/guard';

@Module({
  imports: [
    ShieldModule.forRoot(), // fail-closed stub authority; env-loaded config
    // ShieldModule.forRoot({ decisionAuthority, config }) to supply the real Core authority
  ],
  controllers: [/* the consumer's feature controllers */],
})
export class AppModule {}
```

`forRoot()` 绑定 :

-   **`GlobalEnforcementGuard` 作为 `APP_GUARD`** · 全球、结构上不可避免, 拒绝逐一执行点(ADR-0002). `@Public()` 是唯一的选择退出; 未分类的路由是 **被拒绝(403)**。 。 。 .
-   决心 **`AppConfig`** (单位:千美元) `APP_CONFIG`\+ 该 **`BootSequence`** 钩子, 运行 **ADR-0018 (英语)** (b) 启动时的集合预算主张(违规行为).
-   这个 **核心决定权** (单位:千美元) `SHIELD_DECISION_AUTHORITY`)——真实的 `@astram/core` 授权通过 `forRoot({ decisionAuthority })`,则 关闭失败 **树枝** (deny-by-default),所以误拨不能打开一扇门.

`forRootAsync({ useFactory, inject, imports })` 由 DI 计算成的变体( stub) 在此层中: 工厂在启动时解决相同的选项; 守护/启动 接线相同.

## 请求本金`currentRequestPrincipal`(中文(简体) )

```ts
import { currentRequestPrincipal } from '@astram/guard';

const p = currentRequestPrincipal(); // Readonly<{ tenantId: string; userId: string }> | undefined
```

在请求中运行但没有的框架代码 `req` 手持(例如 `@astram/agent`是因为 `createAuditedFetch`)在这里读到打电话者的房客和校长的ID. 谱: `docs/features/capability-outbound-audit/SPEC.md` v6 第5节 G.

-   **唯相读取.** 框架中间软件( Name`EnforcementModule`,每条路线)打开一个模块-私人 `AsyncLocalStorage` 每个请求都有空的持有人。 全球执法卫队是唯一 写入器:一次,在允许路径上,在认证后,从主端解出 会话或 API 密钥( 绝不来自正文、 标题或查询) 。 值被冻结。 存储,存储 中间软件和写入器不导出,因此应用程序代码不能输入范围或覆盖范围.
-   **`undefined`** 在请求(预定工作)之外 `@Public()` 路径,用于请求 警卫拒绝了 请求没有通过中间软件.
-   **`userId` 是主要编号**: 用户或服务账户. 值没有说明是哪一种 (GAPS #46); 需要时查查ID.
-   在请求的同步上下文之外恢复工作(例如一些溪流消费者)读取 `undefined`,从没有另一个请求的值(一个交互的4个请求测试持有这个). 读吧 在请求自己的调用链中; 由共享代码运行的调用( 一个全应用程序发送器上的收听器) 所以不要在那里读它.
-   **在启动时启动背景工作( E)`onApplicationBootstrap`永远不要懒散 从内心 请求.** 请求内创建的 Async 资源( 计时器、 承诺链、 队列排出) a 处理器从第一次使用开始)保留该请求的背景,包括其主要内容或缺乏 一个.
-   排除路线 `app.setGlobalPrefix(prefix, { exclude })` 也通过中间软件( e2e) 测试这个.
-   `@astram/guard/internal` (仅使用框架)还输出只读 `insideRequest()`数字 : `true` 在通过中间器件的请求中, 无论有没有本金. `@astram/agent`是因为 已审计的获取器使用它拒绝来自 `@Public()` 并拒绝了请求.
-   **唯快报.** `currentRequestPrincipal` 证明在 `@nestjs/platform-express`; 快捷为 在它拥有自己的e2e测试之前不支持.
-   **只有巢穴路线.** 持枪者由一个巢穴中间器件打开,所以直接挂载在 hTTP 适配器( 在 Nest 路由之外) 运行“ 在请求之外 ” : `insideRequest()` 实值 `false` 财务报告和审定财务报表 `@astram/agent`是因为 `createAuditedFetch` 将预定的工作分支放在那里(应用程序必须到此为止) 提供服务器持有的租户)。 在 Nest 处理器或启动的任务中保留连接器代码 .
-   仅在内存中:请求路径(Shield #12)中没有添加数据库或已读的 Redis .

## 文件共享端口符 (P)`SHIELD_FILE_SHARE`,GAPS#57 (中文(简体) )

`src/module/shield-tokens.ts` 宣布该港口为警卫,绝不进口身份(ADR-0003); `@astram/identity` 按要求绑定 光谱 `docs/features/file-share-port/SPEC.md` v1, ADR- 0040 (英语) 增编(2026-11-03).

-   输出 : `SHIELD_FILE_SHARE` 联合国 `Symbol`,没有身份限制, `FileSharePort` (单位:千美元)`shareWithRole`, (中文(简体) ), `unshare`, (中文(简体) ), `revokeForParent`, (中文(简体) ), `listForParent`, (中文(简体) ), `reconcileFile`没有演员, 租户、业主或公司的论点), `FileShareParent` (单位:千美元)`{ typeKey, id }`, (中文(简体) ), `FileShareResult` (单位:千美元)`{ created, effective, missing }`, (中文(简体) ), `FileShareError`, (中文(简体) ), `FILE_SHARE_ERROR_CODES`, (中文(简体) ), `FileShareErrorCode`。 。 。 .
-   `FileShareError(code)` 仅取代码,所以其信息从不带id、文件名或 表格显示: `file_share_invalid` 400个 `Invalid file share request.`, (中文(简体) ), `file_share_not_found` 404 (韩语) `Not found.`, (中文(简体) ), `file_share_denied` 403 (韩语) `Not permitted.`, (中文(简体) ), `file_share_unavailable` 第503条 `File sharing is unavailable.`; 未知代码变为 `file_share_unavailable`。 。 。 .
-   移徙 `1710000000126-AddRecordShareSource.cjs` 添加源列 (单位:千美元)`rs_source_type_key`, (中文(简体) ), `rs_source_record_uuid`, (中文(简体) ), `rs_source_operation`, (中文(简体) ), `''` - 股权, `ck_rs_source_complete`, (中文(简体) ), `uq_rs_grant_source` (替换) `uq_rs_grant`和 `idx_rs_source`· ; `down` 当端口行存在时拒绝.
-   `RecordShareWriter`: 拥有者 `unshare` 只删除所有者制作的行并拒绝翻转 仅匹配端口行 `ShareNotPermittedError(SHARE_MANAGED_BY_LINKED_RECORD)` (单位:千美元)`This share is managed by a linked record.`); 列表行(`RecordShareRow`携带源字段; `listSharesForAuthorizedRecord` 列出一个记录的股票 不受所有者约束, 对于一个呼叫者 已经证明权威 `decide()` (身份是存储文件管理员列表).

## 同伴依赖关系(ADR-0023§2)

`@astram/guard` **对等依赖** 在主机运行时间,所以消费者 完全拥有 一份(单份) `reflect-metadata` 单通/DI注射器:

```
@nestjs/common ^11 · @nestjs/core ^11 · reflect-metadata ^0.2 · rxjs ^7
```

这些也是 `devDependencies` 在这里,软件包会本地化 + 测试 . `@astram/core` 是真实的(工作空间) **依赖性**。 。 。 .

## 图标

```bash
pnpm --filter @astram/guard build   # tsc -p tsconfig.build.json (emits dist + .d.ts)
pnpm --filter @astram/guard lint    # eslint
pnpm --filter @astram/guard test    # vitest run (guard unit + boot-pool + forRoot e2e)
```

## 页:1

-   **常见JS** 当地(`"type": "commonjs"`),用于雀巢JS装饰机+ `reflect-metadata` DI型号. 复发根和 `@astram/core` 保持无害环境管理/节点; 覆盖范围为此软件包(参见 `tsconfig.json`) (中文(简体) ).
-   核心接合导入真实 `@astram/core` **枪管** (类型只) — Core's `exports` 仅显示地图 `"."`,因此子路径导入失败了节点解析. 这个 软件包的 tsconfig 清除了底部 `paths` 这样 `@astram/core` 解决 节点 模块工作空间同 Core 已建 `dist`。 。 。 .

## 常见问题

### @astram/guard 是什么？

Astram框架——执行后卫\+现实世界适配器\("手"\)\. 每个请求都经过一个全球性的逐一拒绝闸门\(ADR-0002\)、分类装饰器、靴子池主张\(ADR-0018\)、Root\(\)注册接头和DB/R

### 如何安装 @astram/guard？

在项目目录运行 npm install @astram/guard，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：rxjs（^7）、@nestjs/core（^11）、@nestjs/common（^11）、reflect-metadata（^0\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @astram/guard 支持 TypeScript 吗？

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

### @astram/guard 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @astram/guard 可以商用吗？

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

### @astram/guard 的下载量有多少？

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

### @astram/guard 还在维护吗？

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