# @bsv/auth-express-middleware 中文文档

规范地址：https://npmcn.com/package/%40bsv/auth-express-middleware/

版本：2\.3\.0
npm 元数据更新时间：2026-10-28T01:21:19.494Z
中文译文更新时间：2026-11-08T17:23:41.472Z
软件包许可：SEE LICENSE IN LICENSE\.txt

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

原始 npm 页面：https://www.npmjs.com/package/%40bsv/auth-express-middleware
原文对照：https://npmcn.com/package/%40bsv/auth-express-middleware/?lang=original
项目主页：https://github.com/bsv-blockchain/ts-stack/tree/main/packages/middleware/auth-express-middleware#readme
源码仓库：https://github.com/bsv-blockchain/ts-stack

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

- 包体积（解压后）：517 kB，28 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：express \>=4\.18\.0 \<6，@bsv/sdk ^2\.8\.5 \|\| ^3\.0\.0 \|\| ^4\.0\.1，@types/express \>=4\.17\.0 \<6
- 首次发布：2025-01-06T18:31:52.246Z
- 最新版本发布：2026-10-28T01:21:19.064Z
- 近 30 天下载量：19797（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：45（近 12 个月 23 个）

## 中文简介

BSV 区块链相互认证快件

## 安装

```sh
npm install @bsv/auth-express-middleware
```

也可以使用：`pnpm add @bsv/auth-express-middleware`、`yarn add @bsv/auth-express-middleware`、`bun add @bsv/auth-express-middleware`

## README

# @ bsv/ auth- sext- middle 软件

为 BRC- 103 提供中间软件, 对等者相互认证 BRC-104 HTTP运输. 它处理公共握手端口,验证 经认证的申请请求、签名回复和可选交换 可核查的证书.

未公布的2.3.0候选人在 BRC-104 签名. 现有路线保留其运输行为、同级范围以及 线条格式. 明确安装需要持久发送栅栏的路线 `guardAuthenticatedResponse`;不需要正常的消费者迁移 回应。 候选人还保留了用于开发的唯一限速器 本地 HTTP 集成装置.

当前发布保留了跨支持的 JSON 的 BRC- 100 字节字段 字节阵列形式,在同步工作前快取握手信息 拒绝无法在不失去语义的情况下表达的解析体 . 2.2.6版本还保留了Express 4上的无体认证请求 JSON 解析器可以提供一个空对象占位符,其中 Express 5 提供 `undefined`HTTP 信件框架将占位符与真实的 贾森 `{}` 身体,它仍然是签名的数据。 现有客户端无需更改. 2.2.7版也一样 保存快递的一角 `res.set({ ...headers })` 超载,包括 支付挑战头。 包装器转发原参数计数; Express保留了自己的标题验证和强制,并签名回复 保留其现有的BRC-104代表.

2.2.8版本需要SDK 2.8.5并去除中间软件头大小和 头数上限. `createAuthMiddleware` 配置它的对等点 `maxGeneralPayloadBytes: null`,避免间接的 SDK 一般信息 在保留元数据和签名验证的同时,对收到的信头设定上限. 收到的信头不包括在 `maxRequestBytes`,该定义仍然适用于 手握/平方数据并编码请求机构。 中间的软件保存所有 bRC- 104 签名和验证所选标题字节, 而不是拒绝 a 由于追加了预算而收到付款。 HTTP 服务器, CDN, 代理和WAF配置自有运输头限制 。 配置这些层 用于最大支持的付款证明并验证整个路径.

签名信头格式错误或重复, 信头值不安全, 认证 失败和无效的签名仍然失败验证. 机构预算、超时 和重放保护 仍然分开。 消费较大签名答复的客户 需要匹配能力; SDK 2.8.5 将标题限制提高4x. 没有BRC100电话, 需要电线或钱包数据迁移。 来源出版物是单独的 保护释放步骤.

## 所需资源

-   22号节点或更新
-   4.18快车或更新车,包括快车5
-   A BRC- 100 个 `WalletInterface`

一揽子船舶原生无害环境管理和共同JS的切入点,包括申报 两个模块系统.

## 安装

```bash
npm install @bsv/auth-express-middleware @bsv/sdk express
```

