Webhook ingress: bind timestamp into signed material for replay protection

[TheGreatAxios]

Summary

CL-7244 asked for replay protection on packages/webhook-triggers' ingress: a byte-for-byte capture of one valid, already-delivered webhook request verified and re-launched the bound workflow indefinitely, since verifySignature only checked an HMAC over the raw body with nothing binding a delivery to a point in time.

A Linear comment thread on the ticket had suggested adopting @corbits/webhooks (a public, unpublished-to-npm sibling package) wholesale and deleting this ingress. I read that package in full and reject that path — see the Linear comment trail for the three reasons (different run-launch lifecycle, no input-templating equivalent, and a regression of the anti-enumeration property CL-7135 shipped the day before). This PR instead closes the actual gap natively:

• New required header X-Webhook-Timestamp (unix seconds).
• Signed material changes from rawBody alone to ${timestamp}.${rawBody}.
• verifySignature rejects a delivery whose timestamp is more than 5 minutes stale or forged into the future (the window Stripe's timestamp.signature scheme uses), via a Number.isFinite-guarded parse so a garbage timestamp can't slip through as NaN.
• Missing/stale timestamp folds into the ingress's existing generic 401 — every failure mode (unknown trigger, disabled trigger, bad signature, bad timestamp) still returns byte-identical JSON, preserving CL-7135's anti-enumeration fix. The server log differentiates the reason; the wire response does not.
• Fixed the one other in-repo caller of the old 2-arg signPayload (the evals harness's fireWebhook, which fires real webhooks through this ingress).

Compatibility

This is a deliberate breaking wire-protocol change — no dual-verify fallback (AGENTS.md forbids leaving a legacy path beside a new one, and a fallback would make replay protection optional). Any already-configured external sender needs X-Webhook-Timestamp added and its signature recomputed over the new material. CL-7260 tracks identifying and notifying affected senders before rollout.

Test plan

• cd packages/webhook-triggers && bun run typecheck && bun test — 40 pass, 8 skip (pre-existing DB-dependent tests), 0 fail
• cd packages/evals && bun run typecheck && bun test — 126 pass, 3 skip (pre-existing), 0 fail
• bunx prettier --check, bun run lint, bun run check:structural — all clean
• Reviewed by Greybeard (fit assessment + design) and Critique (two passes, one build-breaking finding fixed) before and after implementation — see CL-7244 comments

https://linear.app/abklabs/issue/CL-7244

[TheGreatAxios]

greybeard · reject wholesale adoption, approve narrow fix
Branch closes CL-7244's replay gap by binding an X-Webhook-Timestamp into the HMAC-signed material, native to packages/webhook-triggers.

• Rejected adopting @corbits/webhooks wholesale: it launches into an already-live run instead of spinning up a new one (resolve.ts:pickDestination vs this package's launch.ts:launchFoldedRun), has no input-templating equivalent to mapping.ts, and regresses CL-7135's anti-enumeration fix (404 vs 401 by failure mode). Any one of the three is sufficient; no fallback/dual-path was considered.
• signature.ts:61 (isFreshTimestamp) approved as a native ~15-line reimplementation of the standard-webhooks/Stripe timestamp-window pattern rather than vendoring @corbits/webhooks' verify.ts — correct call per AGENTS.md's vendoring bar (Interchange capability we don't want to reimplement, not a small self-contained crypto check).
• Confirmed this is a deliberate breaking wire-protocol change with no legacy path retained; CL-7260 filed separately to track sender notification before rollout.

critique · two passes, one build-break caught and fixed

• First pass: packages/evals/src/targets/real-target.ts:900 still called the old 2-arg signPayload and never sent the new timestamp header — would have failed bun run check (VERIFIED). Fixed in this branch: timestamp computed, header sent, 3-arg call.
• First pass: catch-all log line said "bad signature" even for a missing/stale timestamp (MEDIUM). Fixed by exporting isFreshTimestamp for logging only — verified the HTTP response bodies for every ingress failure branch (unknown trigger, disabled, bad signature, bad timestamp) stay byte-identical; only the log line differentiates.
• Second pass: reran tsc --noEmit on packages/evals, both webhook-triggers test files, and the evals suite — all pass, no new issues, isFreshTimestamp's JSDoc reads cleanly against the existing module security-model comment.
• Verified isFreshTimestamp's Number.isFinite guard is airtight against a NaN-slips-through-Math.abs bypass.

status
Author cannot self-approve; opening as comment. packages/webhook-triggers/src/signature.ts:23-102, packages/webhook-triggers/src/ingress-routes.ts:79-101, packages/evals/src/targets/real-target.ts:889-903.