paystack-webhook 0.1.1__tar.gz → 0.2.0__tar.gz

{paystack_webhook-0.1.1 → paystack_webhook-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paystack-webhook
-Version: 0.1.1
+Version: 0.2.0
 Summary: Verify Paystack and Flutterwave webhooks in Python: HMAC-SHA512, idempotency, replay-safe retries. Zero dependencies.
 Author: mgkvibez
 License: MIT
@@ -134,6 +134,54 @@ header, which proves the sender knows the hash and nothing else. A valid header
 accompany a tampered payload if the hash leaks. This library says so instead of
 implying parity with Paystack.
 
+## When a delivery never arrives
+
+Verification only helps if the body shows up. The failure that costs money is the
+opposite one: the provider says paid, your handler never ran, and nothing is reconciling
+the two. This package now carries a store, a reconciliation job and a replay CLI for it.
+
+Pass the store when you construct the webhook, so deliveries are recorded with their raw
+bytes:
+
+```python
+from paystack_webhooks import PaystackWebhook, SQLiteStore
+
+store = SQLiteStore("deliveries.db")
+paystack = PaystackWebhook("sk_live_...", store=store)
+```
+
+Then compare the provider's ledger against what actually arrived:
+
+```bash
+paystack-webhook reconcile --store deliveries.db --ledger transactions.json
+```
+
+Each finding is a different bug with a different fix:
+
+| Finding | What it means |
+|---|---|
+| `paid_no_delivery` | the ledger says paid and no webhook ever reached you |
+| `delivery_no_ledger` | a delivery for a reference the provider does not know |
+| `amount_mismatch` / `currency_mismatch` | the delivery disagrees with the ledger, in minor units |
+| `duplicate_delivery` | more than one delivery for one reference |
+| `ledger_state_mismatch` | the delivery says success, the ledger says otherwise |
+| `unparseable_delivery` | the stored body is not a payload with a reference |
+
+Exit codes are the contract: `0` clean, `1` findings, `2` usage error. `--json` for a
+machine.
+
+To resend a loss:
+
+```bash
+paystack-webhook replay --store deliveries.db --url http://localhost:3000/webhook --reference T1234
+```
+
+The body is reused byte for byte and the signature is recomputed over those bytes. A
+re-serialised JSON body produces a signature that no longer matches, which is the bug
+replay exists to avoid. Without `--secret` (or `$PAYSTACK_WEBHOOK_SECRET`) the stored
+signature header is reused unchanged, which is only correct if your secret has not
+rotated. `--dry-run` prints the plan and touches no network.
+
 ## The security model, stated plainly
 
 | | Paystack | Flutterwave |

{paystack_webhook-0.1.1 → paystack_webhook-0.2.0}/README.md

@@ -105,6 +105,54 @@ header, which proves the sender knows the hash and nothing else. A valid header
 accompany a tampered payload if the hash leaks. This library says so instead of
 implying parity with Paystack.
 
+## When a delivery never arrives
+
+Verification only helps if the body shows up. The failure that costs money is the
+opposite one: the provider says paid, your handler never ran, and nothing is reconciling
+the two. This package now carries a store, a reconciliation job and a replay CLI for it.
+
+Pass the store when you construct the webhook, so deliveries are recorded with their raw
+bytes:
+
+```python
+from paystack_webhooks import PaystackWebhook, SQLiteStore
+
+store = SQLiteStore("deliveries.db")
+paystack = PaystackWebhook("sk_live_...", store=store)
+```
+
+Then compare the provider's ledger against what actually arrived:
+
+```bash
+paystack-webhook reconcile --store deliveries.db --ledger transactions.json
+```
+
+Each finding is a different bug with a different fix:
+
+| Finding | What it means |
+|---|---|
+| `paid_no_delivery` | the ledger says paid and no webhook ever reached you |
+| `delivery_no_ledger` | a delivery for a reference the provider does not know |
+| `amount_mismatch` / `currency_mismatch` | the delivery disagrees with the ledger, in minor units |
+| `duplicate_delivery` | more than one delivery for one reference |
+| `ledger_state_mismatch` | the delivery says success, the ledger says otherwise |
+| `unparseable_delivery` | the stored body is not a payload with a reference |
+
+Exit codes are the contract: `0` clean, `1` findings, `2` usage error. `--json` for a
+machine.
+
+To resend a loss:
+
+```bash
+paystack-webhook replay --store deliveries.db --url http://localhost:3000/webhook --reference T1234
+```
+
+The body is reused byte for byte and the signature is recomputed over those bytes. A
+re-serialised JSON body produces a signature that no longer matches, which is the bug
+replay exists to avoid. Without `--secret` (or `$PAYSTACK_WEBHOOK_SECRET`) the stored
+signature header is reused unchanged, which is only correct if your secret has not
+rotated. `--dry-run` prints the plan and touches no network.
+
 ## The security model, stated plainly
 
 | | Paystack | Flutterwave |

{paystack_webhook-0.1.1 → paystack_webhook-0.2.0}/paystack_webhook.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paystack-webhook
-Version: 0.1.1
+Version: 0.2.0
 Summary: Verify Paystack and Flutterwave webhooks in Python: HMAC-SHA512, idempotency, replay-safe retries. Zero dependencies.
 Author: mgkvibez
 License: MIT
@@ -134,6 +134,54 @@ header, which proves the sender knows the hash and nothing else. A valid header
 accompany a tampered payload if the hash leaks. This library says so instead of
 implying parity with Paystack.
 
+## When a delivery never arrives
+
+Verification only helps if the body shows up. The failure that costs money is the
+opposite one: the provider says paid, your handler never ran, and nothing is reconciling
+the two. This package now carries a store, a reconciliation job and a replay CLI for it.
+
+Pass the store when you construct the webhook, so deliveries are recorded with their raw
+bytes:
+
+```python
+from paystack_webhooks import PaystackWebhook, SQLiteStore
+
+store = SQLiteStore("deliveries.db")
+paystack = PaystackWebhook("sk_live_...", store=store)
+```
+
+Then compare the provider's ledger against what actually arrived:
+
+```bash
+paystack-webhook reconcile --store deliveries.db --ledger transactions.json
+```
+
+Each finding is a different bug with a different fix:
+
+| Finding | What it means |
+|---|---|
+| `paid_no_delivery` | the ledger says paid and no webhook ever reached you |
+| `delivery_no_ledger` | a delivery for a reference the provider does not know |
+| `amount_mismatch` / `currency_mismatch` | the delivery disagrees with the ledger, in minor units |
+| `duplicate_delivery` | more than one delivery for one reference |
+| `ledger_state_mismatch` | the delivery says success, the ledger says otherwise |
+| `unparseable_delivery` | the stored body is not a payload with a reference |
+
+Exit codes are the contract: `0` clean, `1` findings, `2` usage error. `--json` for a
+machine.
+
+To resend a loss:
+
+```bash
+paystack-webhook replay --store deliveries.db --url http://localhost:3000/webhook --reference T1234
+```
+
+The body is reused byte for byte and the signature is recomputed over those bytes. A
+re-serialised JSON body produces a signature that no longer matches, which is the bug
+replay exists to avoid. Without `--secret` (or `$PAYSTACK_WEBHOOK_SECRET`) the stored
+signature header is reused unchanged, which is only correct if your secret has not
+rotated. `--dry-run` prints the plan and touches no network.
+
 ## The security model, stated plainly
 
 | | Paystack | Flutterwave |

{paystack_webhook-0.1.1 → paystack_webhook-0.2.0}/paystack_webhook.egg-info/SOURCES.txt

@@ -4,21 +4,30 @@ pyproject.toml
 paystack_webhook.egg-info/PKG-INFO
 paystack_webhook.egg-info/SOURCES.txt
 paystack_webhook.egg-info/dependency_links.txt
+paystack_webhook.egg-info/entry_points.txt
 paystack_webhook.egg-info/requires.txt
 paystack_webhook.egg-info/top_level.txt
 paystack_webhooks/__init__.py
+paystack_webhooks/cli.py
 paystack_webhooks/errors.py
 paystack_webhooks/event.py
 paystack_webhooks/flutterwave.py
 paystack_webhooks/idempotency.py
 paystack_webhooks/paystack.py
+paystack_webhooks/reconcile.py
+paystack_webhooks/replay.py
 paystack_webhooks/signature.py
+paystack_webhooks/storage.py
 paystack_webhooks/contrib/__init__.py
 paystack_webhooks/contrib/fastapi.py
 paystack_webhooks/contrib/flask.py
 tests/test_adapters.py
+tests/test_cli.py
 tests/test_event.py
 tests/test_flutterwave.py
 tests/test_idempotency.py
 tests/test_paystack.py
-tests/test_signature.py
+tests/test_reconcile.py
+tests/test_replay.py
+tests/test_signature.py
+tests/test_storage.py

paystack_webhook-0.2.0/paystack_webhook.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+paystack-webhook = paystack_webhooks.cli:main

{paystack_webhook-0.1.1 → paystack_webhook-0.2.0}/paystack_webhooks/__init__.py

@@ -1,8 +1,10 @@
-"""Verify Paystack and Flutterwave webhooks without getting it wrong.
+"""Verify Paystack and Flutterwave webhooks without getting it wrong, then check up
+on them when a delivery goes missing.
 
-    from paystack_webhooks import PaystackWebhook, MemoryStore
+    from paystack_webhooks import PaystackWebhook, SQLiteStore
 
-    paystack = PaystackWebhook("sk_live_...")
+    store = SQLiteStore("deliveries.db")
+    paystack = PaystackWebhook("sk_live_...", store=store)
     event = paystack.process(raw_body, headers)   # None means already handled
 """
 
@@ -11,18 +13,30 @@ from .event import Event
 from .flutterwave import FlutterwaveWebhook
 from .idempotency import MemoryStore, Store
 from .paystack import PaystackWebhook
+from .reconcile import Finding, LedgerEntry, load_ledger, reconcile
+from .replay import ReplayResult, replay_deliveries, sign
+from .storage import Delivery, SQLiteStore
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"
 
 __all__ = [
+    "Delivery",
     "Event",
+    "Finding",
     "FlutterwaveWebhook",
+    "LedgerEntry",
     "MalformedPayload",
     "MemoryStore",
     "PaystackWebhook",
     "RawBodyRequired",
+    "ReplayResult",
+    "SQLiteStore",
     "SignatureError",
     "Store",
     "WebhookError",
     "__version__",
+    "load_ledger",
+    "reconcile",
+    "replay_deliveries",
+    "sign",
 ]

paystack_webhook-0.2.0/paystack_webhooks/cli.py

@@ -0,0 +1,143 @@
+"""`paystack-webhook` - reconcile a ledger against deliveries, and replay them.
+
+Exit codes are a contract, because this runs in cron and in CI:
+
+    0  nothing wrong (no findings, or every replay was accepted)
+    1  findings exist, or a replay was not accepted
+    2  usage or configuration error (bad path, unreadable ledger, no url)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import List, Optional, Sequence
+
+from . import __version__
+from .reconcile import load_ledger, reconcile
+from .replay import replay_deliveries
+from .storage import SQLiteStore
+
+EXIT_OK = 0
+EXIT_FINDINGS = 1
+EXIT_USAGE = 2
+
+SECRET_ENV = "PAYSTACK_WEBHOOK_SECRET"
+
+
+def _store(path: str) -> SQLiteStore:
+    if not path:
+        raise ValueError("--store is required")
+    if not os.path.exists(path):
+        raise ValueError("no store at %s (point it at the file your handler writes)" % path)
+    return SQLiteStore(path)
+
+
+def _cmd_reconcile(args: argparse.Namespace) -> int:
+    store = _store(args.store)
+    try:
+        ledger = load_ledger(args.ledger)
+        n_deliveries = len(store)
+        findings = reconcile(store.deliveries(), ledger)
+    finally:
+        store.close()
+
+    if args.json:
+        print(json.dumps(
+            {"findings": [{"kind": f.kind, "reference": f.reference, "detail": f.detail}
+                          for f in findings],
+             "evidence": {"deliveries": n_deliveries, "ledger_entries": len(ledger)}},
+            indent=2))
+    elif findings:
+        print("Reconciliation found %d problem(s):\n" % len(findings))
+        for f in findings:
+            print("  %-22s %-14s %s" % (f.kind, f.reference, f.detail))
+    else:
+        print("Reconciled %d ledger entries against %d deliveries, no discrepancies."
+              % (len(ledger), n_deliveries))
+    return EXIT_FINDINGS if findings else EXIT_OK
+
+
+def _cmd_replay(args: argparse.Namespace) -> int:
+    store = _store(args.store)
+    try:
+        wanted: Optional[Sequence[str]] = args.reference or None
+        deliveries: List[object] = []
+        if wanted:
+            for reference in wanted:
+                found = store.deliveries(reference)
+                if not found:
+                    raise ValueError("no stored delivery for reference %s" % reference)
+                deliveries.extend(found)
+        else:
+            deliveries = store.deliveries()
+        if not deliveries:
+            raise ValueError("the store holds no deliveries to replay")
+        secret = args.secret or os.environ.get(SECRET_ENV)
+
+        if args.dry_run:
+            for d in deliveries:
+                print("would replay %s to %s (%d bytes%s)"
+                      % (d.reference or d.key, args.url, len(d.body),
+                         ", re-signed" if secret else ", original signature kept"))
+            return EXIT_OK
+
+        results = replay_deliveries(deliveries, args.url, secret=secret)
+    finally:
+        store.close()
+
+    failed = 0
+    for r in results:
+        if r.ok:
+            print("replayed %-14s -> %s %s" % (r.reference or "-", r.status, r.url))
+        else:
+            failed += 1
+            print("FAILED   %-14s -> %s %s"
+                  % (r.reference or "-", r.status if r.status else r.error, r.url))
+    if failed:
+        print("\n%d of %d replays were not accepted" % (failed, len(results)))
+        return EXIT_FINDINGS
+    return EXIT_OK
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="paystack-webhook",
+        description="Reconcile a provider ledger against the webhooks that actually arrived.")
+    parser.add_argument("--version", action="version", version="paystack-webhook %s" % __version__)
+    sub = parser.add_subparsers(dest="command")
+
+    rec = sub.add_parser("reconcile", help="compare a ledger with recorded deliveries")
+    rec.add_argument("--store", required=True, help="SQLite file your handler writes")
+    rec.add_argument("--ledger", required=True, help="ledger JSON (list, or {data: [...]})")
+    rec.add_argument("--json", action="store_true", help="machine-readable output")
+    rec.set_defaults(func=_cmd_reconcile)
+
+    rep = sub.add_parser("replay", help="send recorded deliveries again")
+    rep.add_argument("--store", required=True, help="SQLite file your handler writes")
+    rep.add_argument("--url", required=True, help="where to send them")
+    rep.add_argument("--reference", action="append", help="repeatable; default is all")
+    rep.add_argument("--secret", default=None,
+                     help="re-sign with this secret (default: $%s)" % SECRET_ENV)
+    rep.add_argument("--dry-run", action="store_true", help="show what would be sent")
+    rep.set_defaults(func=_cmd_replay)
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+    if not getattr(args, "command", None):
+        parser.print_help()
+        return EXIT_USAGE
+    try:
+        return int(args.func(args))
+    except (ValueError, OSError) as exc:
+        print("paystack-webhook: %s" % exc, file=sys.stderr)
+        return EXIT_USAGE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

