payrekha 0.1.0a1__tar.gz

payrekha-0.1.0a1/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: payrekha
+Version: 0.1.0a1
+Summary: Sign Payrekha payout intents from your LOS/LMS or settlement engine.
+License: Apache-2.0
+Requires-Python: >=3.9
+Provides-Extra: ed25519
+Requires-Dist: cryptography>=42; extra == "ed25519"

payrekha-0.1.0a1/payrekha/__init__.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Kapil — People of Product
+"""Payrekha intent signing for systems of record (LOS/LMS, settlement engines).
+
+Standard library only for HMAC; Ed25519 signing uses the optional
+``cryptography`` package. Byte-for-byte compatible with @payrekha/core.
+"""
+from .client import DEFAULT_ON_UNAVAILABLE, PayrekhaClient
+from .intent import (
+    INTENT_DOMAIN,
+    INTENT_KINDS,
+    canonical_json,
+    hash_beneficiary,
+    intent_signing_payload,
+    sign_intent_ed25519,
+    sign_intent_hmac,
+)
+
+__all__ = [
+    "DEFAULT_ON_UNAVAILABLE",
+    "PayrekhaClient",
+    "INTENT_DOMAIN",
+    "INTENT_KINDS",
+    "canonical_json",
+    "hash_beneficiary",
+    "intent_signing_payload",
+    "sign_intent_ed25519",
+    "sign_intent_hmac",
+]
+__version__ = "0.1.0a0"

