@travelclw/proof-protocol 0.1.2 → 0.2.0

package/server.js

@@ -1,288 +1,316 @@
-'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(String(left ?? ''))
-  const rightBuffer = Buffer.from(String(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 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,
-  )
-  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,
-  }
-}
-
-module.exports = {
-  REQUEST_PROOF_REASON_TEXT,
-  RequestProofValidationError,
-  calculateRequestProofBindings,
-  getRequestProofKeyId,
-  getRequestProofReasonText,
-  hasTransferredRequestBody,
-  normalizeProofMode,
-  normalizeRequestProofKey,
-  resolveProofServerConfig,
-  verifyRequestProof,
-}
+'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_purpose_mismatch: '请求证明用途不匹配',
+  proof_session_mismatch: '请求证明与当前认证会话不匹配',
+  proof_target_mismatch: '一次性凭据的目标应用或密钥不匹配',
+  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(String(left ?? ''))
+  const rightBuffer = Buffer.from(String(right ?? ''))
+  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer)
+}
+
+const hashBindingValue = value => createHash('sha256').update(value).digest('base64url')
+
+const deriveProofSessionId = sessionId => {
+  if (typeof sessionId !== 'string' || !sessionId.trim()) {
+    throw new RequestProofValidationError('missing_session_context')
+  }
+  return hashBindingValue(`ctx-session-v2:${sessionId}`)
+}
+
+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 (!['dpop+jwt', 'ctx-proof+jwt'].includes(protectedHeader.typ) || 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: options.purpose ? 'ctx-proof+jwt' : '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 (options.purpose) {
+      if (payload.ver !== 2 || payload.purpose !== options.purpose) {
+        throw new RequestProofValidationError('proof_purpose_mismatch')
+      }
+      if (options.purpose === 'session') {
+        if (!safeEqual(payload.psid, deriveProofSessionId(options.sessionId))) {
+          throw new RequestProofValidationError('proof_session_mismatch')
+        }
+      } else if (options.purpose === 'ticket') {
+        if (!options.token || !safeEqual(payload.sth, hashToken(options.token))) {
+          throw new RequestProofValidationError('proof_token_mismatch')
+        }
+      } else {
+        throw new RequestProofValidationError('proof_purpose_mismatch')
+      }
+      return { jti, timeWarning }
+    }
+    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 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,
+  )
+  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,
+  }
+}
+
+module.exports = {
+  deriveProofSessionId,
+  REQUEST_PROOF_REASON_TEXT,
+  RequestProofValidationError,
+  calculateRequestProofBindings,
+  getRequestProofKeyId,
+  getRequestProofReasonText,
+  hasTransferredRequestBody,
+  normalizeProofMode,
+  normalizeRequestProofKey,
+  resolveProofServerConfig,
+  verifyRequestProof,
+}