Metadata-Version: 2.4
Name: pytether
Version: 0.1.0
Summary: ThreadProof: a non-isomorphic lattice-based post-quantum identity proof system
Project-URL: Homepage, https://github.com/obinexus/pytether
Project-URL: Repository, https://github.com/obinexus/pytether
Author-email: OBINexus Computing <support@obinexus.org>
License: MIT
Keywords: cryptography,identity,lattice,post-quantum,threadproof
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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.

| 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

```bash
# 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

```bash
# 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

```python
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

```bash
# 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