payrekha-0.1.0a1/payrekha/client.py

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Kapil — People of Product
+"""Stdlib-only client for the Payrekha gateway, with an explicit fail mode."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Optional
+
+DEFAULT_ON_UNAVAILABLE = "hold-above:5000000"  # ₹50,000
+
+
+def _threshold(on_unavailable: str) -> Optional[int]:
+    """None = allow all, -1 = hold all, n = hold above n paise."""
+    if on_unavailable == "allow":
+        return None
+    if on_unavailable == "hold":
+        return -1
+    if on_unavailable.startswith("hold-above:"):
+        n = on_unavailable.split(":", 1)[1]
+        if n.isdigit():
+            return int(n)
+    raise ValueError("on_unavailable must be 'allow', 'hold' or 'hold-above:<paise>'")
+
+
+class PayrekhaClient:
+    def __init__(self, base_url: str, api_key: str, on_unavailable: str = DEFAULT_ON_UNAVAILABLE, timeout_s: float = 0.5) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout_s = timeout_s
+        self._threshold = _threshold(on_unavailable)
+        self.on_unavailable = on_unavailable
+
+    def _call(self, method: str, path: str, body: Any = None) -> Any:
+        data = None if body is None else json.dumps(body).encode()
+        req = urllib.request.Request(self.base_url + path, data=data, method=method, headers={"authorization": f"Bearer {self.api_key}", "content-type": "application/json"})
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout_s) as r:
+                return json.loads(r.read() or b"null")
+        except urllib.error.HTTPError as e:
+            payload = e.read()
+            try:
+                return json.loads(payload)
+            except ValueError:
+                raise
+        # URLError / timeouts propagate to the caller of _call
+
+    def evaluate(self, payout: Dict[str, Any]) -> Dict[str, Any]:
+        """Evaluate a payout. If the gateway is unreachable, apply the fail mode — never silently allow above it."""
+        try:
+            return self._call("POST", "/v1/evaluate", payout)
+        except (urllib.error.URLError, TimeoutError, ConnectionError, OSError) as e:
+            amount = payout.get("amountPaise")
+            hold = self._threshold is not None and (self._threshold < 0 or not isinstance(amount, int) or amount > self._threshold)
+            return {
+                "verdict": "REVIEW" if hold else "ALLOW",
+                "effectiveAction": "HOLD" if hold else "ALLOW",
+                "degraded": True,
+                "unavailable": True,
+                "onUnavailable": self.on_unavailable,
+                "hits": [],
+                "error": type(e).__name__,
+            }
+
+    def register_intent(self, intent: Dict[str, Any]) -> Dict[str, Any]:
+        return self._call("POST", "/v1/intents", intent)
+
+    def report_outcome(self, payout_id: str, outcome: str) -> Dict[str, Any]:
+        return self._call("POST", "/v1/outcomes", {"payoutId": payout_id, "outcome": outcome})

payrekha-0.1.0a1/payrekha/intent.py

@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Kapil — People of Product
+import base64
+import hashlib
+import hmac
+import json
+import re
+from typing import Any, Dict, Mapping, Optional, Union
+
+INTENT_DOMAIN = "payrekha-intent-v1\n"
+INTENT_KINDS = ("LOAN_DISBURSAL", "PA_SETTLEMENT", "REFUND", "VDA_WITHDRAWAL", "VENDOR_PAYOUT", "VERIFICATION")
+_MAX_SAFE = 2**53 - 1
+_MOBILE = re.compile(r"^(?:\+?91|0)?([6-9]\d{9})$")
+
+
+def _b64url(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).rstrip(b"=").decode("ascii")
+
+
+def _check(value: Any) -> Any:
+    if isinstance(value, bool) or value is None or isinstance(value, str):
+        return value
+    if isinstance(value, int):
+        if abs(value) > _MAX_SAFE:
+            raise ValueError("integers must be JS-safe")
+        return value
+    if isinstance(value, float):
+        raise ValueError("floats are not allowed; use integer paise / epoch ms")
+    if isinstance(value, (list, tuple)):
+        return [_check(v) for v in value]
+    if isinstance(value, Mapping):
+        return {str(k): _check(v) for k, v in value.items() if v is not None}
+    raise TypeError(f"unsupported type {type(value).__name__}")
+
+
+def canonical_json(value: Any) -> str:
+    """Sorted keys, no whitespace, integers only, None fields dropped — same as canonicalJson()."""
+    return json.dumps(_check(value), sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def intent_signing_payload(intent: Mapping[str, Any]) -> bytes:
+    body = {k: v for k, v in intent.items() if k != "signature"}
+    if body.get("kind") not in INTENT_KINDS:
+        raise ValueError("unknown intent kind")
+    return (INTENT_DOMAIN + canonical_json(body)).encode("utf-8")
+
+
+def sign_intent_hmac(intent: Mapping[str, Any], secret: str) -> Dict[str, Any]:
+    """HMAC-SHA256. Anyone holding the secret can mint intents — prefer Ed25519."""
+    if len(secret) < 32:
+        raise ValueError("HMAC secret must be at least 32 characters")
+    sig = hmac.new(secret.encode("utf-8"), intent_signing_payload(intent), hashlib.sha256).digest()
+    return {**intent, "signature": _b64url(sig)}
+
+
+def sign_intent_ed25519(intent: Mapping[str, Any], private_key: Union[bytes, Any]) -> Dict[str, Any]:
+    """Ed25519 (default). ``private_key`` is a 32-byte seed or a cryptography Ed25519PrivateKey."""
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+    key = Ed25519PrivateKey.from_private_bytes(private_key) if isinstance(private_key, (bytes, bytearray)) else private_key
+    return {**intent, "signature": _b64url(key.sign(intent_signing_payload(intent)))}
+
+
+def hash_beneficiary(
+    key: Union[str, bytes],
+    *,
+    account: Optional[str] = None,
+    ifsc: Optional[str] = None,
+    vpa: Optional[str] = None,
+    mobile: Optional[str] = None,
+) -> str:
+    """Keyed beneficiary ref (``hb1_…``), identical to hashBeneficiary() in @payrekha/core."""
+    k = key.encode("utf-8") if isinstance(key, str) else bytes(key)
+    if len(k) < 16:
+        raise ValueError("hash key must be at least 16 bytes")
+    if account is not None:
+        acct = re.sub(r"[\s-]", "", account)
+        code = (ifsc or "").strip().upper()
+        if not re.fullmatch(r"\d{6,20}", acct):
+            raise ValueError("account number must be 6-20 digits")
+        if not re.fullmatch(r"[A-Z]{4}0[A-Z0-9]{6}", code):
+            raise ValueError("IFSC must look like ABCD0123456")
+        pre = f"acct:{acct}|{code}"
+    elif vpa is not None:
+        v = vpa.strip().lower()
+        if not re.fullmatch(r"[a-z0-9.\-_]{2,256}@[a-z][a-z0-9.\-]{1,64}", v):
+            raise ValueError("VPA must look like name@handle")
+        pre = f"vpa:{v}"
+    elif mobile is not None:
+        m = _MOBILE.match(re.sub(r"[\s-]", "", mobile))
+        if m is None:
+            raise ValueError("mobile must be a 10-digit Indian number")
+        pre = f"mob:{m.group(1)}"
+    else:
+        raise ValueError("give account+ifsc, vpa or mobile")
+    return "hb1_" + _b64url(hmac.new(k, pre.encode("utf-8"), hashlib.sha256).digest())

payrekha-0.1.0a1/payrekha.egg-info/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: payrekha
+Version: 0.1.0a1
+Summary: Sign Payrekha payout intents from your LOS/LMS or settlement engine.
+License: Apache-2.0
+Requires-Python: >=3.9
+Provides-Extra: ed25519
+Requires-Dist: cryptography>=42; extra == "ed25519"

payrekha-0.1.0a1/payrekha.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+pyproject.toml
+payrekha/__init__.py
+payrekha/client.py
+payrekha/intent.py
+payrekha.egg-info/PKG-INFO
+payrekha.egg-info/SOURCES.txt
+payrekha.egg-info/dependency_links.txt
+payrekha.egg-info/requires.txt
+payrekha.egg-info/top_level.txt
+tests/test_intent.py

payrekha-0.1.0a1/payrekha.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

payrekha-0.1.0a1/payrekha.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[ed25519]
+cryptography>=42

payrekha-0.1.0a1/payrekha.egg-info/top_level.txt

@@ -0,0 +1 @@
+payrekha

payrekha-0.1.0a1/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "payrekha"
+version = "0.1.0a1"
+description = "Sign Payrekha payout intents from your LOS/LMS or settlement engine."
+license = { text = "Apache-2.0" }
+requires-python = ">=3.9"
+dependencies = []
+
+[project.optional-dependencies]
+ed25519 = ["cryptography>=42"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"

payrekha-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

payrekha-0.1.0a1/tests/test_intent.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: Apache-2.0
+import json
+import pathlib
+import unittest
+
+from payrekha import canonical_json, hash_beneficiary, intent_signing_payload, sign_intent_ed25519, sign_intent_hmac
+
+VEC = json.loads((pathlib.Path(__file__).resolve().parents[2] / "vectors" / "intent-v1.json").read_text("utf-8"))
+
+
+class IntentVectorTest(unittest.TestCase):
+    def test_beneficiary_ref(self):
+        b = VEC["beneficiary"]
+        self.assertEqual(hash_beneficiary(VEC["hashKey"], account=b["account"], ifsc=b["ifsc"]), VEC["intent"]["beneficiaryRef"])
+
+    def test_payload(self):
+        self.assertEqual(intent_signing_payload(VEC["intent"]).decode("utf-8"), VEC["payload"])
+
+    def test_hmac(self):
+        self.assertEqual(sign_intent_hmac(VEC["intent"], VEC["hmacSecret"])["signature"], VEC["hmacSignature"])
+
+    def test_ed25519(self):
+        try:
+            import cryptography  # noqa: F401
+        except ImportError:
+            self.skipTest("cryptography not installed")
+        signed = sign_intent_ed25519(VEC["intent"], bytes.fromhex(VEC["ed25519SeedHex"]))
+        self.assertEqual(signed["signature"], VEC["ed25519Signature"])
+
+    def test_rejects_floats_and_short_secrets(self):
+        with self.assertRaises(ValueError):
+            canonical_json({"a": 1.5})
+        with self.assertRaises(ValueError):
+            sign_intent_hmac(VEC["intent"], "short")
+
+    def test_mobile_normalisation(self):
+        self.assertEqual(hash_beneficiary(VEC["hashKey"], mobile="+91 98765 43210"), hash_beneficiary(VEC["hashKey"], mobile="9876543210"))
+
+
+if __name__ == "__main__":
+    unittest.main()