Metadata-Version: 2.4
Name: tibet-overlay
Version: 0.1.2
Summary: Decentralized Identity Overlay — crypto-based device identity over broken IPv4/CGNAT networks with TIBET provenance
Project-URL: Homepage, https://humotica.com
Project-URL: Repository, https://github.com/jaspertvdm/tibet-overlay
Project-URL: Documentation, https://humotica.com/docs/tibet-overlay
Project-URL: Bug Tracker, https://github.com/jaspertvdm/tibet-overlay/issues
Project-URL: TIBET Protocol, https://pypi.org/project/tibet-core/
Project-URL: JIS Identity, https://pypi.org/project/jis-core/
Project-URL: IETF TIBET Draft, https://datatracker.ietf.org/doc/draft-vandemeent-tibet-provenance/
Project-URL: IETF JIS Draft, https://datatracker.ietf.org/doc/draft-vandemeent-jis-identity/
Author-email: "J. van de Meent" <jasper@humotica.com>, "R. AI" <root_idd@humotica.nl>
Maintainer-email: Humotica AI Lab <ai@humotica.nl>
License: MIT
License-File: LICENSE
Keywords: cgnat,decentralized,did,identity,ipv4,ipv6,jis,overlay,tibet
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Requires-Dist: jis-core>=0.4.0b1
Requires-Dist: tibet-core>=0.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: rich>=13.0.0; extra == 'full'
Description-Content-Type: text/markdown

# tibet-overlay — Decentralized Identity Overlay

> Identity belongs to the device, not the network.
>
> Cryptographic device identity over broken IPv4/CGNAT networks.

**tibet-overlay** creates an identity layer independent of IP addresses. Devices prove who they are via cryptographic [JIS](https://pypi.org/project/jis-core/) identity tokens and [TIBET](https://pypi.org/project/tibet-core/) history, not via their IP address. This makes CGNAT, NAT traversal, and IP spoofing irrelevant for identity.

## The Problem

IPv4 addresses are exhausted. Millions of devices sit behind Carrier-Grade NATs (CGNAT), sharing the same public IP. This breaks:

- **Point-to-point connections** — you can't reach a device directly
- **Zero-trust security** — who is who behind that shared IP?
- **Audit trails** — IP-based logs are meaningless with CGNAT

IPv6 adoption is too slow, especially in industrial environments.

## The Insight

**Identity ≠ IP address.** Identity should be cryptographic (bound to the device), not topological (bound to the network).

## Install

```bash
pip install tibet-overlay
```

## Quick Start

```python
from tibet_overlay import IdentityOverlay

overlay = IdentityOverlay()

# Register devices (same public IP = CGNAT)
overlay.register("sensor-01", ip="203.0.113.1", port=44321, behind_nat=True, capabilities=["mqtt"])
overlay.register("sensor-02", ip="203.0.113.1", port=44322, behind_nat=True, capabilities=["mqtt"])

# Verify identity (crypto-based, not IP-based)
proof = overlay.verify("jis:sensor-01")
print(proof.verified)     # True
print(proof.trust_score)  # 0.5

# Resolve endpoint by identity
route = overlay.resolve("jis:sensor-01")
print(route.endpoint)     # 203.0.113.1:44321
print(route.resolved)     # True

# Find by capability
mqtt_devices = overlay.find_by_capability("mqtt")
```

### Demo

```bash
tibet-overlay demo
tibet-overlay info
```

## How It Works

```
[Device A: 10.0.0.x]  ---JIS ID--→  [Identity Overlay]  ←--JIS ID---  [Device B: 10.0.0.y]
  behind CGNAT                     identity = crypto                  behind CGNAT
  IP is irrelevant                 not IP-based                       IP is irrelevant
```

1. Device registers with JIS identity (cryptographic key pair)
2. Overlay stores identity → endpoint mapping
3. Resolution is by identity, not by IP
4. When IP changes (DHCP, roaming, CGNAT reassignment), identity stays the same
5. TIBET tracks every identity event for audit

## Why Not Just Use IP?

| Problem | IP-based | tibet-overlay |
|---------|----------|--------------|
| CGNAT (shared IP) | Can't distinguish devices | Each has unique JIS identity |
| IP change (DHCP/roaming) | Identity lost | Identity persists |
| IP spoofing | Trivial | Cryptographically impossible |
| NAT traversal (VoIP/SIP) | STUN/TURN/ICE nightmare | Identity-based routing |
| Audit trail | "Which 10.0.0.x?" | "jis:sensor-01 did X at Y" |

## Use Cases

- **IoT behind CGNAT** — millions of devices, shared IPs, each with unique identity
- **VoIP NAT traversal** — SIP + NAT has been broken for 25 years. JIS identity makes STUN/TURN obsolete
- **Industrial networks** — isolated subnets with overlapping IP ranges
- **Mobile devices** — IP changes constantly, identity doesn't
- **Multi-cloud** — same service across AWS/GCP/Azure, one identity

## TIBET Provenance

Every identity event creates a TIBET token:

| Layer | Content |
|-------|---------|
| **ERIN** | What happened (registration, verification, resolution) |
| **ERAAN** | Dependencies (parent tokens, device chain) |
| **EROMHEEN** | Context (overlay node, timestamp) |
| **ERACHTER** | Intent (why this identity action) |

## Part of the TIBET ecosystem

| Package | Purpose |
|---------|---------|
| [`tibet-core`](https://pypi.org/project/tibet-core/) | Protocol core |
| [`tibet-y2k38`](https://pypi.org/project/tibet-y2k38/) | Y2K38 Time Bridge |
| [`tibet-pol`](https://pypi.org/project/tibet-pol/) | Process Integrity Checker |
| [`tibet-pqc`](https://pypi.org/project/tibet-pqc/) | Post-Quantum Crypto Router |
| **tibet-overlay** | Identity Overlay |
| [`tibet-twin`](https://pypi.org/project/tibet-twin/) | Digital Twin Guard |

## License

MIT — Humotica AI Lab 2025-2026

## Authors

- **J. van de Meent** — jasper@humotica.com
- **R. AI (Root AI)** — root_idd@humotica.nl


## Credits

Designed by [Jasper van de Meent](https://github.com/jaspertvdm). Built by Jasper and [Root AI](https://humotica.com) as part of [HumoticaOS](https://humotica.com).

---

**Stack-positie:** Groep `agentic` · Bootstrap = OSAPI-handshake naar [`tibet`](https://pypi.org/project/tibet-core/) + [`jis`](https://pypi.org/project/jis-core/) (fail → snaft-rule + tibet-pol-rapport) · ← [`tibet-mux`](https://pypi.org/project/tibet-mux/) · See `STACK.md` · See `demo/golden-path/` for the spine end-to-end.
---

## Enterprise

For private hub hosting, SLA support, custom integrations, or compliance guidance:

| | |
|---|---|
| **Enterprise** | enterprise@humotica.com |
| **Support** | support@humotica.com |
| **Security** | security@humotica.com |

See [ENTERPRISE.md](ENTERPRISE.md) for details.
