hookbench 0.1.0__py3-none-any.whl

hookbench/__init__.py

@@ -0,0 +1,3 @@
+"""Webhook integration testing: capture, verify HMAC signatures, replay fixtures."""
+
+__version__ = "0.1.0"

hookbench/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

hookbench/cli.py

@@ -0,0 +1,129 @@
+"""hookbench CLI: capture webhooks, verify signatures, replay them at your handler."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+
+from . import __version__
+from .core import DEFAULT_SIGNATURE_HEADER, DEFAULT_TIMESTAMP_HEADER, verify_signature
+from .server import Receiver, replay
+
+
+def cmd_receive(args) -> int:
+    secret = open(args.secret_file, encoding="utf-8").read().strip() if args.secret_file else None
+    receiver = Receiver(port=args.port, secret=secret,
+                        signature_header=args.signature_header,
+                        timestamp_header=args.timestamp_header,
+                        require_timestamp=args.require_timestamp,
+                        fixture_path=args.out)
+    receiver.start()
+    print(f"receiver listening on http://127.0.0.1:{receiver.port}/ "
+          f"(Ctrl+C to stop)")
+    if secret:
+        print(f"verifying {args.signature_header} against the provided secret"
+              + (f", freshness via {args.timestamp_header}" if args.timestamp_header else ""))
+    if args.out:
+        print(f"capturing to {args.out}")
+    print("point your sender at the URL above; captured requests are printed below\n")
+    try:
+        last = 0
+        while True:
+            time.sleep(0.3)
+            while last < len(receiver.captured):
+                c = receiver.captured[last]
+                last += 1
+                verdict = ("signature_valid=?" if c.signature_valid is None
+                           else f"signature_valid={c.signature_valid}")
+                print(f"[{last}] {c.path} ({verdict}) body: {c.body[:160]}")
+    except KeyboardInterrupt:
+        print("\nstopping…")
+    finally:
+        receiver.stop()
+        if receiver.captured:
+            print(f"captured {len(receiver.captured)} request(s)"
+                  + (f" -> {args.out}" if args.out else ""))
+    return 0
+
+
+def cmd_replay(args) -> int:
+    secret = open(args.secret_file, encoding="utf-8").read().strip() if args.secret_file else None
+    results = replay(args.fixtures, args.url, secret=secret,
+                     signature_header=args.signature_header,
+                     timestamp_header=args.timestamp_header,
+                     fresh_signatures=not args.keep_original_signatures)
+    for r in results:
+        print(f"  #{r['run']} {r['path']} -> {r['status']}  {r['response'][:120]}")
+    print(f"{len(results)} webhook(s) replayed to {args.url}")
+    return 0
+
+
+def cmd_verify(args) -> int:
+    payload = open(args.payload, "rb").read()
+    verdict = verify_signature(payload, args.signature, args.secret,
+                               timestamp_header_value=args.timestamp,
+                               require_timestamp=args.require_timestamp,
+                               tolerance_seconds=args.tolerance)
+    if args.json:
+        print(json.dumps(verdict, indent=2))
+    else:
+        print("VALID" if verdict["valid"] else "INVALID")
+        if verdict["error"]:
+            print(f"  {verdict['error']}")
+    return 0 if verdict["valid"] else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="hookbench", description=__doc__)
+    parser.add_argument("--version", action="version", version=f"hookbench {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("receive", help="run a local capture receiver")
+    p.add_argument("--port", type=int, default=8080)
+    p.add_argument("--secret-file", help="file with the HMAC secret (raw string)")
+    p.add_argument("--signature-header", default=DEFAULT_SIGNATURE_HEADER)
+    p.add_argument("--timestamp-header", default=None,
+                   help="set when signatures cover '<timestamp>.<payload>'")
+    p.add_argument("--require-timestamp", action="store_true",
+                   help="reject signatures older than --tolerance")
+    p.add_argument("--tolerance", type=int, default=300)
+    p.add_argument("--out", help="save captures as a fixture .ndjson for replay")
+    p.set_defaults(func=cmd_receive)
+
+    p = sub.add_parser("replay", help="re-send captured webhooks to a handler URL")
+    p.add_argument("fixtures")
+    p.add_argument("--url", required=True)
+    p.add_argument("--secret-file")
+    p.add_argument("--signature-header", default=DEFAULT_SIGNATURE_HEADER)
+    p.add_argument("--timestamp-header", default=DEFAULT_TIMESTAMP_HEADER)
+    p.add_argument("--keep-original-signatures", action="store_true",
+                   help="do not re-sign; replay the captured signature bytes as-is")
+    p.set_defaults(func=cmd_replay)
+
+    p = sub.add_parser("verify", help="check one payload/signature pair offline")
+    p.add_argument("--payload", required=True, help="file with the raw body")
+    p.add_argument("--signature", required=True, help="signature header value, e.g. sha256=…")
+    p.add_argument("--secret", required=True)
+    p.add_argument("--timestamp", help="timestamp header value, when the scheme covers it")
+    p.add_argument("--require-timestamp", action="store_true")
+    p.add_argument("--tolerance", type=int, default=300)
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_verify)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except OSError as exc:
+        print(f"hookbench: error: {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hookbench/core.py

@@ -0,0 +1,96 @@
+"""hookbench core: HMAC verification, local capture receiver, fixture replay."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_SIGNATURE_HEADER = "X-Signature"
+DEFAULT_TIMESTAMP_HEADER = "X-Timestamp"
+DEFAULT_TOLERANCE_SECONDS = 300
+DEFAULT_SCHEME = "sha256"
+
+
+class SignatureError(ValueError):
+    pass
+
+
+def compute_signature(payload: bytes, secret: str, timestamp: str | None = None,
+                      scheme: str = DEFAULT_SCHEME) -> str:
+    """Sign like GitHub/Stripe style receivers: HMAC-SHA256 over `timestamp.payload`
+    when a timestamp is part of the scheme, else over the raw payload."""
+    if timestamp is not None:
+        message = timestamp.encode() + b"." + payload
+    else:
+        message = payload
+    return f"{scheme}=" + hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
+
+
+def verify_signature(payload: bytes, signature_header: str, secret: str,
+                     timestamp: str | None = None,
+                     timestamp_header_value: str | None = None,
+                     tolerance_seconds: int = DEFAULT_TOLERANCE_SECONDS,
+                     require_timestamp: bool = False) -> dict:
+    """Verify a `scheme=<hex>` signature header. Constant-time compare. When the
+    signature was computed over a timestamped message, the timestamp comes from
+    ``timestamp_header_value`` and its freshness is checked."""
+    result = {"valid": False, "error": None, "scheme": None, "replayed": None}
+    if not signature_header:
+        result["error"] = "missing signature header"
+        return result
+    if "=" not in signature_header:
+        result["error"] = "signature header is not in 'scheme=<hex>' form"
+        return result
+    scheme, _, provided = signature_header.partition("=")
+    result["scheme"] = scheme
+    ts = timestamp_header_value
+    if require_timestamp and not ts:
+        result["error"] = f"missing timestamp (needed for the {scheme} scheme freshness check)"
+        return result
+    expected = compute_signature(payload, secret, ts if ts is not None else None, scheme)
+    if not hmac.compare_digest(expected, signature_header.strip()):
+        result["error"] = "signature mismatch (wrong secret, or the payload bytes differ)"
+        return result
+    result["valid"] = True
+    if ts is not None:
+        try:
+            age = abs(time.time() - float(ts))
+            result["replayed"] = age > tolerance_seconds
+            if result["replayed"]:
+                result["error"] = (
+                    f"signature valid but timestamp is {int(age)}s old "
+                    f"(tolerance {tolerance_seconds}s) — possible replay")
+                result["valid"] = False
+        except ValueError:
+            result["error"] = f"non-numeric timestamp {ts!r}"
+            result["valid"] = False
+    return result
+
+
+@dataclass
+class CapturedRequest:
+    timestamp: float
+    method: str
+    path: str
+    headers: dict[str, str]
+    body: str
+    signature_valid: bool | None = None
+
+
+def save_fixtures(path: str | Path, captured: list[CapturedRequest]) -> None:
+    Path(path).write_text(
+        json.dumps([c.__dict__ for c in captured], indent=2), encoding="utf-8")
+
+
+def load_fixtures(path: str | Path) -> list[CapturedRequest]:
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    if isinstance(data, dict):
+        data = data.get("requests", [])
+    return [CapturedRequest(
+        timestamp=c.get("timestamp", 0), method=c.get("method", "POST"),
+        path=c.get("path", "/"), headers=c.get("headers", {}),
+        body=c.get("body", ""), signature_valid=c.get("signature_valid")) for c in data]

