credentagent.webhooks: a real, signed HTTP order.settled (#101)

[dzuluaga]

Stacked on #98 (the orders checkout). Base is feat/97-orders-surface, so this diff is
only the webhook change. Rebases onto main once #98 merges.

In plain terms

When one of your orders gets paid, you often need to tell a different service — the thing that
ships the product, or a worker on another machine. Today's on("order.settled", …) listener can't
do that: it only fires inside the one process that finished the order.

This adds the real signal — a webhook. When an order settles, the gate sends a signed HTTP
request to a URL you registered; the other service checks the signature and fulfils the order. If
you've used Stripe webhooks, this is the same shape you already know.

// SENDING — one config line; settled orders get POSTed (signed, retried, non-blocking):
new CredentAgent({ webhooks: { endpoints: [{ url: "https://fulfillment.example/hooks", secret: process.env.WHSEC }] } });

// RECEIVING — a different service; only the shared secret:
import { constructEvent } from "@openmobilehub/credentagent-gate";
app.post("/hooks", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try { event = constructEvent(req.body, req.get("CredentAgent-Signature"), process.env.WHSEC); }
  catch (err) { return res.status(400).send(err.message); }        // forged / tampered / replayed → rejected
  if (event.type === "order.settled") fulfill(event.data.object.orderId);
  res.json({ received: true });
});

What you're approving

• New code only — nothing existing changes. A server that registers no endpoint behaves exactly
  as before; on(...), orders.* are untouched.
• Worst case if it's wrong: a webhook fails to deliver. The order is still safely recorded (read
  orders.retrieve(id)), and a forged event can't slip through — that's locked by tests that fail
  the moment the signature check is removed (I verified all three go red).
• What stays safe: no real money moves (this is a notification, not a payment); the signing secret
  is never logged; delivery never blocks or rolls back a settled order.

How to test

npm run build && npm test                       # gate: 340 · storefront: 86
node examples/order-webhooks/smoke.mjs           # → ALL SMOKE CHECKS PASSED (sender→receiver over real HTTP)
# two terminals (same secret), then curl:
CREDENTAGENT_WHSEC=whsec_demo node examples/order-webhooks/receiver.mjs   # :4100
CREDENTAGENT_WHSEC=whsec_demo node examples/order-webhooks/sender.mjs     # :4000
curl -X POST http://localhost:4000/buy-sticker   # → receiver prints a verified order.settled

---

For reviewers — the detail

Increment #101, a sub-issue of epic #97. Design run through the DX council (webhook-dx-council:
4 independent designs — library-fit, Stripe-purist, security-first, DX-minimalist — → an 8-vote judge
panel; all four scored 9/10 on Stripe-idiomaticity and converged). Spec: specs/010-order-webhooks/spec.md.

Surface (webhooks.ts, exported from the package):

• Send: new CredentAgent({ webhooks: { endpoints, retries?, transport? } }); credentagent.webhooks.register({ url, events? }) → { id, secret } (mints a whsec_ secret, process-local). Fired fire-and-forget from the single
  completion choke point orders._complete, alongside the in-process event.
• Receive: two symmetric doors over one core (the Zod parse/safeParse idiom) — constructEvent(rawBody, sigHeader, secret) → typed event or throws WebhookSignatureError (Stripe muscle memory);
  verifyEvent(...) → { ok, … } verdict, never throws. Both are standalone exports (a receiver needs
  no CredentAgent) plus ca.webhooks.* convenience.
• Event is Stripe-shaped: { id, type: "order.settled", created, data: { object: <CompletedOrder> } }.

Security model (spec §Security):

• Header CredentAgent-Signature: t=<unix>,v1=<hex HMAC-SHA256>; MAC over `${t}.${rawBody}` with the
  endpoint secret. Hex digest for Stripe interop (deliberate deviation from the repo's internal base64url,
  called out in the doc comment). Multiple v1= accepted for zero-downtime secret rotation.
• Constant-time compare (timingSafeEqual, length-checked); t is bound into the MAC so it can't be
  backdated; a t outside ±300s is refused (replay window — invariant-6 analogue). Secret never logged.
