khipu-consensus 0.1.0__tar.gz

khipu_consensus-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: khipu-consensus
+Version: 0.1.0
+Summary: Byzantine-fault-tolerant multi-party signed agreement (3-of-4 BFT) over DSSE/cosign per-witness signatures.
+Author-email: Yachay <yachay@szlholdings.dev>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/szl-holdings/khipu-consensus
+Project-URL: Source, https://github.com/szl-holdings/khipu-consensus
+Project-URL: Issues, https://github.com/szl-holdings/khipu-consensus/issues
+Project-URL: Changelog, https://github.com/szl-holdings/khipu-consensus/releases
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41.0
+Provides-Extra: service
+Requires-Dist: fastapi>=0.100; extra == "service"
+Requires-Dist: uvicorn>=0.23; extra == "service"
+Requires-Dist: pydantic>=2.0; extra == "service"
+Provides-Extra: remote
+Requires-Dist: requests>=2.28; extra == "remote"
+Provides-Extra: spine
+Requires-Dist: szl-receipt-dsse>=0.3.1; extra == "spine"
+
+# khipu-consensus (Python)
+
+Byzantine-fault-tolerant multi-party signed agreement — a 3-of-4 witness quorum over
+DSSE/cosign per-witness signatures. This is the Python package for the
+[szl-holdings/khipu-consensus](https://github.com/szl-holdings/khipu-consensus) repository;
+the repository README carries the full doctrine, demo links, and evidence boundaries.
+
+```bash
+pip install khipu-consensus
+khipu-verify --help
+```
+
+Doctrine boundary: safety and liveness of the quorum are **Conjecture 2 / Conjecture 3**
+(proof-deferred, not proven). Λ remains Conjecture 1. Nothing in this package asserts a
+theorem it does not carry.
+
+Optional extras: `service` (FastAPI witness API), `remote` (HTTP SDK transport),
+`spine` (fold a witnessed decision into one canonical `szl-receipt-dsse` receipt).
+
+License: Apache-2.0 · Source: https://github.com/szl-holdings/khipu-consensus

khipu_consensus-0.1.0/README.md

@@ -0,0 +1,20 @@
+# khipu-consensus (Python)
+
+Byzantine-fault-tolerant multi-party signed agreement — a 3-of-4 witness quorum over
+DSSE/cosign per-witness signatures. This is the Python package for the
+[szl-holdings/khipu-consensus](https://github.com/szl-holdings/khipu-consensus) repository;
+the repository README carries the full doctrine, demo links, and evidence boundaries.
+
+```bash
+pip install khipu-consensus
+khipu-verify --help
+```
+
+Doctrine boundary: safety and liveness of the quorum are **Conjecture 2 / Conjecture 3**
+(proof-deferred, not proven). Λ remains Conjecture 1. Nothing in this package asserts a
+theorem it does not carry.
+
+Optional extras: `service` (FastAPI witness API), `remote` (HTTP SDK transport),
+`spine` (fold a witnessed decision into one canonical `szl-receipt-dsse` receipt).
+
+License: Apache-2.0 · Source: https://github.com/szl-holdings/khipu-consensus

khipu_consensus-0.1.0/khipu_consensus/__init__.py

@@ -0,0 +1,196 @@
+# SPDX-License-Identifier: Apache-2.0
+# © 2026 Lutar, Stephen P. — SZL Holdings · ORCID 0009-0001-0110-4173
+"""
+khipu-consensus — Byzantine-fault-tolerant multi-party signed agreement.
+
+The category: multi-party-witnessed AI. Each witness ("organ") signs an action
+hash with its own ECDSA-P256 key. >= threshold valid `allow` signatures over the
+same action hash ⇒ the action is CANONICAL (BFT n witnesses, f = n - threshold
+tolerated faults; 3-of-4 tolerates 1). Every per-witness signature is
+ECDSA-P256-SHA256 over the DSSE (Dead-Simple-Signing-Envelope) Pre-Authentication
+Encoding, so it is verifiable by `cosign verify-blob --key <witness>.pub`.
+
+Reference implementation. Mirrors typescript/ and go/ byte-for-byte on the same
+deterministic test vectors (testdata/vectors.json).
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from dataclasses import dataclass, field
+from typing import Optional
+
+ORGAN_VERDICT_PAYLOAD_TYPE = "application/vnd.szl.khipu.organ-verdict+json"
+__version__ = "0.1.0"
+
+
+def canonical_json(obj) -> bytes:
+    """Deterministic canonical JSON: sorted keys, compact separators, UTF-8."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def pae(payload_type: str, body: bytes) -> bytes:
+    """DSSE Pre-Authentication Encoding (DSSEv1)."""
+    t = payload_type.encode("utf-8")
+    return b"DSSEv1 " + str(len(t)).encode() + b" " + t + b" " + str(len(body)).encode() + b" " + body
+
+
+@dataclass
+class OrganVerdict:
+    organ: str
+    keyid: str
+    payload_type: str
+    payload_b64: str          # base64 of the canonical signed statement
+    signature_b64: str        # base64 of the ECDSA-P256-SHA256 signature over PAE
+    verdict: str = "allow"    # informational; the authoritative verdict is inside payload
+    reason: str = ""
+
+    @staticmethod
+    def from_dict(d: dict) -> "OrganVerdict":
+        return OrganVerdict(
+            organ=d.get("organ", ""),
+            keyid=d.get("keyid", ""),
+            payload_type=d.get("payloadType", ORGAN_VERDICT_PAYLOAD_TYPE),
+            payload_b64=d.get("payload", ""),
+            signature_b64=d.get("signature", ""),
+            verdict=d.get("verdict", "allow"),
+            reason=d.get("reason", ""),
+        )
+
+
+@dataclass
+class OrganCheck:
+    organ: str
+    keyid: str
+    valid: bool
+    verdict: Optional[str]
+    action_hash_match: bool
+    counts: bool
+    reason: str = ""
+
+
+@dataclass
+class ConsensusResult:
+    action_hash: str
+    threshold: int
+    n: int
+    consensus_count: int
+    decision: str
+    checks: list = field(default_factory=list)
+
+    @property
+    def khipu_consensus(self) -> str:
+        return f"{self.consensus_count}-of-{self.n}"
+
+
+def sign_verdict(organ: str, action_hash: str, verdict: str, private_key_pem: str,
+                 reason: str = "", lean_sha: str = "", ts: str = "") -> dict:
+    """Produce a DSSE-signed organ verdict dict (the wire shape)."""
+    from cryptography.hazmat.primitives.serialization import load_pem_private_key
+    from cryptography.hazmat.primitives.asymmetric import ec
+    from cryptography.hazmat.primitives import hashes
+    from datetime import datetime, timezone
+
+    keyid = f"{organ}-cosign"
+    statement = {
+        "schema": "szl.khipu.organ_verdict/v1", "organ": organ, "keyid": keyid,
+        "action_hash": action_hash, "verdict": verdict, "reason": reason,
+        "lean_sha": lean_sha, "ts": ts or datetime.now(timezone.utc).isoformat(),
+    }
+    body = canonical_json(statement)
+    priv = load_pem_private_key(private_key_pem.encode(), password=None)
+    sig = priv.sign(pae(ORGAN_VERDICT_PAYLOAD_TYPE, body), ec.ECDSA(hashes.SHA256()))
+    return {
+        "organ": organ, "keyid": keyid, "payloadType": ORGAN_VERDICT_PAYLOAD_TYPE,
+        "payload": base64.b64encode(body).decode(), "signature": base64.b64encode(sig).decode(),
+        "verdict": verdict, "reason": reason,
+    }
+
+
+def verify_verdict(v: OrganVerdict, public_key_pem: str, action_hash: str) -> OrganCheck:
+    """Verify one organ's signature against its public key, and check that the
+    signed action_hash and verdict are internally consistent."""
+    from cryptography.hazmat.primitives.serialization import load_pem_public_key
+    from cryptography.hazmat.primitives.asymmetric import ec
+    from cryptography.hazmat.primitives import hashes
+    from cryptography.exceptions import InvalidSignature
+
+    if not v.payload_b64 or not v.signature_b64:
+        return OrganCheck(v.organ, v.keyid, False, None, False, False, "missing payload/signature")
+    # A valid signature from the same key in a different DSSE domain is not a
+    # Khipu witness verdict. Bind both the protocol and expected wire identity.
+    if v.payload_type != ORGAN_VERDICT_PAYLOAD_TYPE:
+        return OrganCheck(v.organ, v.keyid, False, None, False, False, "payload-type-mismatch")
+    expected_keyid = f"{v.organ}-cosign"
+    if not v.organ or v.keyid != expected_keyid:
+        return OrganCheck(v.organ, v.keyid, False, None, False, False, "witness-identity-mismatch")
+    try:
+        body = base64.b64decode(v.payload_b64)
+        to_verify = pae(v.payload_type, body)
+        pub = load_pem_public_key(public_key_pem.encode())
+        try:
+            pub.verify(base64.b64decode(v.signature_b64), to_verify, ec.ECDSA(hashes.SHA256()))
+        except InvalidSignature:
+            return OrganCheck(v.organ, v.keyid, False, None, False, False, "signature mismatch")
+        decoded = json.loads(body)
+        if not isinstance(decoded, dict) or decoded.get("schema") != "szl.khipu.organ_verdict/v1":
+            return OrganCheck(v.organ, v.keyid, False, None, False, False, "statement-schema-mismatch")
+        if decoded.get("organ") != v.organ or decoded.get("keyid") != expected_keyid:
+            return OrganCheck(v.organ, v.keyid, False, None, False, False, "signed-witness-identity-mismatch")
+        ah_match = decoded.get("action_hash") == action_hash
+        verdict = decoded.get("verdict")
+        counts = ah_match and verdict == "allow"
+        return OrganCheck(v.organ, v.keyid, True, verdict, ah_match, counts)
+    except Exception as e:
+        return OrganCheck(v.organ, v.keyid, False, None, False, False, f"{type(e).__name__}: {e}")
+
+
+def _valid_quorum_counts(threshold: int, n: int) -> bool:
+    return type(threshold) is int and type(n) is int and 1 <= threshold <= n
+
+
+def tally(action_hash: str, verdicts: list, pubkeys: dict,
+          threshold: int = 3, n: int = 4) -> ConsensusResult:
+    """Count valid + allow signatures over `action_hash`; apply the BFT threshold.
+
+    Each witness ("organ") counts AT MOST ONCE: consensus is a property of
+    DISTINCT witnesses, not of raw verdict rows. A second valid `allow` from an
+    organ that already counted is recorded (``counts=False``, reason
+    "duplicate-witness (already counted)") but does NOT increment the tally, so
+    resubmitting one genuine verdict cannot inflate ``consensus_count`` past the
+    honest distinct-witness threshold. Mirrors typescript/ and go/ and the
+    distinctness the Lean ``validCount`` model assumes.
+
+    verdicts: list of dict|OrganVerdict|None (None = abstain/timeout).
+    pubkeys : {organ: PEM}.
+    Invalid quorum counts reject before verification: n and threshold must be
+    positive integers (not booleans), with threshold <= n. They are not coerced.
+    """
+    if not _valid_quorum_counts(threshold, n):
+        return ConsensusResult(action_hash, threshold, n, 0, "rejected", [])
+    checks = []
+    counted: set = set()
+    count = 0
+    for item in verdicts:
+        if item is None:
+            checks.append(OrganCheck(None, None, False, None, False, False, "abstain/timeout"))
+            continue
+        v = item if isinstance(item, OrganVerdict) else OrganVerdict.from_dict(item)
+        pem = pubkeys.get(v.organ, "")
+        if not pem:
+            checks.append(OrganCheck(v.organ, v.keyid, False, None, False, False, "no public key"))
+            continue
+        chk = verify_verdict(v, pem, action_hash)
+        if chk.counts and v.organ in counted:
+            checks.append(OrganCheck(
+                v.organ, v.keyid, chk.valid, chk.verdict, chk.action_hash_match,
+                False, "duplicate-witness (already counted)",
+            ))
+            continue
+        if chk.counts:
+            counted.add(v.organ)
+            count += 1
+        checks.append(chk)
+    decision = "canonical" if count >= threshold else "rejected"
+    return ConsensusResult(action_hash, threshold, n, count, decision, checks)