pytether

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

OBINexus Computing · support@obinexus.org

⚠️ 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.

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

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 — support@obinexus.org — https://github.com/obinexus