paystack_webhook-0.2.0/paystack_webhooks/reconcile.py

@@ -0,0 +1,183 @@
+"""Compare what the provider says was paid against what actually reached you.
+
+Every webhook integration fails the same way eventually: a delivery is lost, retried
+past its window, or arrives twice, and the two systems quietly disagree about who paid
+what. Verification cannot catch that, because there is nothing to verify when a body
+never arrives.
+
+The unit here is minor currency units, because that is what Paystack and Flutterwave
+send (kobo, pesewas). Comparing floats to money is how you get a mismatch finding on
+every single transaction.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Iterable, List, Mapping, Optional, Sequence, Union
+
+PAID_NO_DELIVERY = "paid_no_delivery"
+DELIVERY_NO_LEDGER = "delivery_no_ledger"
+AMOUNT_MISMATCH = "amount_mismatch"
+CURRENCY_MISMATCH = "currency_mismatch"
+DUPLICATE_DELIVERY = "duplicate_delivery"
+LEDGER_STATE_MISMATCH = "ledger_state_mismatch"
+UNPARSEABLE_DELIVERY = "unparseable_delivery"
+
+KINDS = (
+    PAID_NO_DELIVERY,
+    DELIVERY_NO_LEDGER,
+    AMOUNT_MISMATCH,
+    CURRENCY_MISMATCH,
+    DUPLICATE_DELIVERY,
+    LEDGER_STATE_MISMATCH,
+    UNPARSEABLE_DELIVERY,
+)
+
+_SUCCESS_STATUSES = {"success", "successful", "completed"}
+
+
+@dataclass(frozen=True)
+class LedgerEntry:
+    """One transaction as the provider's API reports it."""
+
+    reference: str
+    amount: Optional[int] = None
+    currency: Optional[str] = None
+    status: Optional[str] = None
+
+    @property
+    def paid(self) -> bool:
+        return (self.status or "").lower() in _SUCCESS_STATUSES
+
+
+@dataclass(frozen=True)
+class Finding:
+    kind: str
+    reference: str
+    detail: str
+
+
+def _as_amount(value: Any) -> Optional[int]:
+    if value is None or value == "":
+        return None
+    if isinstance(value, bool):
+        raise ValueError("an amount cannot be a boolean")
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        if value != int(value):
+            raise ValueError("amounts are minor units; %r is not whole" % value)
+        return int(value)
+    text = str(value).strip()
+    if not text:
+        return None
+    return int(text)
+
+
+def load_ledger(source: Union[str, Sequence[Mapping[str, Any]]]) -> List[LedgerEntry]:
+    """Read a ledger from a list of dicts or a JSON file.
+
+    Accepts a bare list, ``{"transactions": [...]}``, or the provider's own
+    ``{"data": [...]}`` envelope, because those are the three shapes you actually
+    end up holding.
+    """
+    if isinstance(source, str):
+        with open(source, "r", encoding="utf-8") as fh:
+            return load_ledger(json.load(fh))
+    if isinstance(source, Mapping):
+        for key in ("transactions", "data"):
+            if isinstance(source.get(key), list):
+                return load_ledger(source[key])
+        raise ValueError("ledger object has no transactions or data list")
+
+    out: List[LedgerEntry] = []
+    for raw in source:
+        if not isinstance(raw, Mapping):
+            raise ValueError("each ledger entry must be an object")
+        reference = raw.get("reference")
+        if not reference:
+            raise ValueError("a ledger entry is missing its reference")
+        currency = raw.get("currency")
+        out.append(
+            LedgerEntry(
+                reference=str(reference),
+                amount=_as_amount(raw.get("amount")),
+                currency=str(currency).upper() if currency else None,
+                status=str(raw["status"]) if raw.get("status") is not None else None,
+            )
+        )
+    return out
+
+
+def _facts(body: bytes) -> tuple:
+    """(event name, reference, amount, currency, successful) from a raw body."""
+    payload = json.loads(body.decode("utf-8"))
+    if not isinstance(payload, Mapping):
+        raise ValueError("payload is not an object")
+    data = payload.get("data") or {}
+    if not isinstance(data, Mapping):
+        data = {}
+    event = str(payload.get("event") or "")
+    reference = data.get("reference") or data.get("tx_ref") or payload.get("reference")
+    status = str(data.get("status") or "").lower()
+    successful = status in _SUCCESS_STATUSES or event.lower().endswith(".success")
+    return (
+        event,
+        str(reference) if reference else None,
+        _as_amount(data.get("amount")),
+        (str(data.get("currency")).upper() if data.get("currency") else None),
+        successful,
+    )
+
+
+def reconcile(deliveries: Iterable[Any], ledger: Iterable[LedgerEntry]) -> List[Finding]:
+    """Every way the two records can disagree, sorted so the output is stable."""
+    findings: List[Finding] = []
+    entries = {e.reference: e for e in ledger}
+    by_reference: dict = {}
+
+    for delivery in deliveries:
+        try:
+            event, reference, amount, currency, successful = _facts(delivery.body)
+        except (ValueError, UnicodeDecodeError) as exc:
+            findings.append(Finding(UNPARSEABLE_DELIVERY, delivery.key,
+                                    "body is not readable JSON: %s" % exc))
+            continue
+        if not reference:
+            findings.append(Finding(UNPARSEABLE_DELIVERY, delivery.key,
+                                    "body carries no reference"))
+            continue
+        by_reference.setdefault(reference, []).append(
+            {"event": event, "amount": amount, "currency": currency,
+             "successful": successful}
+        )
+
+        entry = entries.get(reference)
+        if entry is None:
+            findings.append(Finding(DELIVERY_NO_LEDGER, reference,
+                                    "delivery %s for an unknown reference" % event))
+            continue
+        if successful and not entry.paid:
+            findings.append(Finding(LEDGER_STATE_MISMATCH, reference,
+                                    "delivery says success, ledger says %s"
+                                    % (entry.status or "unknown")))
+        if amount is not None and entry.amount is not None and amount != entry.amount:
+            findings.append(Finding(AMOUNT_MISMATCH, reference,
+                                    "delivery %r, ledger %r (minor units)"
+                                    % (amount, entry.amount)))
+        if currency and entry.currency and currency != entry.currency:
+            findings.append(Finding(CURRENCY_MISMATCH, reference,
+                                    "delivery %s, ledger %s" % (currency, entry.currency)))
+
+    for reference, seen in by_reference.items():
+        if len(seen) > 1:
+            findings.append(Finding(DUPLICATE_DELIVERY, reference,
+                                    "%d deliveries for one reference" % len(seen)))
+
+    for reference, entry in entries.items():
+        if entry.paid and reference not in by_reference:
+            findings.append(Finding(PAID_NO_DELIVERY, reference,
+                                    "ledger says paid, no delivery was recorded"))
+
+    return sorted(findings, key=lambda f: (f.kind, f.reference, f.detail))

