Metadata-Version: 2.4
Name: tibet-mirror
Version: 0.1.1
Summary: Verified Package Mirror — TIBET provenance for package mirrors, supply chain attack detection
Project-URL: Homepage, https://humotica.com
Project-URL: Repository, https://github.com/jaspertvdm/tibet-mirror
Project-URL: Documentation, https://humotica.com/docs/tibet-mirror
Project-URL: Bug Tracker, https://github.com/jaspertvdm/tibet-mirror/issues
Project-URL: TIBET Protocol, https://pypi.org/project/tibet-core/
Project-URL: IETF TIBET Draft, https://datatracker.ietf.org/doc/draft-vandemeent-tibet-provenance/
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: bandersnatch,mirror,provenance,pypi,security,supply-chain,tibet
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
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 :: Software Distribution
Requires-Python: >=3.10
Requires-Dist: jis-core>=0.4.0b1
Requires-Dist: tibet-core>=0.2.0
Provides-Extra: bandersnatch
Requires-Dist: bandersnatch>=6.0.0; extra == 'bandersnatch'
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: bandersnatch>=6.0.0; extra == 'full'
Requires-Dist: rich>=13.0.0; extra == 'full'
Description-Content-Type: text/markdown

# tibet-mirror — Verified Package Mirror with TIBET Provenance

> Every mirrored package gets a TIBET token proving: when it was mirrored, from where, and its hash at mirror time.
>
> If upstream changes (supply chain attack), the TIBET chain breaks. The mirror refuses the package.

**tibet-mirror** is an enterprise-grade package mirror (PyPI, npm) with supply chain attack detection. Every package that enters your mirror is stamped with a [TIBET](https://pypi.org/project/tibet-core/) provenance token. If the upstream registry silently replaces a package, the hash mismatch breaks the TIBET chain and your mirror rejects it.

## The Supply Chain Attack Problem

Package registries like PyPI and npm are high-value targets. An attacker who compromises an upstream package can inject malicious code into thousands of downstream systems.

```
[Upstream PyPI]                         [Your Mirror]
  requests==2.31.0                        requests==2.31.0
  sha256: abc123...                       mirror_hash: abc123...
        |                                 tibet_token: jis:mirror:...
        v                                        |
  ATTACKER replaces package!              tibet-mirror compares:
  sha256: def456... (malicious)             source_hash != mirror_hash
        |                                   TIBET chain BROKEN
        v                                        |
  Mirror pulls update...                  --> QUARANTINE. Alert.
```

## Install

```bash
pip install tibet-mirror
```

With Bandersnatch integration:

```bash
pip install tibet-mirror[bandersnatch]
```

## Quick Start

```python
from tibet_mirror import MirrorEngine, MirrorPolicy

engine = MirrorEngine(mirror_node="mirror-eu-01")

# Mirror a package — creates TIBET provenance token
record = engine.mirror_package(
    name="requests",
    version="2.31.0",
    source_url="https://pypi.org/simple/requests/",
    package_hash="abc123def456...",
)

print(record.verified)       # True
print(record.tibet_token_id) # "jis:mirror:a1b2c3d4..."

# Later: verify the package still matches upstream
result = engine.verify_package("requests", "2.31.0")
print(result)  # True — hashes still match

# Full integrity check across all mirrored versions
integrity = engine.check_integrity("requests")
print(integrity.drift_detected)  # False — no supply chain drift

# Add a policy: block packages with known CVEs
engine.add_policy(MirrorPolicy(
    name="block-known-cves",
    action="BLOCK",
    conditions={"has_cve": True, "severity": "critical"},
    description="Block packages with critical CVEs",
))
```

### CLI

```bash
tibet-mirror info       # Concept overview and supply chain attack scenario
tibet-mirror demo       # Demo: mirror packages, detect simulated attack
tibet-mirror policies   # Show default mirror policies
tibet-mirror status     # Mirror statistics
```

## How It Works

1. **Mirror** — Package is downloaded from upstream (PyPI/npm)
2. **Hash** — SHA-256 of the package at mirror time
3. **TIBET Token** — Provenance token records: who mirrored, when, from where, hash
4. **Verify** — On every sync, compare upstream hash with mirror hash
5. **Detect** — If hashes diverge, the TIBET chain breaks. Package is quarantined.

## TIBET Provenance Layers

Every mirrored package creates a TIBET token:

| Layer | Content |
|-------|---------|
| **ERIN** | Package name, version, source + mirror hashes |
| **ERAAN** | Source registry URL, upstream hash at mirror time |
| **EROMHEEN** | Mirror node, timestamp, operator |
| **ERACHTER** | Mirror reason (scheduled sync, manual, policy override) |

The token chain proves exactly which packages were mirrored when, and whether they have been tampered with since.

## Mirror Policies

| Policy | Action | Description |
|--------|--------|-------------|
| `verify-on-sync` | MIRROR | Always verify hash before accepting upstream update |
| `block-known-cves` | BLOCK | Refuse packages with known critical CVEs |
| `quarantine-new` | QUARANTINE | Hold first-time packages for manual review |
| `block-typosquat` | BLOCK | Refuse packages with names similar to popular packages |

## Bandersnatch Integration

tibet-mirror integrates with [Bandersnatch](https://github.com/pypa/bandersnatch), the official PyPI mirror tool:

```python
from tibet_mirror import MirrorEngine

engine = MirrorEngine(mirror_node="bandersnatch-eu-01")

# After Bandersnatch syncs a package, create provenance
record = engine.mirror_package(
    name="django",
    version="5.0.1",
    source_url="https://pypi.org/simple/django/",
    package_hash="...",
)

# Scan for upstream drift
drift = engine.scan_upstream("django")
print(drift)  # PackageIntegrity showing any version mismatches
```

## 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`](https://pypi.org/project/tibet-overlay/) | Identity Overlay |
| [`tibet-twin`](https://pypi.org/project/tibet-twin/) | Digital Twin Guard |
| **tibet-mirror** | Verified Package Mirror |

## 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 `evidence` · 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-sbom`](https://pypi.org/project/tibet-sbom/) · [`tibet-wayback`](https://pypi.org/project/tibet-wayback/) → · 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.
