@travelclw/proof-protocol 0.1.1 → 0.2.0

package/README.md

@@ -1,65 +1,81 @@
-# @travelclw/proof-protocol
-
-无框架依赖的请求 Proof 协议实现。公共包只负责协议规范化、浏览器密钥存储与签名、Node.js 服务端验证；Axios、Alova、Nest Guard、业务路由、登录页面和 UI 由使用方实现。
-
-公共包不包含任何项目业务路径，不判断某个业务接口是否需要 Proof，也不包含或生成服务端密钥。
-
-## 安装
-
-```bash
-pnpm add @travelclw/proof-protocol
-```
-
-Node.js 服务端验证还需要安装兼容的 `jose`：
-
-```bash
-pnpm add jose@^5
-```
-
-## 入口
-
-- `@travelclw/proof-protocol`：协议常量、规范化、错误码和模式解析。
-- `@travelclw/proof-protocol/browser`：IndexedDB P-256 Key Store 和 Proof 签名。
-- `@travelclw/proof-protocol/node`：JWK 校验、Proof 验证和服务端配置解析。
-
-## 浏览器配置
-
-浏览器构建只读取：
-
-- `PROOF_REQUIRED=0|1`
-
-浏览器端不读取也不应获得任何服务端密钥。使用方需要为每个浏览器应用提供独立的 IndexedDB 名称。
-
-## Node.js 环境变量
-
-- `AUTH_PROOF_MODE=0|1|2` 或 `off|shadow|enforce`
-- `AUTH_PROOF_DEVICE_SESSION_SECRET`
-- `AUTH_PROOF_DEVICE_SESSION_TTL_SECONDS`
-- `AUTH_PROOF_TIME_TOLERANCE_SECONDS`
-
-服务端应在启动阶段调用 `resolveProofServerConfig()`：
-
-```js
-const { resolveProofServerConfig } = require('@travelclw/proof-protocol/node')
-
-const proofConfig = resolveProofServerConfig()
-```
-
-`AUTH_PROOF_MODE` 缺失时按 `enforce` 处理；只要模式不是显式 `off`，就必须由部署环境注入至少 32 个字符的独立 `AUTH_PROOF_DEVICE_SESSION_SECRET`，否则 `resolveProofServerConfig()` 立即抛错。它不读取通用 `SECRET`，也没有内置、示例或回退密钥。
-
-环境变量中的非空值优先于调用方代码配置。缺少 TTL、时间窗口或 shadow 开关时使用协议默认值；显式配置非法值会直接报错，不会静默回退。
-
-## 安全边界
-
-- 不要把 `.env`、真实密钥、Token、Cookie、私钥或生产配置提交到源码或发布到 npm。
-- `AUTH_PROOF_DEVICE_SESSION_SECRET` 只用于服务端设备会话摘要，不得暴露给浏览器。
-- 浏览器 P-256 私钥由 WebCrypto 创建并以不可导出 `CryptoKey` 保存到 IndexedDB。
-- 包只提供协议能力；会话存储、Redis 原子操作、Guard 策略和业务路由由使用方负责。
-
-## 发布内容
-
-npm 包只发布 `core`、`browser`、`node` 三个入口的 JavaScript、类型声明、README 和 LICENSE。测试、脚本、`.env`、`.npmrc` 与 `node_modules` 不进入发布包。
-
-## License
-
-MIT
+# @travelclw/proof-protocol
+
+无框架依赖的请求 Proof 协议实现。公共包只负责协议规范化、浏览器密钥存储与签名、Node.js 服务端验证；Axios、Alova、Nest Guard、业务路由、登录页面和 UI 由使用方实现。
+
+公共包不包含任何项目业务路径，不判断某个业务接口是否需要 Proof，也不包含或生成服务端密钥。
+
+## 安装
+
+```bash
+pnpm add @travelclw/proof-protocol@0.2.0
+```
+
+Node.js 服务端验证还需要安装兼容的 `jose`：
+
+```bash
+pnpm add jose@^5
+```
+
+## 入口
+
+- `@travelclw/proof-protocol`：协议常量、规范化、错误码和模式解析。
+- `@travelclw/proof-protocol/browser`：IndexedDB P-256 Key Store 和 Proof 签名。
+- `@travelclw/proof-protocol/node`：JWK 校验、Proof 验证和服务端配置解析。
+
+## 浏览器配置
+
+浏览器构建只读取：
+
+- `PROOF_REQUIRED=0|1`
+
+浏览器端不读取也不应获得任何服务端密钥。使用方需要为每个浏览器应用提供独立的 IndexedDB 名称。
+
+## Node.js 环境变量
+
+- `AUTH_PROOF_MODE=0|1|2` 或 `off|shadow|enforce`
+- `AUTH_PROOF_DEVICE_SESSION_SECRET`
+- `AUTH_PROOF_DEVICE_SESSION_TTL_SECONDS`
+- `AUTH_PROOF_TIME_TOLERANCE_SECONDS`
+
+服务端应在启动阶段调用 `resolveProofServerConfig()`：
+
+```js
+const { resolveProofServerConfig } = require('@travelclw/proof-protocol/node')
+
+const proofConfig = resolveProofServerConfig()
+```
+
+`AUTH_PROOF_MODE` 缺失时按 `enforce` 处理；只要模式不是显式 `off`，就必须由部署环境注入至少 32 个字符的独立 `AUTH_PROOF_DEVICE_SESSION_SECRET`，否则 `resolveProofServerConfig()` 立即抛错。它不读取通用 `SECRET`，也没有内置、示例或回退密钥。
+
+环境变量中的非空值优先于调用方代码配置。缺少 TTL、时间窗口或 shadow 开关时使用协议默认值；显式配置非法值会直接报错，不会静默回退。
+
+`verifyRequestProof()` 只负责验签、请求绑定和时间计算，过期/未来时间通过 `timeWarning` 返回；是否在 `enforce` 模式拦截、如何在 `shadow` 模式审计，以及如何用 Redis `SET NX EX` 原子消费 `jti`，由服务端适配层负责。
+
+## 安全边界
+
+- 不要把 `.env`、真实密钥、Token、Cookie、私钥或生产配置提交到源码或发布到 npm。
+- `AUTH_PROOF_DEVICE_SESSION_SECRET` 只用于服务端设备会话摘要，不得暴露给浏览器。
+- 浏览器 P-256 私钥由 WebCrypto 创建并以不可导出 `CryptoKey` 保存到 IndexedDB。
+- 同一浏览器应用的多个标签页共享同一个 IndexedDB 记录；`reset()` 会通过 `BroadcastChannel` 通知其它标签页清空内存中的进行中操作，并在每次读取/签名前重新核对 IndexedDB 当前 `kid`。不支持 `BroadcastChannel` 时仍以 IndexedDB 核对为准。
+- `proofKeyPromise` 只缓存进行中的密钥创建操作，不缓存已完成的密钥 Promise；标签页休眠或漏收广播时，下一次签名仍会从 IndexedDB 发现 Key 已轮换。
+- 包只提供协议能力；会话存储、Redis 原子操作、Guard 策略和业务路由由使用方负责。
+
+## 发布内容
+
+npm 包只发布 `core`、`browser`、`node` 三个入口的 JavaScript、类型声明、README 和 LICENSE。测试、脚本、`.env`、`.npmrc` 与 `node_modules` 不进入发布包。
+
+## License
+
+MIT
+
+## V2 Cookie 会话协议（2026-09-12，协调升级）
+
+调用方显式传入 `purpose: 'session' | 'ticket'` 后使用 `typ: ctx-proof+jwt`、`ver: 2`。session 从已签发 JWE 的受认证保护头读取 `psid`；服务端以已验证 sid 调用 `deriveProofSessionId(sid)` 比较。ticket 使用 ST 摘要 `sth`，浏览器必须提供此前注册的 `expectedKeyId`。
+
+V2 不使用 ath/qsh/bth/rid，不自动创建丢失的签名 key，不允许 PROOF_REQUIRED=0 静默跳过。普通受保护路由必须显式指定 V2 purpose，时间警告必须拒绝，jti 由服务端原子消费。省略 purpose 的历史 API 仅保留库级兼容，不作为 V2 服务端降级路径。
+
+前端应在登录授权前取得候选 key；授权服务器须将目标 origin/key 写入 ST，在验签前检查目标，在资格复核后比较原值并原子消费 ST，绑定成功后才返回 Cookie。
+
+`0.2.0` 包含 V2 协议实现。此前使用 `0.1.2` 配合 pnpm patch 的项目升级时，应移除对应补丁并锁定正式版本。前后端必须协调升级，旧登录凭据需要重新登录；不可将旧 Proof 作为 V2 校验失败后的回退。
+
+独立浏览器验收运行 `node tools/browser-v2-check.cjs`，打开输出的本机地址，点击运行；只使用测试 IndexedDB 和合成会话，结束后关闭进程。

