@ 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 提供
undefinedHTTP 信件框架将占位符与真实的
贾森 {} 身体,它仍然是签名的数据。 现有客户端无需更改. 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的切入点,包括申报 两个模块系统.
安装
npm install @bsv/auth-express-middleware @bsv/sdk express
Express是一种对等依赖,所以中间软件使用应用程序的单相
快跑时间和类型图. 这可防止重复的快递设施
从制作 AuthRequest 或返回的与
应用程序的路由类型.
基本用途
在认证前分析请求主体, 因此所签名的有效载荷包含 您的路径得到的相同值 :
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 不被视为握手交通.
选项
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 重置内容
禁止回应内容; 警卫在签署前拒绝, 而不是
让客户端丢弃签名字节 。 普通路线保持他们现有的快车行为.
警卫提供运输边界,而不是根向政策,共享 数据库、访问策略或索引投影适配器。 这些组成部分必须是: 一起安装和测试。 见 基础协调指南 编辑 编译接口示例。 。 。 .
横向规模的服务
默认 SessionManager 是进程本地化的。 使用共享
AsyncSessionManager 当负载平衡器可以引导握手和
对不同实例的认证请求 :
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;批准按准确的会话键入非会话和
身份,而不仅仅是身份 粘接路由不能代替
可替换实例时共享状态 .
证书
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 密码
运行时间导出 :
createAuthMiddlewareExpressTransport
出口类型 :
AuthMiddlewareOptionsAuthRequestAuthTransportLimitsCertificateApprovalStore
运行时批准存储导出 :
InMemoryCertificateApprovalStoreLogLevel
见 API.md (英语) 用于生成的签名.
发展
pnpm typecheck
pnpm lint
pnpm format:check
pnpm test:coverage
pnpm pack:check
pack:check 建立和验证无害环境管理和共同JS中准确的npm沥青球
消费者探测器,加上特快4号和5号的经真实认证的请求
遗留和当前 SDK 客户端。 测试不重建包作为副作用.
规格
许可证
当前 TS Stack 更改根据 Open BSV 许可证版本 6 获得许可; 参见
LICENSE.txt (英语)。该软件包还保留了统一前代码
在开放BSV许可证版本4下. 补给者必须保留
第三次议会 NoTICES.md 和适用的文本在
LICENSES/。 。 。 .
守护的响应和替换者拥有自己的字节快照,包括节点
Buffer 投入。 后续调用器突变不会改变所选择的字节
签名或排队。 持久的警备回调仍然必须检查当前应用程序
授权和同步排序; 拥有的字节不提供该权限.
SDK4 热补丁对等要求
SDK4 对等替代开始于 @bsv/sdk ^4.0.1,恢复数字
钱包结果和遗留线条相容性。 现有的SDK2/3替代品和
下限不变。 SDK4 用户应安装 4. 0.1 个热补丁; 不
需要应用程序-wallet线或数据迁移.