• Endpoint URLs are trusted config (not user input); https-by-default; no redirect-following.

Honesty: at-least-once delivery + bounded exponential backoff; dedupe on event.id; no
guaranteed/exactly-once claim. Unrelated to presence-only-demo (that's mdoc issuer trust).

Tests: webhooks.test.ts (13). The three security controls are load-bearing bypass tests — a
wrong-secret signature, a body tampered after signing, and a stale (replayed) timestamp are each rejected,
and each test was verified to fail when its control is deleted. Additive: full suite green (gate 340,
storefront 86). examples/order-webhooks/ (sender + receiver + smoke) verified end-to-end over real HTTP,
including a forged event rejected with 400.

Files: webhooks.ts (new), orders.ts / client.ts / types.ts / index.ts (wiring + exports),
webhooks.test.ts (new), examples/order-webhooks/, specs/010-order-webhooks/spec.md, README updates.

Refs #101 · epic #97 · spec 010

🤖 Generated with Claude Code

https://claude.ai/code/session_01Harfquzhqg5SCCURyYRbHD

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
credentagent-demo	Ready	Preview, Comment	Jul 23, 2026 9:27pm

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: eef91c00f7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Disable redirect following for webhook deliveries

globalThis.fetch follows redirects by default, so an endpoint that responds with a 3xx causes the gate to issue a second request to the redirect target and treats its eventual 2xx as successful delivery. This contradicts the webhook SSRF boundary and permits a configured or compromised external endpoint to redirect delivery traffic to an internal host; set redirect: "manual" and let the existing non-2xx retry/error path handle redirects.

Useful? React with 👍 / 👎.

[TheBlackBit]

Agree with codex, PTAL

[dzuluaga]

Fixed in cbd726e: the default transport now sends redirect: "manual", so a 3xx surfaces as a failed attempt and flows into the existing retry/error path instead of being followed. Pinned by a bypass test that runs the real fetch transport against a local redirector server and asserts the redirect target never receives the delivery (lastStatus: 302 reported via onDeliveryError). Verified load-bearing: with redirect: "follow" restored, the test goes red.

[chatgpt-codex-connector]

Bound each webhook attempt with a timeout

When a receiver accepts the TCP connection but never sends response headers, this fetch promise remains pending, so deliverTo never reaches its retry/backoff loop or invokes onDeliveryError. Since completion fires these promises without awaiting them, repeated settled orders against such an endpoint can accumulate indefinitely pending requests; use an AbortController timeout per attempt so failures are retried and eventually reported.

Useful? React with 👍 / 👎.

[dzuluaga]

Fixed in cbd726e: each attempt is bounded by a per-attempt timeout (timeoutMs option, default 10s). An AbortController aborts the fetch, and the attempt is additionally raced against the abort signal so even an injected transport that ignores the signal cannot leave deliverTo pending — the timeout feeds the normal retry/backoff loop and ultimately onDeliveryError. Pinned by a bypass test with a transport that accepts and never responds: it asserts the retry ran and the exhaustion was reported (the test hangs red if the timeout is removed).

[TheBlackBit]

Agree with codex, PTAL

[TheBlackBit]

"https required by default" isn't actually enforced, endpoints (constructor + register()) accept any scheme as is. (The "no redirect-following" half is already covered by the codex P1 comment on webhooks.ts:172.) Either validate the scheme where endpoints enter (https only; http for localhost), or drop that clause from the security model.

[dzuluaga]

Enforced rather than dropped (cbd726e), since the clause is the documented SSRF stance: endpoint URLs are now validated at both entry points — the constructor and register() — https required, http allowed only for localhost dev (localhost, *.localhost, 127.0.0.1, [::1]). Invalid or non-https URLs throw a TypeError at config time. The spec now reads "https is enforced where endpoints enter" instead of "required by default", and a bypass test covers both doors.

[TheBlackBit]

LGTM

[dzuluaga]

Deferred by maintainer decision (revisit post-merge): a callback-verification note in the receiver example (signature proves sender, not order existence — confirm via GET /orders/:id before high-value fulfillment). Keeping the example Stripe-shaped: verify signature → act, no extra step.