package/browser.d.ts

@@ -1,40 +1,42 @@
-export type RequestProofPublicKey = {
-  kty: 'EC'
-  crv: 'P-256'
-  x: string
-  y: string
-}
-
-export type RequestProofRegistration = {
-  keyId: string
-  publicKey: RequestProofPublicKey
-}
-
-export type BrowserProofInput = {
-  token: string
-  audience: string
-  method: string
-  path: string
-  requestUri: string
-  body?: unknown
-  contentType?: unknown
-  hasBody?: boolean
-  requestId?: unknown
-}
-
-export type BrowserProofClient = {
-  reset(): Promise<void>
-  getRegistration(): Promise<RequestProofRegistration>
-  tryGetRegistration(): Promise<RequestProofRegistration | null>
-  createProof(input: BrowserProofInput): Promise<string>
-  tryCreateProof(input: BrowserProofInput): Promise<string>
-}
-
-export function calculateKeyId(publicKey: JsonWebKey): Promise<string>
-export function createProofRequestId(): string
-export function createBrowserProofClient(options: {
-  databaseName: string
-  storeName?: string
-  recordId?: string
-  required: () => unknown
-}): BrowserProofClient
+export type RequestProofPublicKey = {
+  kty: 'EC'
+  crv: 'P-256'
+  x: string
+  y: string
+}
+
+export type RequestProofRegistration = {
+  keyId: string
+  publicKey: RequestProofPublicKey
+}
+
+export type BrowserProofInput = {
+  purpose?: 'session' | 'ticket'
+  expectedKeyId?: string
+  token: string
+  audience: string
+  method: string
+  path: string
+  requestUri: string
+  body?: unknown
+  contentType?: unknown
+  hasBody?: boolean
+  requestId?: unknown
+}
+
+export type BrowserProofClient = {
+  reset(): Promise<void>
+  getRegistration(): Promise<RequestProofRegistration>
+  tryGetRegistration(): Promise<RequestProofRegistration | null>
+  createProof(input: BrowserProofInput): Promise<string>
+  tryCreateProof(input: BrowserProofInput): Promise<string>
+}
+
+export function calculateKeyId(publicKey: JsonWebKey): Promise<string>
+export function createProofRequestId(): string
+export function createBrowserProofClient(options: {
+  databaseName: string
+  storeName?: string
+  recordId?: string
+  required: () => unknown
+}): BrowserProofClient