@travelclw/proof-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 travelclw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @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`
+- `AUTH_PROOF_SHADOW_BLOCK_MISSING_PROOF=0|1`
+
+服务端应在启动阶段调用 `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

package/browser.d.ts

@@ -0,0 +1,40 @@
+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

package/browser.js

@@ -0,0 +1,255 @@
+'use strict'
+
+const {
+  canonicalizeBody,
+  canonicalizeQuery,
+  isRequestProofRequired,
+  isRequestProofSetupError,
+  normalizePath,
+} = require('./core')
+
+const bytesToBase64Url = bytes => {
+  let binary = ''
+  bytes.forEach(byte => {
+    binary += String.fromCharCode(byte)
+  })
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '')
+}
+
+const textToBase64Url = value => bytesToBase64Url(new TextEncoder().encode(value))
+
+const getWebCrypto = () => {
+  const webCrypto = globalThis.crypto
+  if (!webCrypto?.subtle) throw new Error('request_proof_unsupported')
+  return webCrypto
+}
+
+const sha256Base64Url = async value => {
+  const digest = await getWebCrypto().subtle.digest('SHA-256', new TextEncoder().encode(value))
+  return bytesToBase64Url(new Uint8Array(digest))
+}
+
+const normalizePublicKey = publicKey => ({
+  kty: 'EC',
+  crv: 'P-256',
+  x: String(publicKey?.x || ''),
+  y: String(publicKey?.y || ''),
+})
+
+const calculateKeyId = publicKey =>
+  sha256Base64Url(
+    JSON.stringify({
+      crv: 'P-256',
+      kty: 'EC',
+      x: String(publicKey?.x || ''),
+      y: String(publicKey?.y || ''),
+    }),
+  )
+
+const createProofRequestId = () => {
+  const webCrypto = getWebCrypto()
+  return typeof webCrypto.randomUUID === 'function'
+    ? webCrypto.randomUUID()
+    : bytesToBase64Url(webCrypto.getRandomValues(new Uint8Array(24)))
+}
+
+const createBrowserProofClient = options => {
+  const databaseName = String(options?.databaseName || '').trim()
+  const storeName = String(options?.storeName || 'context').trim()
+  const recordId = String(options?.recordId || 'request-proof-key').trim()
+  const required = () => isRequestProofRequired(options?.required?.())
+  let proofKeyPromise = null
+
+  if (!databaseName || !storeName || !recordId) {
+    throw new Error('request_proof_storage_failed')
+  }
+
+  const openDatabase = () =>
+    new Promise((resolve, reject) => {
+      if (!globalThis.indexedDB) {
+        reject(new Error('request_proof_storage_unsupported'))
+        return
+      }
+      const request = globalThis.indexedDB.open(databaseName, 1)
+      request.onupgradeneeded = () => {
+        const database = request.result
+        if (!database.objectStoreNames.contains(storeName)) {
+          database.createObjectStore(storeName, { keyPath: 'id' })
+        }
+      }
+      request.onsuccess = () => resolve(request.result)
+      request.onerror = () => reject(new Error('request_proof_storage_failed'))
+    })
+
+  const readStoredKey = async () => {
+    const database = await openDatabase()
+    try {
+      return await new Promise((resolve, reject) => {
+        const request = database.transaction(storeName, 'readonly').objectStore(storeName).get(recordId)
+        request.onsuccess = () => resolve(request.result || null)
+        request.onerror = () => reject(new Error('request_proof_read_failed'))
+      })
+    } finally {
+      database.close()
+    }
+  }
+
+  const isStoredKeyValid = record => {
+    if (!record?.keyId || !record.publicKey?.x || !record.publicKey?.y || !record.privateKey) return false
+    const algorithm = record.privateKey.algorithm
+    return (
+      record.privateKey.type === 'private' &&
+      record.privateKey.extractable === false &&
+      algorithm?.name === 'ECDSA' &&
+      algorithm?.namedCurve === 'P-256' &&
+      Array.isArray(record.privateKey.usages) &&
+      record.privateKey.usages.includes('sign')
+    )
+  }
+
+  const generateCandidate = async () => {
+    const webCrypto = getWebCrypto()
+    const keyPair = await webCrypto.subtle.generateKey(
+      { name: 'ECDSA', namedCurve: 'P-256' },
+      false,
+      ['sign', 'verify'],
+    )
+    const publicKey = normalizePublicKey(await webCrypto.subtle.exportKey('jwk', keyPair.publicKey))
+    return {
+      id: recordId,
+      keyId: await calculateKeyId(publicKey),
+      publicKey,
+      privateKey: keyPair.privateKey,
+      createdAt: new Date().toISOString(),
+    }
+  }
+
+  const storeIfAbsent = async candidate => {
+    const database = await openDatabase()
+    let selectedKey = candidate
+    try {
+      await new Promise((resolve, reject) => {
+        const transaction = database.transaction(storeName, 'readwrite')
+        const store = transaction.objectStore(storeName)
+        const readRequest = store.get(recordId)
+        readRequest.onsuccess = () => {
+          const storedKey = readRequest.result || null
+          if (isStoredKeyValid(storedKey)) selectedKey = storedKey
+          else store.put(candidate)
+        }
+        readRequest.onerror = () => reject(new Error('request_proof_read_failed'))
+        transaction.oncomplete = () => resolve()
+        transaction.onerror = () => reject(new Error('request_proof_write_failed'))
+        transaction.onabort = () => reject(new Error('request_proof_write_failed'))
+      })
+      return selectedKey
+    } finally {
+      database.close()
+    }
+  }
+
+  const getOrCreateKey = () => {
+    if (!proofKeyPromise) {
+      proofKeyPromise = (async () => {
+        const storedKey = await readStoredKey()
+        if (isStoredKeyValid(storedKey)) return storedKey
+        return storeIfAbsent(await generateCandidate())
+      })().catch(error => {
+        proofKeyPromise = null
+        throw error
+      })
+    }
+    return proofKeyPromise
+  }
+
+  const reset = async () => {
+    const pendingKey = proofKeyPromise
+    proofKeyPromise = null
+    await pendingKey?.catch(() => undefined)
+    if (!globalThis.indexedDB) return
+
+    const database = await openDatabase()
+    try {
+      await new Promise((resolve, reject) => {
+        const transaction = database.transaction(storeName, 'readwrite')
+        transaction.objectStore(storeName).delete(recordId)
+        transaction.oncomplete = () => resolve()
+        transaction.onerror = () => reject(new Error('request_proof_reset_failed'))
+        transaction.onabort = () => reject(new Error('request_proof_reset_failed'))
+      })
+    } finally {
+      database.close()
+    }
+  }
+
+  const getRegistration = async () => {
+    const key = await getOrCreateKey()
+    return { keyId: key.keyId, publicKey: key.publicKey }
+  }
+
+  const runtimeUnavailable = () =>
+    (typeof window !== 'undefined' && window.isSecureContext === false) ||
+    !globalThis.crypto?.subtle ||
+    !globalThis.indexedDB
+
+  const tryGetRegistration = async () => {
+    if (!required() && runtimeUnavailable()) return null
+    try {
+      return await getRegistration()
+    } catch (error) {
+      if (!required() && isRequestProofSetupError(error)) return null
+      throw error
+    }
+  }
+
+  const createProof = async input => {
+    const token = String(input?.token || '').trim()
+    if (!token) return ''
+    const key = await getOrCreateKey()
+    const requestId = String(input?.requestId || '').trim()
+    const [ath, qsh, bth] = await Promise.all([
+      sha256Base64Url(token),
+      sha256Base64Url(canonicalizeQuery(input?.requestUri)),
+      sha256Base64Url(canonicalizeBody(input?.body, input?.contentType, input?.hasBody)),
+    ])
+    const header = { alg: 'ES256', kid: key.keyId, typ: 'dpop+jwt' }
+    const payload = {
+      ath,
+      aud: String(input?.audience || ''),
+      htm: String(input?.method || 'GET').toUpperCase(),
+      htu: normalizePath(input?.path),
+      qsh,
+      bth,
+      rid: requestId,
+      iat: Math.floor(Date.now() / 1000),
+      jti: createProofRequestId(),
+    }
+    const signingInput = `${textToBase64Url(JSON.stringify(header))}.${textToBase64Url(JSON.stringify(payload))}`
+    let signature
+    try {
+      signature = await getWebCrypto().subtle.sign(
+        { name: 'ECDSA', hash: 'SHA-256' },
+        key.privateKey,
+        new TextEncoder().encode(signingInput),
+      )
+    } catch {
+      throw new Error('request_proof_sign_failed')
+    }
+    return `${signingInput}.${bytesToBase64Url(new Uint8Array(signature))}`
+  }
+
+  const tryCreateProof = async input => {
+    if (!String(input?.token || '').trim()) return ''
+    if (!required() && runtimeUnavailable()) return ''
+    try {
+      return await createProof(input)
+    } catch (error) {
+      if (!required() && isRequestProofSetupError(error)) return ''
+      throw error
+    }
+  }
+
+  return { createProof, getRegistration, reset, tryCreateProof, tryGetRegistration }
+}
+
+module.exports = { calculateKeyId, createBrowserProofClient, createProofRequestId }