paystack_webhook-0.2.0/paystack_webhooks/replay.py

@@ -0,0 +1,74 @@
+"""Send a recorded delivery again, signed over the bytes that were actually received.
+
+The failure this fixes: the provider retried three times, your handler 500ed, and the
+body is gone. Re-posting a re-serialised dict produces a valid-looking payload whose
+signature does not match, so the honest receiver rejects it and the debugging session
+starts by blaming the wrong component.
+
+So the body is reused byte for byte and the signature is recomputed over those bytes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Callable, Iterable, List, Mapping, Optional
+
+SIGNATURE_HEADER = "X-Paystack-Signature"
+CONTENT_TYPE = "application/json"
+
+
+@dataclass(frozen=True)
+class ReplayResult:
+    reference: Optional[str]
+    url: str
+    status: Optional[int]
+    error: Optional[str] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None and self.status is not None and 200 <= self.status < 300
+
+
+def sign(body: bytes, secret: str) -> str:
+    return hmac.new(secret.encode("utf-8"), bytes(body), hashlib.sha512).hexdigest()
+
+
+def _default_sender(url: str, body: bytes, headers: Mapping[str, str]) -> int:
+    request = urllib.request.Request(url, data=bytes(body), method="POST",
+                                     headers=dict(headers))
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            return int(response.status)
+    except urllib.error.HTTPError as exc:
+        return int(exc.code)
+
+
+def replay_deliveries(
+    deliveries: Iterable[object],
+    url: str,
+    *,
+    secret: Optional[str] = None,
+    sender: Optional[Callable[[str, bytes, Mapping[str, str]], int]] = None,
+) -> List[ReplayResult]:
+    """POST each delivery to ``url``. The caller decides what to do with the results."""
+    if not url:
+        raise ValueError("a replay needs a target url")
+    send = sender or _default_sender
+    out: List[ReplayResult] = []
+
+    for delivery in deliveries:
+        body = bytes(delivery.body)
+        headers = dict(getattr(delivery, "headers", {}) or {})
+        headers.setdefault("Content-Type", CONTENT_TYPE)
+        if secret:
+            headers[SIGNATURE_HEADER] = sign(body, secret)
+        reference = getattr(delivery, "reference", None)
+        try:
+            out.append(ReplayResult(reference, url, send(url, body, headers)))
+        except Exception as exc:  # a single unreachable target must not abort the rest
+            out.append(ReplayResult(reference, url, None, "%s: %s" % (type(exc).__name__, exc)))
+    return out

paystack_webhook-0.2.0/paystack_webhooks/storage.py

@@ -0,0 +1,127 @@
+"""A store that keeps the delivery, not just the fact that it arrived.
+
+``MemoryStore`` answers one question: have I seen this key before? That is enough to
+dedupe and nothing else. Reconciliation needs to know what was actually promised, and
+replay needs the original raw body, because the signature is computed over exactly
+those bytes. A re-serialised JSON body is not the same body and will fail verification
+at the receiving end, which makes replay useless for the one job replay exists for.
+
+SQLite because it is in the standard library, survives a restart, and needs no service
+running beside it. A reconciliation job on a laptop wants a file, not a cluster.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from dataclasses import dataclass
+from typing import List, Mapping, Optional
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS deliveries (
+    key         TEXT PRIMARY KEY,
+    provider    TEXT,
+    reference   TEXT,
+    body        BLOB NOT NULL,
+    headers     TEXT NOT NULL,
+    received_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS deliveries_reference ON deliveries(reference);
+"""
+
+
+@dataclass(frozen=True)
+class Delivery:
+    """One webhook that actually arrived, raw body included."""
+
+    key: str
+    provider: Optional[str]
+    reference: Optional[str]
+    body: bytes
+    headers: Mapping[str, str]
+    received_at: str
+
+
+class SQLiteStore:
+    """Store-protocol compatible, plus the delivery log replay and reconcile need.
+
+    ``seen`` exists so this can stand in wherever a ``Store`` is expected, but it
+    records an empty body. New code should call ``accept`` and pass the body.
+    """
+
+    def __init__(self, path: str = ":memory:") -> None:
+        if not path:
+            raise ValueError("a store path is required")
+        self._lock = threading.Lock()
+        self._conn = sqlite3.connect(path, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        # WAL keeps a reader (reconcile) from blocking the writer (a delivery).
+        if path != ":memory:":
+            self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.executescript(_SCHEMA)
+        self._conn.commit()
+
+    # -- Store protocol ----------------------------------------------------
+    def seen(self, key: str) -> bool:
+        """True if the key was already present. Records it with an empty body."""
+        return not self.accept(key, body=b"")
+
+    # -- the real API ------------------------------------------------------
+    def accept(
+        self,
+        key: str,
+        *,
+        body: bytes = b"",
+        headers: Optional[Mapping[str, str]] = None,
+        provider: Optional[str] = None,
+        reference: Optional[str] = None,
+        received_at: str = "",
+    ) -> bool:
+        """Record the delivery. True if it is new, False if it is a duplicate.
+
+        One statement, so two concurrent deliveries of the same key cannot both be
+        told they are new. That race is a double charge.
+        """
+        if not key:
+            raise ValueError("an idempotency key is required")
+        with self._lock:
+            cur = self._conn.execute(
+                "INSERT OR IGNORE INTO deliveries"
+                " (key, provider, reference, body, headers, received_at)"
+                " VALUES (?, ?, ?, ?, ?, ?)",
+                (key, provider, reference, bytes(body),
+                 json.dumps(dict(headers or {})), received_at),
+            )
+            inserted = cur.rowcount == 1
+            if inserted:
+                self._conn.commit()
+            return inserted
+
+    def deliveries(self, reference: Optional[str] = None) -> List[Delivery]:
+        """Every recorded delivery, oldest first, optionally for one reference."""
+        sql = "SELECT * FROM deliveries"
+        args: tuple = ()
+        if reference is not None:
+            sql += " WHERE reference = ?"
+            args = (reference,)
+        sql += " ORDER BY received_at, rowid"
+        rows = self._conn.execute(sql, args).fetchall()
+        return [
+            Delivery(
+                key=r["key"],
+                provider=r["provider"],
+                reference=r["reference"],
+                body=bytes(r["body"]),
+                headers=json.loads(r["headers"]),
+                received_at=r["received_at"],
+            )
+            for r in rows
+        ]
+
+    def __len__(self) -> int:
+        return self._conn.execute("SELECT COUNT(*) FROM deliveries").fetchone()[0]
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()

{paystack_webhook-0.1.1 → paystack_webhook-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "paystack-webhook"
-version = "0.1.1"
+version = "0.2.0"
 description = "Verify Paystack and Flutterwave webhooks in Python: HMAC-SHA512, idempotency, replay-safe retries. Zero dependencies."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -26,6 +26,9 @@ dependencies = []
 [project.optional-dependencies]
 dev = ["pytest>=8", "fastapi>=0.110", "httpx>=0.27", "flask>=3.0", "ruff>=0.4", "build>=1.0"]
 
+[project.scripts]
+paystack-webhook = "paystack_webhooks.cli:main"
+
 [project.urls]
 Homepage = "https://github.com/mgkvibez/paystack-webhooks"
 Issues = "https://github.com/mgkvibez/paystack-webhooks/issues"

paystack_webhook-0.2.0/tests/test_cli.py

@@ -0,0 +1,88 @@
+import json
+
+from paystack_webhooks.cli import EXIT_FINDINGS, EXIT_OK, EXIT_USAGE, main
+from paystack_webhooks.storage import SQLiteStore
+
+
+def _db(tmp_path, *references):
+    path = str(tmp_path / "d.db")
+    store = SQLiteStore(path)
+    for i, reference in enumerate(references):
+        store.accept("k%d" % i,
+                     body=json.dumps({"event": "charge.success",
+                                      "data": {"reference": reference, "amount": 50000,
+                                               "currency": "NGN"}}).encode(),
+                     reference=reference)
+    store.close()
+    return path
+
+
+def _ledger(tmp_path, entries):
+    path = tmp_path / "ledger.json"
+    path.write_text(json.dumps(entries))
+    return str(path)
+
+
+def test_version_prints_package_version(capsys):
+    import pytest
+    with pytest.raises(SystemExit) as exc:
+        main(["--version"])
+    assert exc.value.code == 0
+    assert capsys.readouterr().out.startswith("paystack-webhook ")
+
+
+def test_no_command_is_a_usage_error():
+    assert main([]) == EXIT_USAGE
+
+
+def test_missing_store_is_a_usage_error(tmp_path):
+    ledger = _ledger(tmp_path, [])
+    missing = str(tmp_path / "nope.db")
+    assert main(["reconcile", "--store", missing, "--ledger", ledger]) == EXIT_USAGE
+
+
+def test_clean_reconciliation_exits_zero(tmp_path, capsys):
+    db = _db(tmp_path, "T1")
+    ledger = _ledger(tmp_path, [{"reference": "T1", "amount": 50000,
+                                 "currency": "NGN", "status": "success"}])
+    assert main(["reconcile", "--store", db, "--ledger", ledger]) == EXIT_OK
+    assert "no discrepancies" in capsys.readouterr().out
+
+
+def test_findings_exit_one_and_are_printed(tmp_path, capsys):
+    db = _db(tmp_path, "T1")
+    ledger = _ledger(tmp_path, [{"reference": "T2", "amount": 1, "currency": "NGN",
+                                 "status": "success"}])
+    assert main(["reconcile", "--store", db, "--ledger", ledger]) == EXIT_FINDINGS
+    out = capsys.readouterr().out
+    assert "paid_no_delivery" in out and "delivery_no_ledger" in out
+
+
+def test_json_output_is_machine_readable(tmp_path, capsys):
+    db = _db(tmp_path, "T1")
+    ledger = _ledger(tmp_path, [{"reference": "T2", "amount": 1, "currency": "NGN",
+                                 "status": "success"}])
+    assert main(["reconcile", "--store", db, "--ledger", ledger, "--json"]) == EXIT_FINDINGS
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["evidence"]["deliveries"] == 1
+    assert {f["kind"] for f in payload["findings"]} == {"paid_no_delivery", "delivery_no_ledger"}
+
+
+def test_replay_dry_run_sends_nothing(tmp_path, capsys):
+    db = _db(tmp_path, "T1")
+    args = ["replay", "--store", db, "--url", "http://127.0.0.1:9/never", "--dry-run"]
+    assert main(args) == EXIT_OK
+    assert "would replay T1" in capsys.readouterr().out
+
+
+def test_replay_unknown_reference_is_a_usage_error(tmp_path):
+    db = _db(tmp_path, "T1")
+    assert main(["replay", "--store", db, "--url", "http://127.0.0.1:9/x",
+                 "--reference", "ghost", "--dry-run"]) == EXIT_USAGE
+
+
+def test_unreadable_ledger_is_a_usage_error(tmp_path):
+    db = _db(tmp_path, "T1")
+    bad = tmp_path / "bad.json"
+    bad.write_text("{not json")
+    assert main(["reconcile", "--store", db, "--ledger", str(bad)]) == EXIT_USAGE

paystack_webhook-0.2.0/tests/test_reconcile.py

@@ -0,0 +1,122 @@
+import json
+
+import pytest
+
+from paystack_webhooks.reconcile import (
+    AMOUNT_MISMATCH,
+    CURRENCY_MISMATCH,
+    DELIVERY_NO_LEDGER,
+    DUPLICATE_DELIVERY,
+    LEDGER_STATE_MISMATCH,
+    PAID_NO_DELIVERY,
+    UNPARSEABLE_DELIVERY,
+    LedgerEntry,
+    load_ledger,
+    reconcile,
+)
+
+
+class FakeDelivery:
+    def __init__(self, key, body, reference=None):
+        self.key = key
+        self.body = body
+        self.reference = reference
+
+
+def _d(key, reference="T1", amount=50000, currency="NGN", event="charge.success", ref=None):
+    return FakeDelivery(key, json.dumps(
+        {"event": event, "data": {"reference": reference, "amount": amount,
+                                  "currency": currency}}).encode())
+
+
+def _ledger(*entries):
+    return [LedgerEntry(reference=r, amount=a, currency=c, status=s) for r, a, c, s in entries]
+
+
+def test_agreement_is_silent():
+    findings = reconcile([_d("k1")], _ledger(("T1", 50000, "NGN", "success")))
+    assert findings == []
+
+
+def test_paid_but_never_delivered():
+    findings = reconcile([], _ledger(("T1", 50000, "NGN", "success")))
+    assert [f.kind for f in findings] == [PAID_NO_DELIVERY]
+    assert findings[0].reference == "T1"
+
+
+def test_pending_ledger_entry_is_not_a_finding():
+    assert reconcile([], _ledger(("T1", 50000, "NGN", "pending"))) == []
+
+
+def test_delivery_for_unknown_reference():
+    findings = reconcile([_d("k1", reference="ghost")], _ledger(("T1", 50000, "NGN", "success")))
+    kinds = sorted(f.kind for f in findings)
+    assert DELIVERY_NO_LEDGER in kinds
+    assert PAID_NO_DELIVERY in kinds
+
+
+def test_amount_and_currency_mismatch():
+    findings = reconcile([_d("k1", amount=49999, currency="GHS")],
+                         _ledger(("T1", 50000, "NGN", "success")))
+    assert sorted(f.kind for f in findings) == [AMOUNT_MISMATCH, CURRENCY_MISMATCH]
+
+
+def test_success_delivery_against_failed_ledger():
+    findings = reconcile([_d("k1")], _ledger(("T1", 50000, "NGN", "failed")))
+    assert [f.kind for f in findings] == [LEDGER_STATE_MISMATCH]
+
+
+def test_duplicate_deliveries_are_one_finding():
+    findings = reconcile([_d("k1"), _d("k2")], _ledger(("T1", 50000, "NGN", "success")))
+    assert [f.kind for f in findings] == [DUPLICATE_DELIVERY]
+    assert "2 deliveries" in findings[0].detail
+
+
+def test_unparseable_body_is_reported_not_raised():
+    broken = FakeDelivery("k1", b"not json")
+    findings = reconcile([broken], _ledger(("T1", 50000, "NGN", "success")))
+    kinds = sorted(f.kind for f in findings)
+    assert UNPARSEABLE_DELIVERY in kinds
+
+
+def test_body_without_reference_is_reported():
+    body = json.dumps({"event": "charge.success", "data": {"amount": 5}}).encode()
+    findings = reconcile([FakeDelivery("k1", body)], [])
+    assert [f.kind for f in findings] == [UNPARSEABLE_DELIVERY]
+
+
+def test_flutterwave_status_and_tx_ref():
+    body = json.dumps({"event": "charge.completed",
+                       "data": {"tx_ref": "FLW1", "amount": 100, "currency": "NGN",
+                                "status": "successful"}}).encode()
+    assert reconcile([FakeDelivery("k1", body)],
+                     _ledger(("FLW1", 100, "NGN", "successful"))) == []
+
+
+@pytest.mark.parametrize("payload", [
+    {"transactions": [{"reference": "T1", "amount": 1, "currency": "ngn", "status": "success"}]},
+    {"data": [{"reference": "T1", "amount": 1, "currency": "NGN", "status": "success"}]},
+    [{"reference": "T1", "amount": 1, "currency": "NGN", "status": "success"}],
+])
+def test_ledger_shapes(payload):
+    entries = load_ledger(payload)
+    assert entries[0].reference == "T1"
+    assert entries[0].currency == "NGN"
+
+
+def test_ledger_from_file(tmp_path):
+    path = tmp_path / "ledger.json"
+    path.write_text(json.dumps([{"reference": "T1", "amount": "50000",
+                                 "currency": "NGN", "status": "success"}]))
+    entries = load_ledger(str(path))
+    assert entries[0].amount == 50000
+
+
+def test_ledger_rejects_missing_reference():
+    with pytest.raises(ValueError):
+        load_ledger([{"amount": 1}])
+
+
+def test_ledger_rejects_fractional_minor_units():
+    with pytest.raises(ValueError):
+        load_ledger([{"reference": "T1", "amount": 1.5}])

paystack_webhook-0.2.0/tests/test_replay.py

@@ -0,0 +1,89 @@
+import hashlib
+import hmac
+import json
+
+import pytest
+
+from paystack_webhooks.replay import SIGNATURE_HEADER, replay_deliveries, sign
+from paystack_webhooks.storage import SQLiteStore
+
+SECRET = "sk_test_demo"
+
+
+def _store(tmp_path, reference="T1", body=None):
+    store = SQLiteStore(str(tmp_path / "d.db"))
+    store.accept("%s-key" % reference,
+                 body=body or json.dumps({"event": "charge.success",
+                                          "data": {"reference": reference,
+                                                   "amount": 50000}}).encode(),
+                 headers={"X-Paystack-Signature": "stale", "Content-Type": "application/json"},
+                 reference=reference, provider="paystack")
+    return store
+
+
+def test_resigned_over_the_original_bytes(tmp_path):
+    """The punchline of the whole module: signature must match what we send."""
+    store = _store(tmp_path)
+    captured = {}
+
+    def sender(url, body, headers):
+        captured["body"] = body
+        captured["headers"] = dict(headers)
+        return 200
+
+    results = replay_deliveries(store.deliveries(), "http://local/hook",
+                                secret=SECRET, sender=sender)
+    assert results[0].ok
+    expected = hmac.new(SECRET.encode(), captured["body"], hashlib.sha512).hexdigest()
+    assert captured["headers"][SIGNATURE_HEADER] == expected
+    assert captured["body"] == store.deliveries()[0].body
+    store.close()
+
+
+def test_original_signature_is_kept_without_a_secret(tmp_path):
+    store = _store(tmp_path)
+    captured = {}
+    replay_deliveries(store.deliveries(), "http://local/hook",
+                      sender=lambda u, b, h: captured.update(h=h) or 200)
+    assert captured["h"][SIGNATURE_HEADER] == "stale"
+    store.close()
+
+
+def test_sign_matches_the_packages_own_verifier():
+    """Replay signs with the same function the verifier checks against."""
+    from paystack_webhooks.signature import hmac_sha512_hex
+    body = b'{"a": 1}'
+    assert sign(body, SECRET) == hmac_sha512_hex(SECRET, body)
+
+
+def test_one_bad_target_does_not_abort_the_run(tmp_path):
+    store = _store(tmp_path, "T1")
+    store.accept("t2-key", body=b'{"event":"charge.success","data":{"reference":"T2"}}',
+                 reference="T2")
+    calls = {"n": 0}
+
+    def sender(url, body, headers):
+        calls["n"] += 1
+        if calls["n"] == 1:
+            raise ConnectionError("refused")
+        return 202
+
+    results = replay_deliveries(store.deliveries(), "http://local/hook", sender=sender)
+    assert [r.ok for r in results] == [False, True]
+    assert "ConnectionError" in results[0].error
+    store.close()
+
+
+def test_non_2xx_is_not_ok(tmp_path):
+    store = _store(tmp_path)
+    results = replay_deliveries(store.deliveries(), "http://local/hook",
+                                sender=lambda u, b, h: 500)
+    assert results[0].ok is False and results[0].status == 500
+    store.close()
+
+
+def test_empty_url_is_refused(tmp_path):
+    store = _store(tmp_path)
+    with pytest.raises(ValueError):
+        replay_deliveries(store.deliveries(), "", sender=lambda u, b, h: 200)
+    store.close()

paystack_webhook-0.2.0/tests/test_storage.py

@@ -0,0 +1,75 @@
+import json
+
+import pytest
+
+from paystack_webhooks.storage import Delivery, SQLiteStore
+
+
+def _body(reference="T1", amount=50000):
+    return json.dumps({"event": "charge.success",
+                       "data": {"reference": reference, "amount": amount,
+                                "currency": "NGN"}}).encode()
+
+
+def test_accept_reports_first_sight_only(tmp_path):
+    store = SQLiteStore(str(tmp_path / "d.db"))
+    assert store.accept("k1", body=_body()) is True
+    assert store.accept("k1", body=_body()) is False
+    assert len(store) == 1
+    store.close()
+
+
+def test_raw_body_survives_byte_for_byte(tmp_path):
+    """Replay is only valid if the signature covers the same bytes we send back."""
+    exact = b'{"event": "charge.success",   "data": {"reference": "T1"}}'
+    store = SQLiteStore(str(tmp_path / "d.db"))
+    store.accept("k1", body=exact, headers={"X-Paystack-Signature": "abc"})
+    got = store.deliveries()[0]
+    assert got.body == exact
+    assert got.headers == {"X-Paystack-Signature": "abc"}
+    store.close()
+
+
+def test_it_persists_across_reopen(tmp_path):
+    path = str(tmp_path / "d.db")
+    first = SQLiteStore(path)
+    first.accept("k1", body=_body(), reference="T1", provider="paystack",
+                 received_at="2026-10-31T20:00:00")
+    first.close()
+
+    second = SQLiteStore(path)
+    assert len(second) == 1
+    assert second.seen("k1") is True
+    assert second.deliveries("T1")[0].provider == "paystack"
+    second.close()
+
+
+def test_deliveries_filter_and_order(tmp_path):
+    store = SQLiteStore(str(tmp_path / "d.db"))
+    store.accept("k1", body=_body("T1"), reference="T1", received_at="2026-10-31T20:00:00")
+    store.accept("k2", body=_body("T2"), reference="T2", received_at="2026-10-31T20:00:01")
+    store.accept("k3", body=_body("T1"), reference="T1", received_at="2026-10-31T20:00:02")
+    assert [d.key for d in store.deliveries()] == ["k1", "k2", "k3"]
+    assert [d.key for d in store.deliveries("T1")] == ["k1", "k3"]
+    assert store.deliveries("nope") == []
+    store.close()
+
+
+def test_seen_is_the_store_protocol(tmp_path):
+    store = SQLiteStore(str(tmp_path / "d.db"))
+    assert store.seen("k1") is False
+    assert store.seen("k1") is True
+    store.close()
+
+
+def test_empty_key_is_refused(tmp_path):
+    store = SQLiteStore(str(tmp_path / "d.db"))
+    with pytest.raises(ValueError):
+        store.accept("", body=_body())
+    store.close()
+
+
+def test_delivery_is_immutable(tmp_path):
+    d = Delivery("k", None, "T1", b"{}", {}, "")
+    with pytest.raises(Exception):
+        d.key = "other"