kxco-verify 1.0.0__tar.gz

kxco_verify-1.0.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: kxco-verify
+Version: 1.0.0
+Summary: Receiver-side verifier for the KXCO hybrid HMAC + ML-DSA-65 webhook signature scheme
+Author-email: KXCO by Knightsbridge <hello@kxco.ai>
+License: MIT
+Project-URL: Homepage, https://kxco.ai
+Project-URL: Documentation, https://chain.kxco.ai/wallet/dev-docs
+Project-URL: Repository, https://github.com/JackKXCO/kxco-post-quantum-verifiers
+Keywords: post-quantum,ml-dsa,dilithium,webhook,fips-204,kxco
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: oqs
+Requires-Dist: liboqs-python>=0.10; extra == "oqs"
+Provides-Extra: pqcrypto
+Requires-Dist: pqcrypto>=0.3; extra == "pqcrypto"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# kxco-verify (Python)
+
+Receiver-side verifier for the KXCO hybrid HMAC + ML-DSA-65 webhook signature scheme. Wire-format compatible with `@kxco/post-quantum` (npm), the Go verifier, and the Rust verifier.
+
+## Install
+
+```bash
+pip install kxco-verify           # core (HMAC, envelope, fingerprint)
+pip install kxco-verify[oqs]      # adds liboqs-python for ML-DSA
+pip install kxco-verify[pqcrypto] # adds pqcrypto for ML-DSA
+```
+
+The HMAC, envelope, fingerprint, and timestamp paths use only the Python standard library. ML-DSA-65 verification is lazy-loaded: it only requires a PQC backend when `verify_pq` is actually called.
+
+## Quick start (FastAPI)
+
+```python
+from fastapi import FastAPI, Request, HTTPException
+import os
+import kxco_verify as kx
+
+PINNED_KID    = "aa29f37ab7f4b2cf"  # current KXCO production kid (refresh from /.well-known if rotated)
+PINNED_PUBKEY = bytes.fromhex("...3904 hex chars...")
+HMAC_SECRET   = os.environ["KXCO_WEBHOOK_SECRET"].encode()
+
+app = FastAPI()
+
+@app.post("/webhooks/kxco")
+async def webhook(request: Request):
+    raw_body = await request.body()
+    headers = {k.lower(): v for k, v in request.headers.items()}
+
+    result = kx.verify_delivery(
+        headers=headers,
+        raw_body=raw_body,
+        hmac_secret=HMAC_SECRET,
+        pq_public_key=PINNED_PUBKEY,
+        pinned_kid=PINNED_KID,
+    )
+    if not result.ok:
+        raise HTTPException(401, "invalid signature")
+
+    return {"ok": True}
+```
+
+## Running tests
+
+```bash
+cd python
+python test_kxco_verify.py
+```
+
+Expected: `All 6 vector tests passed.`
+
+This verifies that the Python implementation produces identical outputs to `vectors.json` — the same file used by the JavaScript, Go, and Rust verifiers.
+
+## License
+
+MIT.

kxco_verify-1.0.0/README.md

@@ -0,0 +1,59 @@
+# kxco-verify (Python)
+
+Receiver-side verifier for the KXCO hybrid HMAC + ML-DSA-65 webhook signature scheme. Wire-format compatible with `@kxco/post-quantum` (npm), the Go verifier, and the Rust verifier.
+
+## Install
+
+```bash
+pip install kxco-verify           # core (HMAC, envelope, fingerprint)
+pip install kxco-verify[oqs]      # adds liboqs-python for ML-DSA
+pip install kxco-verify[pqcrypto] # adds pqcrypto for ML-DSA
+```
+
+The HMAC, envelope, fingerprint, and timestamp paths use only the Python standard library. ML-DSA-65 verification is lazy-loaded: it only requires a PQC backend when `verify_pq` is actually called.
+
+## Quick start (FastAPI)
+
+```python
+from fastapi import FastAPI, Request, HTTPException
+import os
+import kxco_verify as kx
+
+PINNED_KID    = "aa29f37ab7f4b2cf"  # current KXCO production kid (refresh from /.well-known if rotated)
+PINNED_PUBKEY = bytes.fromhex("...3904 hex chars...")
+HMAC_SECRET   = os.environ["KXCO_WEBHOOK_SECRET"].encode()
+
+app = FastAPI()
+
+@app.post("/webhooks/kxco")
+async def webhook(request: Request):
+    raw_body = await request.body()
+    headers = {k.lower(): v for k, v in request.headers.items()}
+
+    result = kx.verify_delivery(
+        headers=headers,
+        raw_body=raw_body,
+        hmac_secret=HMAC_SECRET,
+        pq_public_key=PINNED_PUBKEY,
+        pinned_kid=PINNED_KID,
+    )
+    if not result.ok:
+        raise HTTPException(401, "invalid signature")
+
+    return {"ok": True}
+```
+
+## Running tests
+
+```bash
+cd python
+python test_kxco_verify.py
+```
+
+Expected: `All 6 vector tests passed.`
+
+This verifies that the Python implementation produces identical outputs to `vectors.json` — the same file used by the JavaScript, Go, and Rust verifiers.
+
+## License
+
+MIT.

