Metadata-Version: 2.4
Name: tibet-trail
Version: 0.1.1
Summary: CLI audit trail reader for TIBET provenance tokens
Author: J. van de Meent
Author-email: "R. AI" <root_idd@humotica.nl>
License: MIT
Keywords: tibet,audit,provenance,cli,trail
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: tibet-core>=0.3.0
Requires-Dist: jis-core>=0.4.0b1
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# tibet-trail

CLI audit trail reader for TIBET provenance tokens. Reads, searches, and monitors JSONL files written by `tibet-core` FileStore.

## Install

```bash
pip install tibet-trail
```

## Commands

```bash
# Show recent tokens (default: 20)
tibet-trail log audit.jsonl [-n 50] [--format json|csv|text]

# Search by action/actor/time
tibet-trail search audit.jsonl --actor jis:hub --action "ping.*" --since 1h

# Trace provenance chain
tibet-trail trace audit.jsonl <token_id> [--depth 50]

# Live follow (tail -f style)
tibet-trail watch audit.jsonl [--filter-actor jis:hub]

# Verify integrity
tibet-trail verify audit.jsonl [--key <hex>]

# Statistics
tibet-trail stats audit.jsonl [--format json]

# Export to file
tibet-trail export audit.jsonl output.csv --format csv
```

## Time Filters

The `--since` flag accepts relative times: `30s`, `5m`, `1h`, `2d`, `1w` or ISO timestamps.

## Python API

```python
from tibet_trail import TrailReader

reader = TrailReader("audit.jsonl")

# Last 10 tokens
for token in reader.log(n=10):
    print(f"{token.timestamp}: {token.action} ({token.actor})")

# Search with regex
results = reader.search(action="ping.*", actor="jis:hub", since="1h")

# Trace chain
chain = reader.trace("tibet_20241217_abc12345")

# Verify integrity
report = reader.verify()
print(f"Integrity: {report['integrity']}")

# Stats
stats = reader.stats()
print(f"Total: {stats['total']}, Actors: {stats['actors']}")
```

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

## License

MIT


## 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-report`](https://pypi.org/project/tibet-report/) · 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.
