Metadata-Version: 2.4
Name: tibet-drop
Version: 0.1.0
Summary: TIBET Drop — identity-bound device-to-device payload transfer with bilateral consent. Reference Python implementation of TIBET TAT (Touch-And-Transfer) wire protocol.
Project-URL: Homepage, https://humotica.com
Project-URL: TIBET Protocol, https://pypi.org/project/tibet-zip-cli/
Author-email: Jasper van de Meent <info@humotica.com>, Humotica AI Lab <ai@humotica.nl>
License: MIT
Keywords: agentic,airdrop,byos,ed25519,humotica,identity,tibet,tibet-drop,tibet-tat,vc
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Requires-Dist: cbor2>=5.0
Requires-Dist: cryptography>=42.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# tibet-drop — TIBET Drop / TIBET TAT reference implementation

**Status:** v0.1.0 alpha (Phase 1A prototype, May 2026)
**Spec:** [`/srv/jtel-stack/hersenspinsels/airdrop/`](../../hersenspinsels/airdrop/)

`tibet-drop` is the reference Python implementation of **TIBET Drop**
(product) / **TIBET TAT** (Touch-And-Transfer wire protocol) — identity-bound
device-to-device payload transfer with bilateral consent, mutual causal
anchoring, and optional cryptographic deactivation.

## What it does

```
TIBET Drop in one breath:
  • Two devices touch (NFC handshake — UPIP-seed exchange)
  • Both verify each other's identity (Ed25519)
  • They agree to a tunnel-key (X25519 ECDH + HKDF)
  • They open an AES-256-GCM tunnel (Wi-Fi Direct or BT LE)
  • Sender ships a .tza bundle (TBZ format with airdrop manifest)
  • Both sides write paired chain tokens (transfer_out + transfer_in)
  • Sender optionally tombstones (Story 1 Wipe variant)
  • All cryptographic, all auditable, no central authority
```

The end-to-end demo (`tibet-drop demo`) walks through all nine steps of
the Phase 0 spec and produces a clean validation pass for every primitive.

## Install

```bash
pip install tibet-drop
```

(or for development, from this directory: `pip install -e .`)

## Quickstart

### Demo (end-to-end mock airdrop)

```bash
tibet-drop demo
```

Walks Alice → Bob through identity generation, handshake, tunnel
derivation, bundle pack, encrypted streaming, verification, and chain
token emission. ~10 seconds, no setup required.

### Full flow with subcommands

```bash
# 1. Both parties generate identities
tibet-drop init --aint alice.aint --out ./alice
tibet-drop init --aint bob.aint --out ./bob

# 2. Sender generates a UPIP-seed (mock NFC handshake)
tibet-drop handshake --identity ./alice --output alice.seed \
    --payload-type ai_state --wipe

# 3. Inspect the seed (decode + verify signature)
tibet-drop seed-inspect alice.seed

# 4. Pack a payload directory into a .tza bundle
BOB_PUBKEY=$(python3 -c "import json;print(json.load(open('./bob/identity.json'))['pubkey_hex'])")
tibet-drop pack \
    --identity ./alice \
    --receiver-aint bob.aint \
    --receiver-pubkey $BOB_PUBKEY \
    --input ./alice-state-dir \
    --output airdrop.tza \
    --payload-type ai_state

# 5. Verify and inspect the bundle
tibet-drop verify airdrop.tza
tibet-drop inspect airdrop.tza

# 6. Unpack on the receiver side
tibet-drop unpack airdrop.tza --out ./bob-restored
```

## Architecture

```
src/tibet_drop/
   crypto.py       Ed25519 identity, X25519 ephemeral, HKDF, AES-256-GCM
   handshake.py    UPIP-seed encode/decode/verify (CBOR, ≤512 bytes)
   tokens.py       transfer_out / transfer_in / tombstone TIBET tokens
   bundle.py       .tza pack/verify/inspect (TBZ-compatible manifest)
   demo.py         End-to-end mock airdrop demonstration
   cli.py          tibet-drop subcommands (argparse)
```

## Spec alignment

This is a reference implementation of the Phase 0 specifications in
[`/hersenspinsels/airdrop/`](../../hersenspinsels/airdrop/):

| Spec doc | Implementation |
|---|---|
| `phase-0-user-flow.md` | `cli.py`, `demo.py` (3 user stories) |
| `phase-0-tombstone-transfer-pair-spec.md` | `tokens.py` (all three) |
| `phase-0-upip-seed-and-ecdh.md` | `handshake.py` + `crypto.py` |
| `phase-0-tza-bundle-format.md` | `bundle.py` (manifest + block sigs) |
| `phase-0-multi-device-identity-model.md` | (post-MVP — single key v0.1) |

## What it does NOT do (yet)

- **Real NFC** — handshake is mock-via-file (CBOR encoded, sigs valid)
- **Real Wi-Fi Direct** — tunnel is mock-in-memory chunked AES-256-GCM
- **Multi-device delegation** — single Ed25519 key per identity (v0.1)
- **SEMA-context headers** — Phase 0 #6, post-MVP
- **Drift-record** — Phase 0 #7, post-MVP

These are well-scoped extensions for v0.2 / v0.3.

## Testing

```bash
PYTHONPATH=src python3 -m tibet_drop demo -v
```

The demo serves as both end-to-end test and live documentation.

## Compatibility with TIBET ecosystem

- `.tza` bundles are TBZ v1 compatible — readable by `tibet-zip-cli`
  for basic integrity checks (airdrop-specific manifest fields are
  additive, not breaking)
- TIBET tokens use the same canonical-form-then-sign discipline as
  the rest of the HumoticaOS substrate
- `tibet-bom` (PyPI) can ingest `transfer_out` / `transfer_in` /
  `tombstone` tokens via `collect json` for incident-transparency
  reports

## License

MIT. Author: Jasper van de Meent (Humotica).