package/core.d.ts

@@ -0,0 +1,29 @@
+export const REQUEST_PROOF_HEADER: 'x-ctx-proof'
+export const AUTH_CENTER_PROOF_AUDIENCE: 'auth-center'
+export const ODM_REQUEST_PROOF_AUDIENCE: 'uweb-odm'
+export const DEFAULT_REQUEST_PROOF_TIME_TOLERANCE_SECONDS: number
+export const REQUEST_PROOF_ERROR_CODES: Readonly<{
+  timeMismatch: 'E4601'
+  requestExpired: 'E4602'
+  requestUnverifiable: 'E4603'
+  sessionMismatch: 'E4604'
+  requestInvalid: 'E4605'
+  serviceUnavailable: 'E503'
+}>
+
+export class RequestProofValidationError extends Error {
+  readonly code: string
+  constructor(code: string)
+}
+
+export function canonicalizeQuery(value: unknown): string
+export function canonicalizeBody(body: unknown, contentType?: unknown, hasBody?: boolean): string
+export function normalizeJsonValue(value: unknown): unknown
+export function normalizePath(value: unknown): string
+export function normalizeProofMode(value: unknown): 'off' | 'shadow' | 'enforce'
+export function stableJson(value: unknown): string
+export function isRequestProofRequired(value: unknown): boolean
+export function isRequestProofSetupError(error: unknown): boolean
+export function getRequestProofErrorCode(
+  reason: string,
+): (typeof REQUEST_PROOF_ERROR_CODES)[keyof typeof REQUEST_PROOF_ERROR_CODES]

