rblake2320/bpc-protocol

# BPC -- 绑定对凭证 一种请求认证协议，其中每个 API 调用都经过设备签名、配对验证、密钥锁定和防重放保护。 ## 它是什么 静态 API 密钥是一个单一字符串，任何持有它的人都可以获得完全访问权限。它们会被提交到代码仓库、在日志中泄露、被供应链攻击窃取，并且可以被无限重放。一旦 API 密钥泄露，攻击者就拥有与合法客户端相同的访问权限——而你甚至可能永远不会知道。 BPC 用一种多因素、逐请求签名的协议取代了静态密钥。每个客户端生成一个设备绑定的 ECDSA 密钥对（通过 Web Crypto API 设置为不可导出），通过显式的配对过程向服务器注册，并使用私钥、用户选择的密钥、新鲜随机数和时间戳对每个请求进行签名。被盗的凭证在没有设备密钥、密钥和新鲜随机数窗口的情况下毫无用处——必须同时具备所有条件。 ## 5 层防护 | 层级 | 作用 | 防御内容 | |-------|-------------|---------------| | 设备绑定密钥 | 通过 Web Crypto API 以 `extractable: false` 生成的 ECDSA P-256 密钥对 | 被盗密钥在另一设备上使用——没有私钥，就没有有效签名 | | 显式配对注册表 | 每个客户端必须在发出请求之前单独注册和审批 | 未知调用者、枚举攻击、未授权访问 | | 用户选择的密钥 | 通过 HMAC 派生混入每个签名中的密钥——永远不会以明文形式存储或传输 | 被盗密钥 + 被盗设备——攻击者仍然缺少密钥 | | 防重放保护 | 每个请求使用唯一随机数和 60 秒时间戳窗口 | 捕获的请求在之后重放——随机数已被使用，时间戳已过期 | | 行为异常引擎 | 跟踪未知配对探测、签名失败、重放尝试、过期时间戳 | 探测、暴力破解、协调攻击模式 | ## 快速开始 ``` cd examples/full-stack npm install && npm start ``` 这将启动一个受 BPC 保护的 Express 服务器和一个执行注册、配对和签名请求的客户端。 ## 安装 ``` npm install @bpc/server # server verification middleware npm install @bpc/client-sdk # client signing SDK ``` 两个包都依赖于 `@bpc/core`（会自动安装）。 ## 服务器用法 ``` import express from 'express'; import { PairRegistry, ServerNonceStore, AnomalyEngine, verifyBPCRequest } from '@bpc/server'; const app = express(); const registry = new PairRegistry(); const nonceStore = new ServerNonceStore(); const anomaly = new AnomalyEngine(); app.use(async (req, res, next) => { const result = await verifyBPCRequest({ pairId: req.headers['x-bpc-pair-id'] as string, signature: req.headers['x-bpc-signature'] as string, signedData: req.headers['x-bpc-signed-data'] as string, method: req.method, path: req.path, }, registry, nonceStore, anomaly); if (!result.ok) return res.status(401).json({ error: result.error }); next(); }); ``` ## 客户端用法 ``` import { BPCClient } from '@bpc/client-sdk'; import { generateKeypair, hashSecret } from '@bpc/core'; // After pairing (see spec for full flow): const client = new BPCClient({ serverUrl: 'https://api.example.com', pairId: 'pair_a1b2c3d4e5f6g7h8', keypair: myKeypair, secret: 'mySecret', }); const response = await client.fetch('/api/data'); ``` ## 架构 ``` packages/ core/ Crypto primitives, canonical payload, nonce generation, HMAC server/ Pair registry, nonce store, anomaly engine, verification pipeline client-sdk/ BPCClient with automatic request signing and fetch wrapper ``` - **`@bpc/core`** -- 共享的加密函数（ECDSA 密钥生成、签名、验证、HMAC 派生、规范化）。框架无关，可在浏览器和 Node.js 中运行。 - **`@bpc/server`** -- 验证管道（`verifyBPCRequest`）、配对注册表、服务端随机数存储和行为异常引擎。框架无关——可搭配任意 HTTP 框架使用。 - **`@bpc/client-sdk`** -- 处理请求签名和头部构建的 `BPCClient` 类。提供自动附加 BPC 头部的 `fetch()` 封装。 ## 安全属性 以下属性由协议强制执行并由测试套件验证。声明范围限定于**正确实现、正确部署、正确运行**的系统。 | 属性 | 声明 | 保障方式 | |----------|-------|--------------| | 凭证隔离 | 被盗的 API 密钥无法从其他设备使用 | 以 `extractable: false` 生成的 ECDSA 私钥——无法被 JavaScript 导出或被受损的应用层提取 | | 密钥绑定 | 被盗的设备在没有用户密钥的情况下无法使用 | 每个请求携带一个从 `hashSecret(secret)` 派生的 HMAC，混入签名载荷中。服务器独立于 ECDSA 签名进行验证。 | | 重放抵抗 | 捕获的有效请求无法被重放 | 每请求加密随机数（首次使用后即被消耗）+ 60 秒时间戳窗口。两者必须同时有效。 | | 请求体完整性 | 有效签名无法被移植到不同的请求体上 | `body_hash`（原始请求体的 SHA-256）被包含在签名的规范化载荷中。服务器计算收到请求体的哈希值并进行比对。 | | 轮换真实性 | 密钥轮换不能仅由持有配对 ID 的攻击者发起 | 轮换载荷（`old_pair_id`、`new_pub_jwk`、`timestamp`、`purpose`）由现有设备私钥签名。服务器在接受新密钥之前验证签名和所有绑定字段。 | | 行为检测 | 重复探测、签名失败和重放尝试被跟踪 | 异常引擎记录每个配对的威胁分数。运维人员可以基于分数阈值进行管控。 | **BPC 不做以下声明：** - 防护完全受损的主机（操作系统级密钥提取或密钥窃取超出协议范围） - 硬件认证——`extractable: false` 标志防止 JS 层提取；TPM/Secure Enclave 绑定需要 WebAuthn 认证（计划于 v0.2.0） - 抗量子性——ECDSA P-256 在密码学相关的量子计算机出现后易受 Shor 算法攻击。NIST 将在 2030 年前弃用 P-256。在此期限之前计划迁移到 ML-DSA（CRYSTALS-Dilithium，FIPS 204）。 ## 状态 v1.0.0——生产级参考实现。专利申请中。 对该代码库进行了三轮独立的对抗性测试，发现并解决了以下问题：密钥 HMAC 执行漏洞、轮换载荷字段绑定、示例服务器中的请求体哈希执行、HMAC 比较时序、Redis 速率限制器中的 `Math.random()`。全部 57 个测试（core、server、client-sdk）均已通过。 设备密钥上的 `non-extractable` 标志可防止 JavaScript 层的密钥提取。对于硬件级绑定（TPM/Secure Enclave），需要通过 WebAuthn 进行平台认证，计划于 v0.2.0 实现。完整协议规范请参阅 `spec/bpc-spec-v1.md`。 ## 路线图（v0.2.0） - 持久化配对注册表（基于数据库，重启后保留） - 多实例随机数存储（基于 Redis，适用于负载均衡部署） - 通过 WebAuthn 实现硬件认证（TPM/Secure Enclave 密钥绑定） - ML-DSA 迁移路径（后量子，2030 年 NIST 期限之前） ## 致谢 由 R. Blake 构思和设计。

标签：API安全, API认证, Bound Pair Credentials, BPC, ECDSA, Express, GNU通用公共许可证, HMAC, IP 地址批量处理, JSONLines, JSON输出, MITM代理, Node.js, nonce, P-256, StruQ, Web Crypto API, Web安全, 反凭证盗用, 反暴力破解, 反枚举, 多因素认证, 抗重放攻击, 无静态密钥, 时间戳, 显式配对注册, 用户自选密钥, 网络安全, 自动化攻击, 蓝队分析, 行为异常检测, 设备密钥对, 设备绑定, 请求签名, 防API密钥滥用, 防供应链攻击, 防凭证泄露, 防日志泄露, 防重放, 隐私保护, 零信任, 非可导出密钥