kxco_verify-1.0.0/kxco_verify.egg-info/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: kxco-verify
+Version: 1.0.0
+Summary: Receiver-side verifier for the KXCO hybrid HMAC + ML-DSA-65 webhook signature scheme
+Author-email: KXCO by Knightsbridge <hello@kxco.ai>
+License: MIT
+Project-URL: Homepage, https://kxco.ai
+Project-URL: Documentation, https://chain.kxco.ai/wallet/dev-docs
+Project-URL: Repository, https://github.com/JackKXCO/kxco-post-quantum-verifiers
+Keywords: post-quantum,ml-dsa,dilithium,webhook,fips-204,kxco
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: oqs
+Requires-Dist: liboqs-python>=0.10; extra == "oqs"
+Provides-Extra: pqcrypto
+Requires-Dist: pqcrypto>=0.3; extra == "pqcrypto"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# kxco-verify (Python)
+
+Receiver-side verifier for the KXCO hybrid HMAC + ML-DSA-65 webhook signature scheme. Wire-format compatible with `@kxco/post-quantum` (npm), the Go verifier, and the Rust verifier.
+
+## Install
+
+```bash
+pip install kxco-verify           # core (HMAC, envelope, fingerprint)
+pip install kxco-verify[oqs]      # adds liboqs-python for ML-DSA
+pip install kxco-verify[pqcrypto] # adds pqcrypto for ML-DSA
+```
+
+The HMAC, envelope, fingerprint, and timestamp paths use only the Python standard library. ML-DSA-65 verification is lazy-loaded: it only requires a PQC backend when `verify_pq` is actually called.
+
+## Quick start (FastAPI)
+
+```python
+from fastapi import FastAPI, Request, HTTPException
+import os
+import kxco_verify as kx
+
+PINNED_KID    = "aa29f37ab7f4b2cf"  # current KXCO production kid (refresh from /.well-known if rotated)
+PINNED_PUBKEY = bytes.fromhex("...3904 hex chars...")
+HMAC_SECRET   = os.environ["KXCO_WEBHOOK_SECRET"].encode()
+
+app = FastAPI()
+
+@app.post("/webhooks/kxco")
+async def webhook(request: Request):
+    raw_body = await request.body()
+    headers = {k.lower(): v for k, v in request.headers.items()}
+
+    result = kx.verify_delivery(
+        headers=headers,
+        raw_body=raw_body,
+        hmac_secret=HMAC_SECRET,
+        pq_public_key=PINNED_PUBKEY,
+        pinned_kid=PINNED_KID,
+    )
+    if not result.ok:
+        raise HTTPException(401, "invalid signature")
+
+    return {"ok": True}
+```
+
+## Running tests
+
+```bash
+cd python
+python test_kxco_verify.py
+```
+
+Expected: `All 6 vector tests passed.`
+
+This verifies that the Python implementation produces identical outputs to `vectors.json` — the same file used by the JavaScript, Go, and Rust verifiers.
+
+## License
+
+MIT.

kxco_verify-1.0.0/kxco_verify.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+kxco_verify.py
+pyproject.toml
+kxco_verify.egg-info/PKG-INFO
+kxco_verify.egg-info/SOURCES.txt
+kxco_verify.egg-info/dependency_links.txt
+kxco_verify.egg-info/requires.txt
+kxco_verify.egg-info/top_level.txt

kxco_verify-1.0.0/kxco_verify.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kxco_verify-1.0.0/kxco_verify.egg-info/requires.txt

@@ -0,0 +1,9 @@
+
+[dev]
+pytest>=7
+
+[oqs]
+liboqs-python>=0.10
+
+[pqcrypto]
+pqcrypto>=0.3

kxco_verify-1.0.0/kxco_verify.egg-info/top_level.txt

@@ -0,0 +1 @@
+kxco_verify

kxco_verify-1.0.0/kxco_verify.py

