irosh 0.2.0

SSH sessions over Iroh peer-to-peer transport
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

# Irosh

**Cryptographically-Identified P2P Secure Shell and Decentralized Data Transfer Protocol.**

[![Crates.io](https://img.shields.io/crates/v/irosh.svg)](https://crates.io/crates/irosh)
[![Documentation](https://docs.rs/irosh/badge.svg)](https://docs.rs/irosh)
[![License](https://img.shields.io/crates/l/irosh.svg)](#license)

Irosh is a high-assurance remote access toolset built on the Iroh networking stack. It provides a robust library and a streamlined CLI for establishing secure shell sessions and high-speed data transfers over encrypted, hole-punched QUIC streams. 

By leveraging Ed25519 identities, Irosh eliminates the need for public IP addresses, open ports, or complex VPN configurations, making it ideal for managing distributed infrastructure across restricted networks.

---

## Installation

### CLI Binary (Recommended)
For standard interactive usage, install the pre-compiled binary via the unified installer:

**Linux / macOS / Android (Termux)**:
```bash
curl -fsSL irosh.pages.dev/install | sh
```

**Windows (PowerShell)**:
```powershell
iwr irosh.pages.dev/ps | iex
```

### From Source
If you have the Rust toolchain installed:
```bash
cargo install irosh-cli
```

---

## Core Architecture

Irosh is designed for professional environments where security and resilience are paramount.

- **Identity-Based Routing**: Peer discovery and authentication are tied to a persistent Ed25519 secret key.
- **NAT Traversal**: Automatic hole-punching and relaying via the Iroh stack ensures connectivity in complex network topologies.
- **Ad-hoc Peer Discovery**: Secure, out-of-band trust establishment using short-lived pairing codes.
- **Service-Oriented**: Native support for background execution via system services (systemd, launchd).
- **Protocol Multiplexing**: Dedicated side-channels for metadata exchange and high-performance file synchronization.

---

## Quick Start

### 1. Host Initialization
Install the background service on the host machine to enable persistent access:
```bash
irosh system install
```

### 2. Peer Pairing
Generate a temporary pairing code for initial discovery:
```bash
irosh wormhole <custom-code>
```

### 3. Establishing a Session
Connect from a client machine using the pairing code or a previously saved ticket:
```bash
irosh <code-or-ticket>
```

---

## Interactive Escape Commands
During an active session, use the `~` prefix at the start of a line for local control:
- `~?` - View all available local commands.
- `~put [-r] <local> [remote]` - Upload a file or directory.
- `~get [-r] <remote> [local]` - Download a file or directory.
- `~C` - Open the irosh local command prompt.
- `~~` - Send a literal tilde character.

---

## Developer Integration (Library)

The `irosh` crate provides a low-level API for embedding P2P SSH capabilities into custom Rust applications.

### Add to project
```bash
cargo add irosh
```

### Implementation Example
```rust,no_run
use irosh::{Server, ServerOptions, StateConfig};

#[tokio::main]
async fn main() -> irosh::Result<()> {
    let state = StateConfig::new("./state".into());
    let options = ServerOptions::new(state);
    
    let (ready, server) = Server::bind(options).await?;
    println!("Node initialized. Ticket: {}", ready.ticket);
    
    server.run().await
}
```

---

## Protocol Comparison

| Feature | OpenSSH | Irosh |
| :--- | :--- | :--- |
| **Addressing** | IP / Hostname | Cryptographic Node ID |
| **Connectivity** | Static Ports (22) | NAT Hole-punching / QUIC |
| **Identity** | External Key Management | Built-in Ed25519 Secrets |
| **Trust Model** | Manual known_hosts | Trust On First Use (TOFU) |
| **Relay Support** | Manual ProxyJump | Native Global Relay Network |

---

## Documentation

- [**Technical Manual (Library)**](src/README.md) — Architectural details, feature flags, and library integration.
- [**API Reference**](https://docs.rs/irosh) — Full technical documentation for Rust developers.
- [**Development Roadmap**](docs/ROADMAP.md) — Stability goals and the path to v1.0.

---

## License

Licensed under MIT or Apache-2.0.