hookbench/server.py

@@ -0,0 +1,120 @@
+"""Local capture receiver (stdlib http.server) and replay client (urllib)."""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+import urllib.error
+import urllib.request
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+from .core import CapturedRequest, verify_signature
+
+
+class Receiver:
+    """Capture webhooks to a list (and optionally stream them to an .ndjson file).
+
+    When a secret is provided, every request's signature header is verified and
+    the verdict is recorded alongside the payload."""
+
+    def __init__(self, port: int = 8080, secret: str | None = None,
+                 signature_header: str = "X-Signature",
+                 timestamp_header: str | None = None,
+                 require_timestamp: bool = False,
+                 fixture_path: str | None = None):
+        self.port = port
+        self.secret = secret
+        self.signature_header = signature_header.lower()
+        self.timestamp_header = (timestamp_header or "").lower()
+        self.require_timestamp = require_timestamp
+        self.fixture_path = fixture_path
+        self.captured: list[CapturedRequest] = []
+        self._server = None
+        self._thread = None
+
+    def _handler(self):
+        receiver = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self):  # noqa: N802
+                length = int(self.headers.get("Content-Length", 0) or 0)
+                body = self.rfile.read(length).decode("utf-8", "replace")
+                valid = None
+                if receiver.secret:
+                    verdict = verify_signature(
+                        body.encode("utf-8"),
+                        self.headers.get(receiver.signature_header, ""),
+                        receiver.secret,
+                        timestamp_header_value=(
+                            self.headers.get(receiver.timestamp_header)
+                            if receiver.timestamp_header else None),
+                        require_timestamp=receiver.require_timestamp,
+                    )
+                    valid = verdict["valid"]
+                receiver.captured.append(CapturedRequest(
+                    timestamp=time.time(), method="POST", path=self.path,
+                    headers={k: v for k, v in self.headers.items()},
+                    body=body, signature_valid=valid))
+                status = 200 if valid is not False else 400
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json")
+                self.end_headers()
+                self.wfile.write(json.dumps({"received": True, "signature_valid": valid}).encode())
+
+            def log_message(self, *args):  # silence default stderr logging
+                pass
+
+        return Handler
+
+    def start(self) -> None:
+        self._server = ThreadingHTTPServer(("127.0.0.1", self.port), self._handler())
+        self.port = self._server.server_address[1]
+        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        if self._server:
+            self._server.shutdown()
+            self._server.server_close()
+        if self.fixture_path and self.captured:
+            from .core import save_fixtures
+            save_fixtures(self.fixture_path, self.captured)
+
+    def __enter__(self) -> "Receiver":
+        self.start()
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.stop()
+
+
+def replay(fixtures_path: str, target_url: str, secret: str | None = None,
+           signature_header: str = "X-Signature",
+           timestamp_header: str | None = None,
+           fresh_signatures: bool = True) -> list[dict]:
+    """Re-send captured webhooks to a target, re-signing with a fresh timestamp
+    so replay-protection does not eat your own test traffic."""
+    from .core import compute_signature, load_fixtures
+
+    results = []
+    for i, captured in enumerate(load_fixtures(fixtures_path), 1):
+        payload = captured.body.encode("utf-8")
+        headers = {"Content-Type": captured.headers.get("content-type", "application/json")}
+        if secret:
+            ts = str(int(time.time())) if fresh_signatures else captured.headers.get(timestamp_header or "", "")
+            use_ts = ts if (timestamp_header and ts) else None
+            headers[signature_header] = compute_signature(payload, secret, use_ts)
+            if timestamp_header and use_ts:
+                headers[timestamp_header] = use_ts
+        elif captured.headers.get(signature_header):
+            headers[signature_header] = captured.headers[signature_header]
+        request = urllib.request.Request(target_url, data=payload, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(request, timeout=30) as response:
+                status, body = response.status, response.read().decode("utf-8", "replace")
+        except urllib.error.HTTPError as exc:
+            status, body = exc.code, exc.read().decode("utf-8", "replace")
+        results.append({"run": i, "path": captured.path, "status": status,
+                        "response": body[:200]})
+    return results

hookbench-0.1.0.dist-info/METADATA

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: hookbench
+Version: 0.1.0
+Summary: Webhook integration testing: capture webhooks, verify HMAC signatures, replay fixtures at your handler — stdlib only
+Author: juzorei
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/juzorei/hookbench
+Keywords: webhooks,hmac,testing,integration,agent-skills
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# hookbench
+
+Capture webhooks as fixtures, verify HMAC signatures the way each vendor means them, and replay captures at your handler while developing.
+
+```text
+$ hookbench receive --port 8080 --secret-file secret.txt --out captured.ndjson
+receiver listening on http://127.0.0.1:8080/ (Ctrl+C to stop)
+verifying X-Signature against the provided secret
+[1] /hook (signature_valid=True) body: {"event": "payment.succeeded", "id": 7}
+
+$ hookbench replay captured.ndjson --url http://localhost:9000/handler --secret-file secret.txt
+  #1 /hook -> 200  {"received": true}
+1 webhook(s) replayed to http://localhost:9000/handler
+
+$ hookbench verify --payload body.bin --signature "sha256=abc…" --secret whsec_test123
+VALID
+```
+
+A webhook integration fails in exactly three ways — handler never called (exposure), signature doesn't verify (secret/serialization), handler is wrong (logic). `hookbench` separates them mechanically:
+
+- `receive` — a local capture receiver; when a secret is given, every request's signature verdict is recorded with the payload, and an invalid signature answers 400.
+- `verify` — offline single-payload check. Constant-time comparison, raw-payload and timestamped schemes (Stripe-style `t=…,v1=…`), freshness tolerance against replay.
+- `replay` — re-signs fixtures with a fresh timestamp (so your own replay doesn't trip replay protection) and POSTs them at your handler; `--keep-original-signatures` compares against the captured bytes as-is.
+
+**The serialization trap:** signatures cover exact bytes. A proxy pretty-printing the body breaks the signature while the payload "looks the same" — fixtures store raw bodies, and verification must read the raw request body, never a parsed-and-re-dumped copy.
+
+Python 3.11+, stdlib only.
+
+Install: `pip install hookbench` — or from this repo:
+`pip install "git+https://github.com/juzorei/hookbench#subdirectory=tools/hookbench"`
+
+The companion agent skill lives in [skills/webhook-integration-testing](../skills/webhook-integration-testing). Skills: `npx skills add juzorei/hookbench`.

hookbench-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+hookbench/__init__.py,sha256=uB2QplRa0YmigL3U7svN_shSnOUmGTnzHAD0mUbENr0,108
+hookbench/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+hookbench/cli.py,sha256=cpytsFlZu5PVbklgBDh2XqMPfwd6j8cKK63szIULBxU,5553
+hookbench/core.py,sha256=TdgANAAirqNQ8SuMjk2qowD2QqS68PSfIt0oDU036N4,3716
+hookbench/server.py,sha256=Nuhg87Rk3tRmHiQ-djepaXdzl_yDRmMqK6tqIDRNWbQ,5188
+hookbench-0.1.0.dist-info/METADATA,sha256=x7IkHqCRVEFzA7GtZ8tL78EdhbgIPZS0GDmc275B9Po,2622
+hookbench-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+hookbench-0.1.0.dist-info/entry_points.txt,sha256=p5w3c5PZZgTnFZ-22ITcdnHPbbt_QaSAB2LQ8XWCipk,49
+hookbench-0.1.0.dist-info/top_level.txt,sha256=MrLr2GBq3h7BIyL4H_9d5dPbJzobCwes1_m96mDHzdI,10
+hookbench-0.1.0.dist-info/RECORD,,

hookbench-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hookbench-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hookbench = hookbench.cli:main

hookbench-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hookbench