@@ -0,0 +1,208 @@
+"""kxco_verify — receiver-side verifier for the KXCO hybrid HMAC + ML-DSA-65
+webhook signature scheme.
+
+Wire-format compatible with @kxco/post-quantum (npm), the Go verifier, and the
+Rust verifier.
+
+The HMAC, envelope, fingerprint, and timestamp paths depend only on the Python
+standard library.
+
+ML-DSA-65 verification requires one of:
+    - `oqs`        (Open Quantum Safe Python bindings; pip install oqs)
+    - `pqcrypto`   (pip install pqcrypto, with ML-DSA backend)
+The verifier auto-detects the available backend at import time.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from dataclasses import dataclass
+from typing import Mapping, Optional
+
+DEFAULT_REPLAY_WINDOW = 300  # seconds
+
+# ── ML-DSA backend detection ────────────────────────────────────────────────
+#
+# Backend selection is LAZY: probing happens only on the first verify_pq call.
+# This keeps the HMAC and envelope paths fully functional even if no PQC
+# library is installed locally (the receiver may only verify HMAC and treat PQ
+# as defence-in-depth that they'll wire up later).
+
+_ml_dsa_backend: Optional[str] = None
+_pqcrypto_ml_dsa = None
+_backend_probed = False
+
+
+def _probe_ml_dsa_backend() -> None:
+    """Lazy backend probe. Called from verify_pq only."""
+    global _ml_dsa_backend, _pqcrypto_ml_dsa, _backend_probed
+    if _backend_probed:
+        return
+    _backend_probed = True
+
+    try:
+        import oqs  # type: ignore
+        probe = oqs.Signature("ML-DSA-65")  # raises if liboqs shared lib missing
+        del probe
+        _ml_dsa_backend = "oqs"
+        return
+    except Exception:
+        pass
+
+    try:
+        from pqcrypto.sign import ml_dsa_65 as _ml_dsa_mod  # type: ignore
+        _pqcrypto_ml_dsa = _ml_dsa_mod
+        _ml_dsa_backend = "pqcrypto"
+    except Exception:
+        _pqcrypto_ml_dsa = None
+
+
+# ── Envelope + HMAC primitives (pure stdlib) ─────────────────────────────────
+
+def envelope(timestamp: str, raw_body: bytes) -> bytes:
+    """Canonical signed envelope: timestamp + "." + raw_body bytes."""
+    if isinstance(raw_body, str):
+        raw_body = raw_body.encode("utf-8")
+    return timestamp.encode("utf-8") + b"." + raw_body
+
+
+def hmac_hex(secret: bytes, timestamp: str, raw_body: bytes) -> str:
+    """HMAC-SHA-256 of the envelope, hex-encoded. No `sha256=` prefix."""
+    if isinstance(secret, str):
+        secret = secret.encode("utf-8")
+    mac = hmac.new(secret, envelope(timestamp, raw_body), hashlib.sha256)
+    return mac.hexdigest()
+
+
+def verify_hmac(secret: bytes, timestamp: str, raw_body: bytes, sig_header: str) -> bool:
+    """Constant-time verify of the X-KXCO-Signature header.
+    Accepts the value with or without the `sha256=` prefix.
+    """
+    expected = "sha256=" + hmac_hex(secret, timestamp, raw_body)
+    given = sig_header if sig_header.startswith("sha256=") else "sha256=" + sig_header
+    return hmac.compare_digest(expected, given)
+
+
+# ── ML-DSA-65 verify ─────────────────────────────────────────────────────────
+
+def verify_pq(public_key: bytes, timestamp: str, raw_body: bytes, sig_header: str) -> bool:
+    """Verify the X-KXCO-PQ-Signature ML-DSA-65 signature.
+
+    Accepts header value with or without the `ml-dsa-65=` prefix.
+    Returns False on any error (invalid hex, invalid key, signature mismatch).
+    """
+    hex_sig = sig_header[len("ml-dsa-65="):] if sig_header.startswith("ml-dsa-65=") else sig_header
+    try:
+        sig_bytes = bytes.fromhex(hex_sig)
+    except ValueError:
+        return False
+
+    env = envelope(timestamp, raw_body)
+    _probe_ml_dsa_backend()
+
+    if _ml_dsa_backend == "oqs":
+        try:
+            import oqs  # type: ignore
+            verifier = oqs.Signature("ML-DSA-65")
+            return verifier.verify(env, sig_bytes, public_key)
+        except Exception:
+            return False
+
+    if _ml_dsa_backend == "pqcrypto":
+        try:
+            _pqcrypto_ml_dsa.verify(public_key, sig_bytes + env)
+            return True
+        except Exception:
+            return False
+
+    raise RuntimeError(
+        "No ML-DSA-65 backend available. Install one of:\n"
+        "  pip install liboqs-python    # Open Quantum Safe (with liboqs built locally)\n"
+        "  pip install pqcrypto         # pqcrypto with ML-DSA backend"
+    )
+
+
+# ── Kid / fingerprint ────────────────────────────────────────────────────────
+
+def fingerprint(public_key: bytes) -> str:
+    """16-hex kid: first 8 bytes of SHA-256(public_key)."""
+    if isinstance(public_key, str):
+        public_key = bytes.fromhex(public_key)
+    return hashlib.sha256(public_key).hexdigest()[:16]
+
+
+def kid_equals(a: str, b: str) -> bool:
+    """Constant-time string compare for kids."""
+    if len(a) != len(b):
+        return False
+    return hmac.compare_digest(a, b)
+
+
+# ── Full delivery verifier ───────────────────────────────────────────────────
+
+@dataclass
+class VerifyResult:
+    hmac_ok: bool
+    pq_ok: bool
+    timestamp_ok: bool
+    kid_ok: bool
+
+    @property
+    def ok(self) -> bool:
+        return (self.hmac_ok or self.pq_ok) and self.timestamp_ok and self.kid_ok
+
+
+def verify_delivery(
+    *,
+    headers: Mapping[str, str],
+    raw_body: bytes,
+    hmac_secret: Optional[bytes] = None,
+    pq_public_key: Optional[bytes] = None,
+    pinned_kid: Optional[str] = None,
+    window_seconds: int = DEFAULT_REPLAY_WINDOW,
+    now_unix: Optional[int] = None,
+) -> VerifyResult:
+    """Verify a KXCO webhook delivery.
+
+    `headers` should have lowercase keys. `raw_body` must be the exact bytes
+    received over the wire (do not re-stringify a parsed JSON object).
+
+    Either signature alone is sufficient; verifying both is defence-in-depth.
+    """
+    timestamp = headers.get("x-kxco-timestamp", "")
+    sig_hmac = headers.get("x-kxco-signature", "")
+    sig_pq = headers.get("x-kxco-pq-signature", "")
+    kid = headers.get("x-kxco-pq-kid", "")
+
+    try:
+        ts = int(timestamp)
+    except ValueError:
+        return VerifyResult(False, False, False, False)
+
+    now = now_unix if now_unix is not None else int(time.time())
+    timestamp_ok = abs(now - ts) <= window_seconds
+    kid_ok = (pinned_kid is None) or kid_equals(kid, pinned_kid)
+
+    hmac_ok = False
+    if hmac_secret is not None and sig_hmac and timestamp_ok:
+        hmac_ok = verify_hmac(hmac_secret, timestamp, raw_body, sig_hmac)
+
+    pq_ok = False
+    if pq_public_key is not None and sig_pq and timestamp_ok and kid_ok:
+        pq_ok = verify_pq(pq_public_key, timestamp, raw_body, sig_pq)
+
+    return VerifyResult(hmac_ok=hmac_ok, pq_ok=pq_ok, timestamp_ok=timestamp_ok, kid_ok=kid_ok)
+
+
+__all__ = [
+    "envelope",
+    "hmac_hex",
+    "verify_hmac",
+    "verify_pq",
+    "fingerprint",
+    "kid_equals",
+    "verify_delivery",
+    "VerifyResult",
+    "DEFAULT_REPLAY_WINDOW",
+]

kxco_verify-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "kxco-verify"
+version = "1.0.0"
+description = "Receiver-side verifier for the KXCO hybrid HMAC + ML-DSA-65 webhook signature scheme"
+authors = [{ name = "KXCO by Knightsbridge", email = "hello@kxco.ai" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.9"
+keywords = ["post-quantum", "ml-dsa", "dilithium", "webhook", "fips-204", "kxco"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security :: Cryptography",
+]
+
+[project.optional-dependencies]
+oqs = ["liboqs-python>=0.10"]
+pqcrypto = ["pqcrypto>=0.3"]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://kxco.ai"
+Documentation = "https://chain.kxco.ai/wallet/dev-docs"
+Repository = "https://github.com/JackKXCO/kxco-post-quantum-verifiers"
+
+[tool.setuptools]
+# Single-module flat layout. Excludes test_kxco_verify.py from the wheel.
+py-modules = ["kxco_verify"]
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"

kxco_verify-1.0.0/setup.cfg

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