Express是一种对等依赖,所以中间软件使用应用程序的单相 快跑时间和类型图. 这可防止重复的快递设施 从制作 `AuthRequest` 或返回的与 应用程序的路由类型.

## 基本用途

在认证前分析请求主体, 因此所签名的有效载荷包含 您的路径得到的相同值 :

```ts
import express from 'express'
import { PrivateKey, ProtoWallet } from '@bsv/sdk'
import { createAuthMiddleware, type AuthRequest } from '@bsv/auth-express-middleware'

const wallet = new ProtoWallet(PrivateKey.fromRandom())
const app = express()

app.use(express.json())
app.use(createAuthMiddleware({ wallet }))

app.get('/private', (req: AuthRequest, res) => {
  res.json({ identityKey: req.auth?.identityKey })
})
```

默认需要认证 。 没有BRC-103/104的请求 收到认证 `401`与 `allowUnauthenticated: true`,它们继续 与 `req.auth.identityKey === 'unknown'`。 。 。 .

准确 `/.well-known/auth` 路径总是可以通过中间软件到达 因为它确定了受保护路线所用的会话。 类似的前缀 例如 `/.well-known/auth/extra` 不被视为握手交通.

## 选项

```ts
const auth = createAuthMiddleware({
  wallet,
  allowUnauthenticated: false,
  sessionManager,
  certificatesToRequest,
  onCertificatesReceived,
  certificateApprovalStore,
  logger,
  logLevel: 'error',
  transportLimits: {
    requestTimeoutMs: 30_000,
    maxPendingRequests: 1_000,
    maxRequestBytes: 8 * 1024 * 1024,
    maxResponseBytes: 8 * 1024 * 1024
  }
})
```

-   `wallet` 需要并且必须执行 BRC-100 钱包接口.
-   `allowUnauthenticated` 默认为 `false`。 。 。 .
-   `sessionManager` 接受SDK的游戏 `SessionManager` 或一个 `AsyncSessionManager`。 。 。 .
-   `certificatesToRequest` 询问允许证书类型的对等点,以及 字段。 遗留 v0. 1 形状并不断言每个列出的类型或字段 已提供; 检查 `onCertificatesReceived` 在批准之前.
-   `onCertificatesReceived` 可能是同步或同步的。 它接收 `(senderPublicKey, certificates, req, res, approve)`当此调用时 配置后, 受保护的请求仍然被屏蔽, 除非召回 明确呼吁 `approve()`。通常未经批准返回是 拒绝并最终生成所配置的认证超时. 通话 `approve` 不止一次没有效果。 召回必须验证 每个应用程序特定证书政策,包括所需类型和 字段完整性,在批准前.
-   `certificateApprovalStore` 与确切的BRC-103对照的核准记录 非会话和身份。 默认 `InMemoryCertificateApprovalStore` 仅当握手时才合适 保护请求仍是一个过程。 使用 `onCertificatesReceived` 必须注入共享存储并保留对 至少有相应的会话寿命。 存储失败和每次 准确布尔以外的判决 `true` 失败关闭.
-   `logger` 财务报告和审定财务报表 `logLevel` 启用结构化生命周期日志。 认证 信头、证书机构、签名、响应机构和钱包对象 未登录.
-   `transportLimits.requestTimeoutMs` 将握手、核查、, 证书,和响应签名状态。 它默认为30秒.
-   `transportLimits.maxPendingRequests` 每个进程待定的协议 状态。 默认为 1 000 且无法关闭 `503` 在容量.
-   `transportLimits.maxRequestBytes` 绑定握手普通数据并编码 请求体在对等处理前的工作,不包括收到的HTTP头. 默认为8 MiB. 准备吧 `-1` 只有当嵌入服务执行相当的请求预算时.
-   `transportLimits.maxResponseBytes` 缓冲的应用程序响应 BRC-104 签名,包括转交给 `res.sendFile`默认为 8 MIB 无法用签名关闭 `413` 反应。 准备吧 `-1` 仅在 嵌入服务执行相应的响应预算.

启动时无效的选项类型失败 .

## 最后认证的答复

`guardAuthenticatedResponse(res, guard)` 是一个服务选择的边界 在同步响应后必须重新检查授权或输出资格 签名。 在发送回复之前安装在经认证的处理器中 。 这个 拒绝未经认证的请求、重复登记和逾期登记.