package/core.js

@@ -0,0 +1,219 @@
+'use strict'
+
+const REQUEST_PROOF_HEADER = 'x-ctx-proof'
+const AUTH_CENTER_PROOF_AUDIENCE = 'auth-center'
+const ODM_REQUEST_PROOF_AUDIENCE = 'uweb-odm'
+const DEFAULT_REQUEST_PROOF_TIME_TOLERANCE_SECONDS = 2 * 60 * 60
+
+const REQUEST_PROOF_ERROR_CODES = Object.freeze({
+  timeMismatch: 'E4601',
+  requestExpired: 'E4602',
+  requestUnverifiable: 'E4603',
+  sessionMismatch: 'E4604',
+  requestInvalid: 'E4605',
+  serviceUnavailable: 'E503',
+})
+
+class RequestProofValidationError extends Error {
+  constructor(code) {
+    super(code)
+    this.name = 'RequestProofValidationError'
+    this.code = code
+  }
+}
+
+const compareText = (left, right) => (left < right ? -1 : left > right ? 1 : 0)
+
+const normalizePath = value => {
+  const rawValue = String(value || '').trim()
+  if (!rawValue) return ''
+
+  let path = rawValue
+  if (/^[a-z][a-z\d+.-]*:\/\//i.test(rawValue)) {
+    try {
+      path = new URL(rawValue).pathname
+    } catch {
+      return ''
+    }
+  }
+
+  const withoutQuery = path.split(/[?#]/)[0]
+  const withLeadingSlash = withoutQuery.startsWith('/') ? withoutQuery : `/${withoutQuery}`
+  return withLeadingSlash.replace(/\/{2,}/g, '/') || '/'
+}
+
+const canonicalizeQuery = value => {
+  const rawValue = String(value || '').trim()
+  if (!rawValue) return ''
+
+  let query = ''
+  if (/^[a-z][a-z\d+.-]*:\/\//i.test(rawValue)) {
+    try {
+      query = new URL(rawValue).search.slice(1)
+    } catch {
+      return ''
+    }
+  } else {
+    const withoutFragment = rawValue.split('#')[0]
+    const queryIndex = withoutFragment.indexOf('?')
+    query = queryIndex >= 0 ? withoutFragment.slice(queryIndex + 1) : ''
+  }
+
+  return Array.from(new URLSearchParams(query).entries())
+    .sort(([leftKey, leftValue], [rightKey, rightValue]) => {
+      const keyResult = compareText(leftKey, rightKey)
+      return keyResult || compareText(leftValue, rightValue)
+    })
+    .map(([key, entryValue]) => `${encodeURIComponent(key)}=${encodeURIComponent(entryValue)}`)
+    .join('&')
+}
+
+const normalizeJsonValue = value => {
+  if (value === null) return null
+  if (Array.isArray(value)) {
+    return value.map(item =>
+      item === undefined || typeof item === 'function' || typeof item === 'symbol'
+        ? null
+        : normalizeJsonValue(item),
+    )
+  }
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null
+  if (typeof value !== 'object') return value
+  if (typeof value.toJSON === 'function') return normalizeJsonValue(value.toJSON())
+
+  return Object.keys(value)
+    .sort(compareText)
+    .reduce((result, key) => {
+      const item = value[key]
+      if (item !== undefined && typeof item !== 'function' && typeof item !== 'symbol') {
+        result[key] = normalizeJsonValue(item)
+      }
+      return result
+    }, {})
+}
+
+const stableJson = value => JSON.stringify(normalizeJsonValue(value)) || ''
+
+const formEntriesToObject = entries => {
+  const result = {}
+  for (const [key, value] of entries) {
+    const current = result[key]
+    result[key] =
+      current === undefined
+        ? value
+        : Array.isArray(current)
+          ? [...current, value]
+          : [current, value]
+  }
+  return result
+}
+
+const isBinaryBody = body => {
+  if (typeof Buffer !== 'undefined' && typeof Buffer.isBuffer === 'function' && Buffer.isBuffer(body)) {
+    return true
+  }
+  if (typeof Blob !== 'undefined' && body instanceof Blob) return true
+  if (typeof ArrayBuffer !== 'undefined') {
+    return body instanceof ArrayBuffer || ArrayBuffer.isView(body)
+  }
+  return false
+}
+
+const canonicalizeBody = (body, contentType, hasBody) => {
+  const normalizedContentType = String(contentType || '').toLowerCase()
+  if (hasBody === false) return 'none'
+  if (normalizedContentType.includes('multipart/form-data')) return 'multipart'
+  if (typeof FormData !== 'undefined' && body instanceof FormData) return 'multipart'
+  if (body === undefined || body === null || body === '') return 'none'
+  if (isBinaryBody(body)) return 'binary'
+  if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) {
+    return `form:${stableJson(formEntriesToObject(body.entries()))}`
+  }
+  if (typeof body === 'string') {
+    if (normalizedContentType.includes('application/x-www-form-urlencoded')) {
+      return `form:${stableJson(formEntriesToObject(new URLSearchParams(body).entries()))}`
+    }
+    if (normalizedContentType.includes('json')) {
+      try {
+        return `json:${stableJson(JSON.parse(body))}`
+      } catch {
+        return `text:${body}`
+      }
+    }
+    return `text:${body}`
+  }
+  if (normalizedContentType.includes('application/x-www-form-urlencoded')) {
+    return `form:${stableJson(body)}`
+  }
+  return `json:${stableJson(body)}`
+}
+
+const isRequestProofRequired = value => String(value ?? '').trim() !== '0'
+
+const normalizeProofMode = value => {
+  const mode = String(value ?? '').trim().toLowerCase()
+  if (mode === '0' || mode === 'off') return 'off'
+  if (mode === '1' || mode === 'shadow') return 'shadow'
+  return 'enforce'
+}
+
+const isRequestProofSetupError = error => {
+  const message = error instanceof Error ? error.message : String(error || '')
+  return /^request_proof_(?:unsupported|storage_unsupported|storage_failed|read_failed|write_failed|reset_failed|sign_failed)$/.test(
+    message,
+  )
+}
+
+const getRequestProofErrorCode = reason => {
+  if (reason === 'proof_expired') return REQUEST_PROOF_ERROR_CODES.timeMismatch
+  if (reason === 'proof_replayed') return REQUEST_PROOF_ERROR_CODES.requestExpired
+  if (
+    [
+      'missing_proof',
+      'missing_proof_binding',
+      'missing_bound_proof',
+      'missing_sso_source_proof',
+      'invalid_proof_key',
+    ].includes(reason)
+  ) {
+    return REQUEST_PROOF_ERROR_CODES.requestUnverifiable
+  }
+  if (
+    [
+      'missing_user',
+      'missing_token',
+      'missing_device_cookie',
+      'missing_binding',
+      'missing_session_context',
+      'token_mismatch',
+      'session_mismatch',
+      'session_id_mismatch',
+      'missing_sso_source_binding',
+      'sso_source_device_mismatch',
+    ].includes(reason)
+  ) {
+    return REQUEST_PROOF_ERROR_CODES.sessionMismatch
+  }
+  if (reason === 'missing_device_secret' || reason === 'verification_failed') {
+    return REQUEST_PROOF_ERROR_CODES.serviceUnavailable
+  }
+  return REQUEST_PROOF_ERROR_CODES.requestInvalid
+}
+
+module.exports = {
+  AUTH_CENTER_PROOF_AUDIENCE,
+  DEFAULT_REQUEST_PROOF_TIME_TOLERANCE_SECONDS,
+  ODM_REQUEST_PROOF_AUDIENCE,
+  REQUEST_PROOF_ERROR_CODES,
+  REQUEST_PROOF_HEADER,
+  RequestProofValidationError,
+  canonicalizeBody,
+  canonicalizeQuery,
+  getRequestProofErrorCode,
+  isRequestProofRequired,
+  isRequestProofSetupError,
+  normalizeJsonValue,
+  normalizePath,
+  normalizeProofMode,
+  stableJson,
+}

package/node.d.ts

@@ -0,0 +1,78 @@
+export type RequestProofPublicKey = {
+  kty: 'EC'
+  crv: 'P-256'
+  x: string
+  y: string
+}
+
+export type NormalizedRequestProofKey = {
+  keyId: string
+  publicKey: RequestProofPublicKey
+}
+
+export type RequestProofTimeWarning = {
+  reason: 'proof_expired'
+  issuedAt: number | null
+  serverNow: number
+  diffSeconds: number | null
+  toleranceSeconds: number
+}
+
+export type VerifyRequestProofOptions = {
+  proof: string
+  publicKey: RequestProofPublicKey
+  keyId: string
+  token: string
+  method: string
+  path: string
+  audience: string
+  timeToleranceSeconds?: number
+  body?: unknown
+  contentType?: unknown
+  hasBody?: boolean
+  requestId?: unknown
+  requireRequestBindings?: boolean
+}
+
+export type ProofServerMode = 'off' | 'shadow' | 'enforce'
+
+export type ProofServerConfig = {
+  mode: ProofServerMode
+  deviceSessionSecret: string
+  deviceSessionTtlSeconds: number
+  timeToleranceSeconds: number
+  shadowBlockMissingProof: boolean
+}
+
+export const REQUEST_PROOF_REASON_TEXT: Readonly<Record<string, string>>
+export function getRequestProofReasonText(reason: string): string
+
+export function hasTransferredRequestBody(options: {
+  body?: unknown
+  contentLength?: unknown
+  transferEncoding?: unknown
+}): boolean
+export function calculateRequestProofBindings(options: {
+  path: unknown
+  body?: unknown
+  contentType?: unknown
+  hasBody?: boolean
+  requestId?: unknown
+}): { qsh: string; bth: string; rid: string }
+export function normalizeRequestProofKey(value: unknown): Promise<NormalizedRequestProofKey | null>
+export function getRequestProofKeyId(proofValue: string): string
+export function verifyRequestProof(options: VerifyRequestProofOptions): Promise<{
+  jti: string
+  timeWarning: RequestProofTimeWarning | null
+}>
+export function normalizeProofMode(value: unknown): ProofServerMode
+export function resolveProofServerConfig(options?: {
+  env?: Record<string, string | undefined>
+  mode?: string | number
+  deviceSessionSecret?: string
+  deviceSessionTtlSeconds?: number
+  timeToleranceSeconds?: number
+  shadowBlockMissingProof?: boolean
+}): ProofServerConfig
+
+export { RequestProofValidationError } from './core'

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@travelclw/proof-protocol",
+  "version": "0.1.0",
+  "description": "Framework-independent browser and Node.js request Proof protocol",
+  "license": "MIT",
+  "author": "travelclw",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/bubbles_4/travelclw.git",
+    "directory": "packages/proof-protocol"
+  },
+  "homepage": "https://gitee.com/bubbles_4/travelclw/tree/main/packages/proof-protocol#readme",
+  "bugs": {
+    "url": "https://gitee.com/bubbles_4/travelclw/issues"
+  },
+  "keywords": [
+    "proof-of-possession",
+    "request-signing",
+    "webcrypto",
+    "authentication",
+    "security"
+  ],
+  "files": [
+    "*.js",
+    "*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "commonjs",
+  "main": "./core.js",
+  "types": "./core.d.ts",
+  "exports": {
+    ".": {
+      "types": "./core.d.ts",
+      "default": "./core.js"
+    },
+    "./browser": {
+      "types": "./browser.d.ts",
+      "default": "./browser.js"
+    },
+    "./node": {
+      "types": "./node.d.ts",
+      "default": "./server.js"
+    }
+  },
+  "peerDependencies": {
+    "jose": ">=5 <6"
+  },
+  "peerDependenciesMeta": {
+    "jose": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "jose": "^5.10.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node --test",
+    "verify:publish": "node scripts/verify-publish.js",
+    "prepublishOnly": "npm run verify:publish && npm test"
+  }
+}

