seigr-toolset-transmissions 0.2.0a0

Self-sovereign P2P streaming protocol with pure STC cryptography (Pre-release Alpha)

Seigr Toolset Transmissions (STT)

Secure binary transport that doesn't care what you're sending.

STT creates opaque encrypted packets that tunnel through any network (UDP, WebSocket, HTTPS) and can only be decrypted by authorized participants. No assumptions about your data - you could be streaming video, sending sensor readings, transferring files, or running your own custom protocol.

---

📖 Quick Links

• New to STT? → What is STT? - Start here
• Want to use it? → Getting Started - Installation & first program
• Need API docs? → API Reference - Complete Python API
• Curious how it works? → Architecture - Design & protocol details

---

Why STT?

Problem: Most protocols assume what you're sending (HTTP = web pages, MQTT = IoT messages, WebRTC = video calls). But what if you need secure binary transport without those assumptions?

Solution: STT provides encrypted binary packets that:

✅ Tunnel through any transport (UDP if available, WebSocket/HTTPS if firewalled)
✅ Only decrypt for authorized peers (pre-shared seed authentication)
✅ Work for any application (you define what the bytes mean)
✅ Are opaque to intermediaries (network sees encrypted binary blobs)

Use STT for: Video streaming, sensor networks, file transfer, messaging, custom protocols - anything that moves bytes securely.

---

Status

Version: 0.2.0a0 (unreleased)
Test Coverage: 93.01% (2803 statements)
Status: Alpha - core functionality implemented and tested

What works: Handshake, sessions, streams, frames, UDP/WebSocket transport, encryption, storage
Known stubs/incomplete:

• ProbabilisticStream._try_send_segment() - simulates network delivery (stub for integration)
• RelayServer._handle_forward() - counts forwarded frames but doesn't implement actual forwarding
• core/transport.py UDPTransport - placeholder class (working implementation is in transport/udp.py)

What's next: Complete stub implementations, production hardening, additional transports

---

Quick Example

import asyncio
from seigr_toolset_transmissions import STTNode

async def main():
    # Create node with pre-shared seeds
    node = STTNode(
        node_seed=b"my_node_secret_32bytes_minimum!",
        shared_seed=b"shared_secret_32bytes_minimum!",
        host="127.0.0.1",  # Default; use "0.0.0.0" to accept external connections
        port=8080
    )
    
    # Start listening
    await node.start(server_mode=True)
    
    # Receive packets from any authorized peer
    async for packet in node.receive():
        print(f"Received {len(packet.data)} bytes")
        # packet.data contains decrypted bytes
        # Only peers with matching shared_seed can send to us

asyncio.run(main())

That's it. Encrypted packets tunnel through your network automatically.

👉 Learn more: Getting Started Guide

---

How It Works

1. Pre-Shared Seeds: Both peers must have matching secrets (QR code, secure channel, etc.)
2. Handshake: 4-message mutual authentication using STC encryption
3. Encrypted Packets: All data encrypted before sending - opaque to network
4. Transport Agnostic: Packets travel over UDP, WebSocket, or any byte transport

┌─────────────┐                    ┌─────────────┐
│   Node A    │ ──[encrypted]────→ │   Node B    │
│ (shared_seed│    UDP/WebSocket   │ shared_seed)│
└─────────────┘ ←─[encrypted]───── └─────────────┘
                Only A & B can decrypt
                Network sees random bytes

👉 Deep dive: Architecture | Handshake Process | Security Model

---

Installation

Requirements: Python 3.9+

# From source (not yet on PyPI)
git clone https://github.com/Seigr-lab/SeigrToolsetTransmissions.git
cd SeigrToolsetTransmissions
pip install -e .

Dependencies:

• seigr-toolset-crypto >= 0.4.0 (STC encryption)

👉 Full guide: Installation & Setup

---

📚 Documentation

User Manual (Learn STT from scratch)

Getting Started:

• Chapter 1: What is STT? - Overview and use cases
• Chapter 2: Core Concepts - Nodes, sessions, streams
• Chapter 9: Getting Started - Installation and first program

Understanding How It Works:

• Chapter 3: Binary Protocols - Why binary?
• Chapter 4: Encryption - STC and pre-shared seeds
• Chapter 5: Handshake - 4-message authentication
• Chapter 6: Sessions - Session lifecycle
• Chapter 7: Streams - Multiplexing explained
• Chapter 8: Transport - UDP vs WebSocket

Using STT:

• Chapter 10: Common Patterns - Real-world examples
• Chapter 11: Error Handling - Troubleshooting
• Chapter 12: Performance - Optimization

Security & Design:

• Chapter 13: Security Model - Threat model
• Chapter 14: Comparisons - STT vs HTTP/gRPC/WebRTC/QUIC
• Chapter 15: Design Decisions - Why STT works this way

Reference:

• Glossary - All terms defined
• Frame Format - Binary format spec
• Configuration - All settings
• Error Codes - Complete error reference

API & Technical Docs

• API Reference - Complete Python API for all components
• Architecture - Design philosophy and protocol stack
• STC Dependency - External crypto library docs

Development

• Environment Setup - Dev environment
• CHANGELOG - Version history

---

Components

STT is built from these core components (all with dedicated documentation):

• STTNode - Main runtime (85.56% tested)
• Handshake - Mutual authentication (87.93% tested)
• Sessions - Connection management (100% tested)
• Streams - Multiplexed channels (99.24% tested)
• Frames - Binary protocol (98.26% tested)
• Transport - UDP/WebSocket (84-90% tested)
• Chamber - Encrypted storage (96.97% tested)
• STCWrapper - Cryptography (98.78% tested)

👉 Full component docs: API Reference

---

Testing

pytest tests/ -v --cov

Coverage: 93.01% (2803 statements)
Test suite: 200+ tests covering all core components

---

Security

STT has undergone comprehensive security auditing:

• ✅ Bandit static analysis: 0 issues (6679 lines of code scanned)
• ✅ Safety dependency check: 0 vulnerabilities
• ✅ pip-audit OSV database: 0 vulnerabilities in STT code

All identified security issues have been fixed, including:

• SHA1 usage properly marked as non-cryptographic (WebSocket handshake only)
• Default bind addresses set to localhost (127.0.0.1) for security
• Pickle replaced with JSON for storage serialization
• Secrets module used for cryptographic randomness
• Comprehensive error logging for debugging

👉 Full security audit: Security Audit Summary

---

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Development: See Environment Setup

---

License

ANTI-CAPITALIST SOFTWARE LICENSE (v 1.4)

See LICENSE for full details.

---

Support & Community

• Issues: GitHub Issues
• Sponsor: GitHub Sponsors