警卫收到一个拥有的候选人 里面有经过认证的来电者, BRC-104 运输请求 ID, 尝试号, 状态, 响应头和正文 字节。 逻辑应用操作ID仍然单独存在. 标题包括 BRC-104认证元数据和规范内容长度;节点可添加其内容 普通日期/连接元数据。 BRC-104的签名覆盖面仍然存在 状态/正体和所选标题规则;普通 CORS/cache 标题不会变成 密码签名只是因为他们出现在这张快照里 它可能会等待 获取应用程序的耐用发送栅栏。 拿着围栏时, 重新检查当前授权和每个披露的目标,然后调用 `enqueue()` 同步进行. 回调队列通过节点原生地已经签名的字节 HTTP响应方法. 它从不签署 等待数据库 或授权 打电话的人自己。 一个处理器级锁 `res.send()` 不够,因为 签字的事以后再说 应用程序的作者必须使用配对的栅栏, 将作者纳入其他进程.

如果候选人僵持不下,则以 `statusCode`, (中文(简体) ), `headers` 财务报告和审定财务报表 `body: Uint8Array` 不打电话 `enqueue()`中间软件 丢弃第一个签名的候选者, 并签名替换相同者 请求和会话。 警卫又跟着我跑 `attempt: 1`; 它必须重新检查 当前访问, 并排入此响应或关闭失败 。 只有一个替补 允许。 其正体加上UTF-8标题名称和值最多可达64个KiB,以及 其身体还必须符合配置的响应-身体限制。 包括所需的遥感中心, 明确显示服务能力和误标头:已丢弃候选人 信头没有被继承 。 绝不将机密候选人信头复制到 公共错误.

签名尝试和警卫收购都共享配置的响应 暂停 。 断接或超时中止提供的信号, 关闭响应 并保留了无效的调用。 警卫必须被取消 释放自己获得的资源。 呼叫两次,呼叫后 守护返回, 无决定返回, 或在字节列后失败 无法附加一个未签名的后退。 不成功可能关闭连接 HTTP出错;客户端应该通过其持久操作协议来恢复.

