缺少时间戳新鲜度校验导致 webhook 可重放 / Missing webhook timestamp freshness check allows replay

[saxon134]

问题 / Problem

中文：verify_webhook_signature 会解析 t=...,v1=...，但只把时间戳拼入 HMAC，没有校验时间戳是否过期；任何被截获的有效 webhook 签名都可以在未来重复提交并继续返回 True。修复应增加可配置的最大时间偏移并拒绝过期签名，价值是降低重放攻击风险，保护业务事件处理的可信度和幂等成本。
English: verify_webhook_signature parses t=...,v1=... but only includes the timestamp in the HMAC input; it never checks whether the timestamp is stale. A captured valid webhook can be replayed later and still verify as True. Add a configurable freshness window and reject expired signatures to reduce replay risk and protect event-processing correctness and operational trust.

价值 / Value

修复该问题可以提升正确性、可靠性和用户信任，降低 missing timestamp freshness in verify_webhook_signature 带来的排障与运维成本。

Fixing this issue improves correctness, reliability, and user trust while reducing debugging and operational cost caused by missing timestamp freshness in verify_webhook_signature.

证据 / Evidence

File: src/globalrouter/_webhooks.py

Line: 13

Severity / 严重级别: high

Summary / 摘要: missing timestamp freshness in verify_webhook_signature

[saxon134]

Coding Loop Plan

Refined Issue

Webhook signature verification currently accepts timestamped signatures without enforcing timestamp freshness, allowing captured webhook headers and payloads to be replayed later.

Implementation Plan

Add a bounded timestamp freshness check to timestamped webhook signature verification while preserving existing legacy sha256= behavior. Use a conservative default tolerance, make it configurable through the existing public helper, and cover fresh, stale, future-skewed, malformed, invalid-signature, and legacy cases with focused tests. Avoid unrelated API or webhook refactors.

Development Tasks

1. Add focused webhook freshness tests
   Extend the existing webhook signature test coverage to define the desired behavior before implementation. Use deterministic timestamps by monkeypatching the webhook module clock or by otherwise controlling the current time. Cover: a valid t=...,v1=... signature inside the default tolerance is accepted; an otherwise valid old timestamp is rejected; an otherwise valid future timestamp beyond tolerance is rejected; a non-integer timestamp is rejected; an invalid digest is rejected; the legacy sha256= form keeps its current behavior because it has no timestamp to validate.
   Files: tests/test_client.py
   Tests: python -m pytest tests/test_client.py -q -k webhook

2. Implement timestamp freshness validation
   Update verify_webhook_signature so timestamped signatures require a parseable Unix timestamp and are accepted only when abs(now - timestamp) <= tolerance_seconds. Add a keyword-only tolerance_seconds parameter with a conservative default such as 300 seconds. Keep the function returning False for malformed input instead of raising. Keep using hmac.compare_digest for digest comparison. Preserve existing legacy sha256= verification behavior without applying freshness checks to it.
   Files: src/globalrouter/_webhooks.py, src/globalrouter/_client.py
   Tests: python -m pytest tests/test_client.py -q -k webhook

3. Document the freshness behavior
   Update the README webhook signature example or surrounding text to state that timestamped webhook signatures are checked against a default freshness tolerance, and show how callers can override tolerance_seconds if needed. Do not add unrelated webhook documentation.
   Files: README.md
   Tests: python -m pytest tests/test_client.py -q -k webhook

4. Run full repository validation
   Run the existing project validation commands after the focused webhook work passes. Fix only issues caused by the webhook freshness change.
   Tests: python -m pytest -q, python -m ruff check ., python -m mypy src tests