package/server.js

@@ -0,0 +1,308 @@
+'use strict'
+
+const { createHash, timingSafeEqual } = require('node:crypto')
+const { calculateJwkThumbprint, decodeProtectedHeader, importJWK, jwtVerify } = require('jose')
+const {
+  DEFAULT_REQUEST_PROOF_TIME_TOLERANCE_SECONDS,
+  RequestProofValidationError,
+  canonicalizeBody,
+  canonicalizeQuery,
+  normalizePath,
+  normalizeProofMode,
+} = require('./core')
+
+const REQUEST_PROOF_REASON_TEXT = Object.freeze({
+  invalid_proof_key: '浏览器提交的 proof 公钥无效或缺失',
+  missing_user: 'JWT 中缺少用户名，无法定位账号会话',
+  missing_token: '请求缺少 Authorization Bearer token',
+  missing_proof: '请求缺少浏览器 proof',
+  missing_device_cookie: '请求缺少设备 Cookie，无法定位浏览器设备',
+  missing_device_secret: '未配置设备会话摘要密钥，无法计算设备摘要',
+  missing_binding: 'Redis 中不存在当前账号与设备 Cookie 的会话绑定',
+  missing_session_context: '缺少当前 token 对应的设备会话上下文',
+  missing_proof_binding: '设备会话尚未绑定浏览器 proof 公钥',
+  token_mismatch: '当前 token 与设备会话绑定不一致',
+  session_mismatch: 'JWT sessionId 与设备会话绑定不一致',
+  session_id_mismatch: '登录会话 ID 与设备会话绑定不一致',
+  missing_sso_source_binding: '一次性 SSO 凭证缺少可信源设备绑定',
+  missing_sso_source_proof: '一次性 SSO 凭证缺少源浏览器 Proof 授权',
+  sso_source_device_mismatch: '一次性 SSO 凭证与当前设备不匹配',
+  proof_key_mismatch: '当前浏览器 proof 公钥与已绑定公钥不一致',
+  proof_replayed: '请求 proof 的 jti 已使用，疑似重放请求',
+  invalid_proof_format: '请求 proof 格式不是合法 JWT',
+  invalid_proof_header: '请求 proof 头部算法或类型不符合要求',
+  proof_expired: '请求 proof 时间与服务器时间偏差超过允许窗口',
+  invalid_proof_jti: '请求 proof 缺少有效 jti',
+  proof_method_mismatch: '请求 proof 绑定的 HTTP 方法不匹配',
+  proof_path_mismatch: '请求 proof 绑定的接口路径不匹配',
+  proof_token_mismatch: '请求 proof 绑定的 token 摘要不匹配',
+  proof_query_mismatch: '请求 proof 绑定的查询参数不匹配',
+  proof_body_mismatch: '请求 proof 绑定的请求内容不匹配',
+  proof_request_id_mismatch: '请求 proof 绑定的请求 ID 不匹配',
+  missing_proof_query_binding: '请求 proof 缺少查询参数绑定',
+  missing_proof_body_binding: '请求 proof 缺少请求内容绑定',
+  missing_proof_request_id_binding: '请求 proof 缺少请求 ID 绑定',
+  invalid_proof_signature: '请求 proof 签名验签失败',
+  proof_missing_or_invalid: '缺少 proof 或 proof 公钥无效',
+  missing_bound_proof: '当前浏览器会话未绑定请求 proof 公钥',
+  user_agent_changed: '请求 User-Agent 与登录绑定时不同',
+  accept_language_changed: '请求 Accept-Language 与登录绑定时不同',
+  verification_failed: '请求 proof 验证过程异常',
+})
+
+const getRequestProofReasonText = reason =>
+  REQUEST_PROOF_REASON_TEXT[String(reason || '')] || '未知请求 Proof 校验失败原因'
+
+const safeEqual = (left, right) => {
+  const leftBuffer = Buffer.from(left)
+  const rightBuffer = Buffer.from(right)
+  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer)
+}
+
+const hashBindingValue = value => createHash('sha256').update(value).digest('base64url')
+
+const hasTransferredRequestBody = options => {
+  const rawContentLength = Array.isArray(options?.contentLength)
+    ? options.contentLength[0]
+    : options?.contentLength
+  const contentLengthText = String(rawContentLength ?? '').trim()
+  if (contentLengthText) {
+    const contentLength = Number(contentLengthText)
+    if (Number.isFinite(contentLength) && contentLength >= 0) return contentLength > 0
+  }
+
+  const rawTransferEncoding = Array.isArray(options?.transferEncoding)
+    ? options.transferEncoding[0]
+    : options?.transferEncoding
+  if (String(rawTransferEncoding ?? '').trim()) return true
+
+  const body = options?.body
+  if (body === undefined || body === null || body === '') return false
+  if (
+    typeof body === 'object' &&
+    !Array.isArray(body) &&
+    !Buffer.isBuffer(body) &&
+    Object.keys(body).length === 0
+  ) {
+    return false
+  }
+  return true
+}
+
+const calculateRequestProofBindings = options => ({
+  qsh: hashBindingValue(canonicalizeQuery(options?.path)),
+  bth: hashBindingValue(canonicalizeBody(options?.body, options?.contentType, options?.hasBody)),
+  rid: String(options?.requestId || '').trim(),
+})
+
+const normalizePublicKey = value => {
+  const x = String(value?.x || '').trim()
+  const y = String(value?.y || '').trim()
+  const isCoordinate = coordinate =>
+    coordinate.length >= 40 && coordinate.length <= 60 && /^[A-Za-z0-9_-]+$/.test(coordinate)
+
+  if (value?.kty !== 'EC' || value?.crv !== 'P-256' || !isCoordinate(x) || !isCoordinate(y)) {
+    return null
+  }
+  return { kty: 'EC', crv: 'P-256', x, y }
+}
+
+const normalizeRequestProofKey = async value => {
+  const publicKey = normalizePublicKey(value?.publicKey)
+  if (!publicKey) return null
+
+  const keyId = await calculateJwkThumbprint(publicKey, 'sha256')
+  const suppliedKeyId = String(value?.keyId || '').trim()
+  if (suppliedKeyId && !safeEqual(suppliedKeyId, keyId)) return null
+  return { keyId, publicKey }
+}
+
+const hashToken = token => createHash('sha256').update(token).digest('base64url')
+
+const getRequestProofKeyId = proofValue => {
+  const proof = String(proofValue || '').trim()
+  if (!proof) throw new RequestProofValidationError('missing_proof')
+  if (proof.length < 64 || proof.length > 4096) {
+    throw new RequestProofValidationError('invalid_proof_format')
+  }
+
+  let protectedHeader
+  try {
+    protectedHeader = decodeProtectedHeader(proof)
+  } catch {
+    throw new RequestProofValidationError('invalid_proof_header')
+  }
+  if (protectedHeader.typ !== 'dpop+jwt' || protectedHeader.alg !== 'ES256') {
+    throw new RequestProofValidationError('invalid_proof_header')
+  }
+  const keyId = String(protectedHeader.kid || '').trim()
+  if (!keyId) throw new RequestProofValidationError('invalid_proof_header')
+  return keyId
+}
+
+const verifyRequestProof = async options => {
+  const proof = String(options?.proof || '').trim()
+  if (!proof) throw new RequestProofValidationError('missing_proof')
+  if (proof.length < 64 || proof.length > 4096) {
+    throw new RequestProofValidationError('invalid_proof_format')
+  }
+
+  const keyId = getRequestProofKeyId(proof)
+  if (!safeEqual(keyId, options.keyId)) {
+    throw new RequestProofValidationError('proof_key_mismatch')
+  }
+
+  try {
+    const verificationKey = await importJWK(options.publicKey, 'ES256')
+    const { payload } = await jwtVerify(proof, verificationKey, {
+      algorithms: ['ES256'],
+      audience: options.audience,
+      typ: 'dpop+jwt',
+    })
+    const now = Math.floor(Date.now() / 1000)
+    const timeToleranceSeconds =
+      options.timeToleranceSeconds || DEFAULT_REQUEST_PROOF_TIME_TOLERANCE_SECONDS
+    const issuedAt = Number(payload.iat)
+    const timeWarning =
+      !Number.isInteger(issuedAt) || Math.abs(issuedAt - now) > timeToleranceSeconds
+        ? {
+            reason: 'proof_expired',
+            issuedAt: Number.isInteger(issuedAt) ? issuedAt : null,
+            serverNow: now,
+            diffSeconds: Number.isInteger(issuedAt) ? issuedAt - now : null,
+            toleranceSeconds: timeToleranceSeconds,
+          }
+        : null
+
+    const jti = String(payload.jti || '').trim()
+    if (jti.length < 16 || jti.length > 200) {
+      throw new RequestProofValidationError('invalid_proof_jti')
+    }
+    if (String(payload.htm || '').toUpperCase() !== String(options.method || '').toUpperCase()) {
+      throw new RequestProofValidationError('proof_method_mismatch')
+    }
+    if (normalizePath(payload.htu) !== normalizePath(options.path)) {
+      throw new RequestProofValidationError('proof_path_mismatch')
+    }
+    if (!safeEqual(String(payload.ath || ''), hashToken(options.token))) {
+      throw new RequestProofValidationError('proof_token_mismatch')
+    }
+
+    const expectedBindings = calculateRequestProofBindings(options)
+    const queryHash = String(payload.qsh || '').trim()
+    if (options.requireRequestBindings && !queryHash) {
+      throw new RequestProofValidationError('missing_proof_query_binding')
+    }
+    if (queryHash && !safeEqual(queryHash, expectedBindings.qsh)) {
+      throw new RequestProofValidationError('proof_query_mismatch')
+    }
+
+    const bodyHash = String(payload.bth || '').trim()
+    if (options.requireRequestBindings && !bodyHash) {
+      throw new RequestProofValidationError('missing_proof_body_binding')
+    }
+    if (bodyHash && !safeEqual(bodyHash, expectedBindings.bth)) {
+      throw new RequestProofValidationError('proof_body_mismatch')
+    }
+
+    const requestId = String(payload.rid || '').trim()
+    if (options.requireRequestBindings && !requestId) {
+      throw new RequestProofValidationError('missing_proof_request_id_binding')
+    }
+    if (requestId && !safeEqual(requestId, expectedBindings.rid)) {
+      throw new RequestProofValidationError('proof_request_id_mismatch')
+    }
+    return { jti, timeWarning }
+  } catch (error) {
+    if (error instanceof RequestProofValidationError) throw error
+    throw new RequestProofValidationError('invalid_proof_signature')
+  }
+}
+
+const readOverride = (env, name, fallback) => {
+  const value = env?.[name]
+  return value !== undefined && String(value).trim() !== '' ? value : fallback
+}
+
+const integerSetting = (value, fallback, name, minimum, maximum) => {
+  if (value === undefined || String(value).trim() === '') return fallback
+  const parsed = Number(value)
+  if (
+    !Number.isInteger(parsed) ||
+    parsed < minimum ||
+    (maximum !== undefined && parsed > maximum)
+  ) {
+    const range = maximum === undefined ? `at least ${minimum}` : `between ${minimum} and ${maximum}`
+    throw new Error(`${name} must be an integer ${range}`)
+  }
+  return parsed
+}
+
+const booleanSetting = (value, fallback, name) => {
+  if (value === undefined || String(value).trim() === '') return fallback
+  const normalized = String(value).trim()
+  if (normalized !== '0' && normalized !== '1') {
+    throw new Error(`${name} must be 0 or 1`)
+  }
+  return normalized === '1'
+}
+
+const resolveProofServerConfig = options => {
+  const env = options?.env ?? (typeof process !== 'undefined' ? process.env : {})
+  const mode = normalizeProofMode(readOverride(env, 'AUTH_PROOF_MODE', options?.mode))
+  const deviceSessionSecret = String(
+    readOverride(env, 'AUTH_PROOF_DEVICE_SESSION_SECRET', options?.deviceSessionSecret) || '',
+  ).trim()
+  const deviceSessionTtlSeconds = integerSetting(
+    readOverride(
+      env,
+      'AUTH_PROOF_DEVICE_SESSION_TTL_SECONDS',
+      options?.deviceSessionTtlSeconds,
+    ),
+    12 * 60 * 60,
+    'AUTH_PROOF_DEVICE_SESSION_TTL_SECONDS',
+    1,
+  )
+  const timeToleranceSeconds = integerSetting(
+    readOverride(env, 'AUTH_PROOF_TIME_TOLERANCE_SECONDS', options?.timeToleranceSeconds),
+    DEFAULT_REQUEST_PROOF_TIME_TOLERANCE_SECONDS,
+    'AUTH_PROOF_TIME_TOLERANCE_SECONDS',
+    30,
+    DEFAULT_REQUEST_PROOF_TIME_TOLERANCE_SECONDS,
+  )
+  const shadowBlockMissingProof = booleanSetting(
+    readOverride(
+      env,
+      'AUTH_PROOF_SHADOW_BLOCK_MISSING_PROOF',
+      options?.shadowBlockMissingProof ? '1' : '0',
+    ),
+    false,
+    'AUTH_PROOF_SHADOW_BLOCK_MISSING_PROOF',
+  )
+
+  if (mode !== 'off' && deviceSessionSecret.length < 32) {
+    throw new Error(
+      'AUTH_PROOF_DEVICE_SESSION_SECRET is required when AUTH_PROOF_MODE is shadow or enforce and must contain at least 32 characters',
+    )
+  }
+  return {
+    mode,
+    deviceSessionSecret,
+    deviceSessionTtlSeconds,
+    timeToleranceSeconds,
+    shadowBlockMissingProof,
+  }
+}
+
+module.exports = {
+  REQUEST_PROOF_REASON_TEXT,
+  RequestProofValidationError,
+  calculateRequestProofBindings,
+  getRequestProofKeyId,
+  getRequestProofReasonText,
+  hasTransferredRequestBody,
+  normalizeProofMode,
+  normalizeRequestProofKey,
+  resolveProofServerConfig,
+  verifyRequestProof,
+}