此模式支持本地节点 HTTP/1 响应, 包括 HTTPS, 没有 压缩、延迟编码或替换响应/标题方法 或认证后。 不支持的构成被拒绝 。 配置 在这样的中间软件之外运行,并限定完整的运输堆栈. `content-encoding` 可能缺席或 `identity`; 转让框架和精确度 内容长度属于本地交通。 守备反应发出 没有 Express 的 ETag 自动 ETag , 有条件的响应 或身体转变。 总部、204、205和304的答复必须已经空了 签名的尸体。 特别是, [HTTP 205 重置内容](https://www.rfc-editor.org/rfc/rfc9110.html#name-205-reset-content) 禁止回应内容; 警卫在签署前拒绝, 而不是 让客户端丢弃签名字节 。 普通路线保持他们现有的快车行为.

警卫提供运输边界,而不是根向政策,共享 数据库、访问策略或索引投影适配器。 这些组成部分必须是: 一起安装和测试。 见 [基础协调指南](https://npmcn.com/docs/guides/root-eviction-coordination.md) 编辑 [编译接口示例](https://npmcn.com/docs/guides/compiled-package-examples.md)。 。 。 .

## 横向规模的服务

默认 `SessionManager` 是进程本地化的。 使用共享 `AsyncSessionManager` 当负载平衡器可以引导握手和 对不同实例的认证请求 :

```ts
import type { AsyncSessionManager } from '@bsv/sdk'

const sessionManager: AsyncSessionManager = {
  async addSession(session) {
    await sessions.put(session.sessionNonce, session)
  },
  async updateSession(session) {
    await sessions.put(session.sessionNonce, session)
  },
  async getSession(identifier) {
    return await sessions.get(identifier)
  },
  async removeSession(session) {
    await sessions.delete(session.sessionNonce)
  },
  async hasSession(identifier) {
    return (await sessions.get(identifier)) !== undefined
  }
}

app.use(createAuthMiddleware({ wallet, sessionManager }))
```

后置商店必须保存 SDK 的会话语义并使用 适当的原子化、过期、可用性和加密控制。 若为 `onCertificatesReceived` 配置,同样的复制品也必须共享 `certificateApprovalStore`;批准按准确的会话键入非会话和 身份,而不仅仅是身份 粘接路由不能代替 可替换实例时共享状态 .

## 证书

```ts
app.use(
  createAuthMiddleware({
    wallet,
    certificatesToRequest: {
      certifiers: ['<compressed-certifier-public-key>'],
      types: {
        '<base64-certificate-type>': ['firstName']
      }
    },
    async onCertificatesReceived(senderPublicKey, certificates, req, res, approve) {
      await authorizeDisclosedFields(senderPublicKey, certificates)
      approve()
    }
  })
)
```

该申请仍负责批准政策、证书 撤销检查,安全存储所披露的数据。 需要缺失 证书以稳定公差失败 。 内部钱包,签名,和 证书处理器出错仅通过可选日志登录,并且是 未返回呼叫者.

已认证 `res.sendFile()` 反应保存快递 `root`, (中文(简体) ), `dotfiles`, (中文(简体) ), `start`, (中文(简体) ), `end`,以及 `headers` 安全相关选项 文件被缓冲用于签名。 需要相对路径 `root`; 转弯和 锁链从根部外逃出 其他发送文件缓存和范围 谈判选择仍然是申请的责任.

反应包还缓冲器 `write()`, (中文(简体) ), `writeHead()`, (中文(简体) ), `flushHeaders()`, (中文(简体) ), 数据转交给 `end()` 因此标准节点/ Express 路径无法逃脱 签名的回复。 直接状态和头状态在签署前被俘. 流出仍为受限缓冲:本议定书必须知道完整的正文 在它可以签署它之前.

## 公共服务、中央应急培训和社区支助方案

此软件包不强制CORS, CSP, 或原产地许可列表 。 这是 故意:认证端点可能服务于浏览器应用程序,WUI,移动客户端,以及 其他跨越许多领域的呼叫者。 在应用程序中配置这些政策 或边缘层 :

-   当公共服务是服务时,默认情况下保留公共服务访问 合同.
-   提供由操作员配置的原产地许可列表作为选入限制.
-   永远不要结合 `Access-Control-Allow-Origin: *` 与认证的CORS.
-   显示所需 `x-bsv-auth-*` 浏览器客户端的响应头.
-   处理 `OPTIONS` 在支持浏览器飞行前进行认证之前.
-   将 CSP 作为浏览器文档政策; API 响应一般需要 CORS 而运输控制.

在此中间软件中不要硬码一个部署特定域列表 .

## 错误行为

公用错误是故意稳定的,不包括内部例外 信件 :

| 状态 | 代码 | 含义 |
| --- | --- | --- |
| 400个 | `ERR_AUTH_MALFORMED` | 无效的握手或认证信头 |
| 400个 | `ERR_CERTIFICATES_REQUIRED` | 未提供所需证书 |
| 401 (中文(简体) ) | `UNAUTHORIZED` 编号 : `ERR_AUTH_FAILED` | 签名、会话或 HMAC 验证失败 |
| 408 (简体中文) | `ERR_AUTH_TIMEOUT` | 限定的协议步骤已超时 |
| 500个 | `ERR_INTERNAL_SERVER_ERROR` | 内部认证处理失败 |
| 500个 | `ERR_RESPONSE_SIGNING_FAILED` | 无法签名验证的回复 |
| 第503条 | `ERR_AUTH_CAPACITY` | 待发状态达到所配置的极限 |

## 安全说明

-   使用 HTTPS. 相互认证提供了完整性和身份,而不是 对所有HTTP元数据和内容保密.
-   每个请求路径安装中间软件; 响应方法为 临时包裹,同时签名验证的回复.
-   别相信 `req.auth.identityKey === 'unknown'` 作为授权.
-   使用共享会话状态进行多事件部署 .
-   保持超时、响应大小和能力限制并进行监测 `408`编号 :`413`编号 :`503` 费率.
-   在身份认证后单独验证授权.
-   BRC- 104 v0. 1 签名方法、 路径名、 查询、 所选标题和正文; 它 已经 **没有** 签署计划/授权`Host`, (中文(简体) ), `Cookie`,转发信头, 或任意的标准标题。 这是故意的,因为浏览器和 网页库在签名时往往无法安全地观察这些值. 不要从这些省略的价值中选择租户或授予权。 压住 将任何与安全有关的价值与 精确签名 `x-bsv-*` 或者说 `Authorization` 字段。 使用不同的服务器 当虚拟当局是单独的安全主机时,身份密钥。 A 类 有效签名只认证此已记录子集, 而不是完整 浏览器或代理上下文 .
-   已签名的回复信头同样仅限于: `x-bsv-*` (不包括 (auth 信封)和 `Authorization`中不包含经认证的决定 未签名 `Location`, cookie,内容类型,或其他响应元数据.
-   解析 JSON、 URL 编码、 文本和二进制机构及其匹配的快递 在认证前解析器 。 URL 编码对象必须只包含精确的字符串 字段; 嵌入式/阵列式强制和无支持的非空体会失效.
-   保持请求体限和正常快车加固到位.
-   回复或连接已后延迟认证失败 解决后就包含在该请求中,从未写成第二次 快速响应.

## API 密码

运行时间导出 :

-   `createAuthMiddleware`
-   `ExpressTransport`

出口类型 :

-   `AuthMiddlewareOptions`
-   `AuthRequest`
-   `AuthTransportLimits`
-   `CertificateApprovalStore`

运行时批准存储导出 :

-   `InMemoryCertificateApprovalStore`
-   `LogLevel`

见 [API.md (英语)](https://npmcn.com/package/%40bsv/auth-express-middleware/API.md) 用于生成的签名.

## 发展

```bash
pnpm typecheck
pnpm lint
pnpm format:check
pnpm test:coverage
pnpm pack:check
```

`pack:check` 建立和验证无害环境管理和共同JS中准确的npm沥青球 消费者探测器,加上特快4号和5号的经真实认证的请求 遗留和当前 SDK 客户端。 测试不重建包作为副作用.

## 规格

-   [BRC-103:对等对等验证](https://github.com/bitcoin-sv/BRCs/blob/master/peer-to-peer/0103.md)
-   [BRC-104: BRC-103的HTTP运输](https://github.com/bitcoin-sv/BRCs/blob/master/peer-to-peer/0104.md)

## 许可证

当前 TS Stack 更改根据 Open BSV 许可证版本 6 获得许可; 参见 [LICENSE.txt (英语)](https://npmcn.com/package/%40bsv/auth-express-middleware/LICENSE.txt)。该软件包还保留了统一前代码 在开放BSV许可证版本4下. 补给者必须保留 [第三次议会 NoTICES.md](https://npmcn.com/package/%40bsv/auth-express-middleware/THIRD_PARTY_NOTICES.md) 和适用的文本在 [`LICENSES/`](https://npmcn.com/package/%40bsv/auth-express-middleware/LICENSES/)。 。 。 .

守护的响应和替换者拥有自己的字节快照,包括节点 `Buffer` 投入。 后续调用器突变不会改变所选择的字节 签名或排队。 持久的警备回调仍然必须检查当前应用程序 授权和同步排序; 拥有的字节不提供该权限.

## SDK4 热补丁对等要求

SDK4 对等替代开始于 `@bsv/sdk ^4.0.1`,恢复数字 钱包结果和遗留线条相容性。 现有的SDK2/3替代品和 下限不变。 SDK4 用户应安装 4. 0.1 个热补丁; 不 需要应用程序-wallet线或数据迁移.

## 常见问题

### @bsv/auth-express-middleware 是什么？

BSV 区块链相互认证快件

### 如何安装 @bsv/auth-express-middleware？

在项目目录运行 npm install @bsv/auth-express-middleware，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：express（\>=4\.18\.0 \<6）、@bsv/sdk（^2\.8\.5 \|\| ^3\.0\.0 \|\| ^4\.0\.1）、@types/express（\>=4\.17\.0 \<6）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bsv/auth-express-middleware 支持 TypeScript 吗？

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

### @bsv/auth-express-middleware 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bsv/auth-express-middleware 需要什么版本的 Node\.js？

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

### @bsv/auth-express-middleware 可以商用吗？

@bsv/auth-express-middleware 使用 SEE LICENSE IN LICENSE\.txt 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @bsv/auth-express-middleware 的下载量有多少？

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

### @bsv/auth-express-middleware 还在维护吗？

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