Metadata-Version: 2.4
Name: keeper-pam-webrtc-rs
Version: 1.2.3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Security
Classifier: Topic :: Communications
License-File: LICENSE
Summary: Keeper PAM WebRTC for Python - A secure, stable, and high-performance Tube API for Python, providing WebRTC-based secure tunneling with enterprise-grade security and reliability optimizations.
License-Expression: MIT
Requires-Python: >=3.7
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Keeper PAM WebRTC for Python

A secure, stable, and high-performance **Tube API** for Python, providing WebRTC-based secure tunneling with enterprise-grade security and reliability optimizations.

## Core Values

**Security • Stability • Performance** - Built for Keeper Security's mission-critical applications:

- **🔒 Security First**: Memory-safe Rust implementation with comprehensive bounds checking
- **🛡️ Enterprise Stability**: Lock-free architecture eliminates race conditions and deadlocks  
- **⚡ Optimized Performance**: Advanced optimizations deliver exceptional speed when you need it
- **🔧 Production Ready**: Zero-configuration reliability for demanding security applications

## Description

`keeper-pam-webrtc-rs` provides Python bindings to a Rust-based **Tube API** for secure communication, designed for:

- **Secure tunneling** via WebRTC data channels with memory-safe operations
- **Multi-connection management** through tube abstractions
- **Reliable peer connection handling** with comprehensive error handling
- **Efficient channel management** for different communication patterns
- **Cross-platform compatibility** (Linux, macOS, Windows, Alpine)
- **Mission-critical reliability** for security-focused applications

This package is designed to be used with Keeper Gateway and Keeper Commander. It provides a **secure, reliable tube-based communication system** built on WebRTC, specifically tailored for Keeper Security's internal products and security-critical tunneling use cases.

> **Note**: This package is intended for internal Keeper Security products and is not being actively advertised for general use.

## Installation

```shell
pip install keeper-pam-webrtc-rs
```

## Usage

```python
import keeper_pam_webrtc_rs

# Create a tube registry
registry = keeper_pam_webrtc_rs.PyTubeRegistry()

# Define a signal callback for WebRTC events
def on_signal(signal_dict):
    print(f"Received signal: {signal_dict}")
    # Handle ICE candidates, connection state changes, etc.

# Create a server-side tube for tunneling
server_result = registry.create_tube(
    conversation_id="tunnel-session-123",
    settings={
        "conversationType": "tunnel",
        "target_host": "127.0.0.1", 
        "target_port": "22"  # SSH tunnel example
    },
    trickle_ice=True,
    callback_token="server-token",
    ksm_config="server-config",
    signal_callback=on_signal
)

# Get the offer SDP to send to the client
# NOTE: All SDP (offers, answers) are base64-encoded - use them directly, don't decode!
server_offer = server_result['offer']  # Base64-encoded WebRTC offer
server_tube_id = server_result['tube_id']

# Create a client-side tube with the offer
client_result = registry.create_tube(
    conversation_id="tunnel-client-123",
    settings={
        "conversationType": "tunnel",
        "target_host": "192.168.1.100",
        "target_port": "22"
    },
    trickle_ice=True,
    callback_token="client-token",
    ksm_config="client-config",
    offer=server_offer,  # Pass base64-encoded offer directly (don't decode!)
    signal_callback=on_signal
)

# Get the answer SDP to send back to server
client_answer = client_result['answer']  # Base64-encoded WebRTC answer
client_tube_id = client_result['tube_id']

# Set the remote description on the server
# NOTE: Pass base64-encoded answer directly
registry.set_remote_description(server_tube_id, client_answer, is_answer=True)

# Check connection state
state = registry.get_connection_state(server_tube_id)
print(f"Connection state: {state}")

# Close when done
registry.close_tube(server_tube_id)
registry.close_tube(client_tube_id)
```

### Server Mode with TCP Listener

For server tubes that listen for external TCP connections:

```python
# Create server tube with TCP listener (dynamic port)
server_result = registry.create_tube(
    conversation_id="tcp-tunnel",
    settings={
        "conversationType": "tunnel",
        "local_listen_addr": "127.0.0.1:0"  # 0 = dynamic port assignment
    },
    trickle_ice=True,
    callback_token="token",
    ksm_config="config",
    signal_callback=on_signal
)

# Get actual listening address (port assigned by OS)
listen_addr = server_result['actual_local_listen_addr']  # "127.0.0.1:59194"
host, port = listen_addr.split(':')

# External clients can now connect to this address
import socket
client = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
client.connect((host, int(port)))
# Data flows: TCP → WebRTC → Remote tube → Remote target
```

**API Documentation**: See [docs/PYTHON_API_CONTRACT.md](docs/PYTHON_API_CONTRACT.md) for complete API reference including:
- Base64 SDP encoding requirements
- Return value specifications
- Migration guides and common pitfalls

## Features

- **🔒 Memory Safety**: Rust-powered implementation prevents buffer overflows and memory corruption
- **🛡️ Reliable Architecture**: Lock-free design eliminates race conditions and ensures stability
- **⚡ Efficient Performance**: Optimized for speed without compromising security or stability
- **🌊 Tube Abstraction**: High-level API for managing WebRTC-based secure tunnels
- **🌍 Cross-Platform**: Secure, consistent behavior across Linux, macOS, Windows, Alpine
- **🐍 Python Integration**: Built with abi3 for maximum compatibility (Python 3.7+)
- **🔧 Production Hardened**: Comprehensive error handling and graceful degradation

## Tube API Architecture

This implementation provides a **Tube-based abstraction** over WebRTC:

### **Security Features**
- **Memory-Safe Operations**: Rust's ownership system prevents common security vulnerabilities
- **Bounds Checking**: Comprehensive validation prevents buffer overflows and data corruption
- **Zero Unsafe Code**: Hot paths use only verified, safe Rust code (except vetted SIMD intrinsics)
- **Graceful Error Handling**: Robust error recovery prevents crashes and data leaks

### **Tube Management**  
- **Multi-Connection Support**: Each tube can manage multiple WebRTC connections
- **Channel Abstraction**: High-level channel management for different protocols
- **State Management**: Comprehensive connection state tracking and reporting
- **Signal Handling**: Event-driven architecture for ICE candidates and state changes

### **Performance Features**
- **SIMD Optimization**: Hardware-accelerated frame parsing with safe fallbacks
- **Zero-Copy Pipelines**: Efficient data handling minimizes memory overhead
- **Event-Driven Design**: Native WebRTC events provide responsive communication
- **Always Optimized**: Maximum efficiency by default, no configuration required

## Tube API Reference

### **Core Methods**

- `create_tube(conversation_id, settings, ...)` - Create a new secure tube or add conversation to existing tube
- `set_remote_description(tube_id, sdp, is_answer)` - Set remote SDP description
- `add_ice_candidate(tube_id, candidate)` - Add ICE candidate for connection
- `get_connection_state(tube_id)` - Get current connection state
- `close_connection(connection_id)` - Close specific connection
- `close_tube(tube_id)` - Close entire tube

### **Conversation Types**

The tube API supports different communication patterns:

- **`tunnel`** - Secure TCP tunneling through WebRTC
- **`guacd`** - Apache Guacamole protocol tunneling
- **`socks5`** - SOCKS5 proxy tunneling

## Build & Verification

To build and verify the implementation:

```bash
# Standard build (all optimizations enabled)
cargo build --release

# Run comprehensive test suite
cargo test --release

# Optional: Enable debug logging for troubleshooting
cargo build --release --features production_debug
```

## Why This Implementation?

Built specifically for Keeper Security's tunneling requirements:

- **Security-First Design**: Memory safety and comprehensive validation prevent vulnerabilities
- **Mission-Critical Reliability**: Lock-free architecture ensures stable operation under load  
- **Optimized for Security Applications**: Performance optimizations that don't compromise security
- **Tube Abstraction**: High-level API designed specifically for secure tunneling use cases

**The secure, stable, high-performance tube communication system for enterprise security applications.**

