pytether 0.1.0

ThreadProof: a non-isomorphic lattice-based post-quantum identity proof system

pytether

ThreadProof — Non-Isomorphic Lattice-Based Post-Quantum Identity Proof

OBINexus Computing · [e-mail]

---

⚠️ Security Warning

This package is a proof-faithful MVP. It is not a formally hardened cryptographic library and has not been audited. Do not use it to protect real sensitive data.

Component	Status
HKDF-SHA3-512	✅ Standard-library implementation, RFC 5869 faithful
Commitment scheme	✅ HMAC-SHA3-512, constant-time comparison
Witness (SamplePre)	⚠️ Deterministic noise approximation — not a full trapdoor sampler
LWE hardness	⚠️ Structural approximation — no formal reduction proven for this code
Post-quantum security	⚠️ Aspirational — the proof document provides the theoretical basis; this implementation does not provide certified PQ security

---

Project Summary

pytether is a Python implementation of the ThreadProof identity system defined by OBINexus Computing. ThreadProof uses non-isomorphic lattice structures to create identity proofs that are:

• Coordinate-locked — valid only in the coordinate space in which they were generated (Axiom 4.1)
• Context-bound — derived keys bind the proof to a specific application context (Axiom 4.3)
• Non-transferable — proofs from one coordinate system cannot be transplanted into another (Axiom 4.2)
• Audit-integrated — every operation is recorded in an append-only audit log

---

ThreadProof Concept Mapping

Spec concept	Package location	Notes
CID tuple (I, V, S, B, E, K, P, C)	pytether.cid.CID	All eight fields present
ZID:QZ-Lattice-<digits> format	pytether.cid, pytether.patterns	Regex-validated
HKDF-SHA3-512 encoding function	pytether.crypto.hkdf_sha3_512	Standard-library only
Algorithm 1 — Key Generation	pytether.core.PyTether.keygen
Algorithm 2 — Proof Generation	pytether.core.PyTether.prove
Algorithm 3 — Verification	pytether.core.PyTether.verify
SecureAuditNode	pytether.audit.AuditLog	Append-only in-memory log
Pattern registration	pytether.patterns	Auto-registered on import
Congregation Linker	pytether.core.PyTether	Orchestrates all components
Coordinate-system lock	pk.coordinate_system == proof.coordinate_system	Checked first in verify

---

Install

# From GitHub (latest)
pip install git+https://github.com/obinexus/pytether.git

# Local editable install (development)
git clone https://github.com/obinexus/pytether.git
cd pytether
pip install -e .

Requires Python 3.11+. No third-party dependencies.

---

CLI Examples

# Generate a key pair
pytether keygen --public-key pk.json --secret-key sk.json

# Generate a proof
pytether prove --secret-key sk.json --message "hello" --context "my-app-v1"

# Verify the proof
pytether verify --public-key pk.json --proof out/proof.json \
    --message "hello" --context "my-app-v1"

# End-to-end demo (prints full JSON output)
pytether demo --message "hello-threadproof" --context "demo"

# Custom coordinate system
pytether keygen --coordinate-system Polar --public-key pk_polar.json --secret-key sk_polar.json

Exit codes: 0 = success / verification accepted, 1 = verification rejected, 2 = error.

---

Python API

from pytether import PyTether, CID

# --- Key generation ---
tether = PyTether()
public_key, secret_key = tether.keygen(
    coordinate_system="Cartesian",   # Axiom 4.1: locks the proof to this space
    lattice_dimension=16,
    modulus=12289,
    bound=512,
)

print(public_key.cid.identity)       # e.g. "ZID:QZ-Lattice-3741"

# --- Proof generation ---
proof = tether.prove(
    secret_key,
    message="hello",
    context="my-application-v1",
)

# --- Verification ---
ok = tether.verify(public_key, proof, message="hello", context="my-application-v1")
assert ok  # True

# Wrong message → False
ok = tether.verify(public_key, proof, message="goodbye", context="my-application-v1")
assert not ok

# --- Audit log ---
for event in tether.audit_log.events:
    print(event.operation, event.success, event.zid)

# --- Serialisation ---
import json
pk_json = json.dumps(public_key.to_dict(), indent=2)
sk_json = json.dumps(secret_key.to_dict(), indent=2)
proof_json = json.dumps(proof.to_dict(), indent=2)

from pytether.models import PublicKey, SecretKey, Proof
pk2    = PublicKey.from_dict(json.loads(pk_json))
sk2    = SecretKey.from_dict(json.loads(sk_json))
proof2 = Proof.from_dict(json.loads(proof_json))

---

Development & Testing

# Install in editable mode
pip install -e .

# Run the full test suite
pytest

# Run with verbose output
pytest -v

# Run a specific test file
pytest tests/test_core.py -v

---

Repository Structure

pytether/
├── pyproject.toml
├── README.md
├── src/
│   └── pytether/
│       ├── __init__.py     # Public API re-exports
│       ├── cid.py          # Canonical Identity Definition
│       ├── crypto.py       # HKDF-SHA3-512, witness derivation
│       ├── models.py       # PublicKey, SecretKey, Proof dataclasses
│       ├── core.py         # PyTether: keygen, prove, verify
│       ├── audit.py        # AuditEvent, AuditLog
│       ├── patterns.py     # ThreadProof pattern registry
│       └── cli.py          # CLI entry point
└── tests/
    ├── test_cid.py
    ├── test_core.py
    └── test_cli.py

---

Contact

OBINexus Computing — [e-mail] — https://github.com/obinexus