Files

glm-5.1 dad8224686 Add architecture specification for wraith SSH tunnel tool

Docs:
- README.md: index with doc table, ADR table, lifecycle definitions
- overview.md: purpose, exports, dependencies, constraints
- transport.md: Transport trait, TCP/TLS/iroh implementations, stream join
- client.md: SOCKS5 server, port forwarding, channel manager, reconnection
- server.md: auth, channel handling, stealth mode, outbound proxy
- tun-shim.md: separate privileged process, virtual DNS, --unshare mode
- napi-and-pubsub.md: NAPI wrapper, pubsub event target adapter

ADRs:
- 001: Pluggable transport via AsyncRead+AsyncWrite trait
- 002: TUN shim as separate process
- 003: iroh stream via tokio::io::join
- 004: SSH runs over transport, not alongside
- 005: SOCKS5 as primary interface, TUN as add-on
- 006(007): NAPI exposes single duplex stream

Open questions: 11 items covering TLS certs, iroh relay defaults,
Windows TUN, auth expansion, NAPI surface, TCP reconstruction

2026-06-01 15:01:45 +00:00

2.0 KiB

Raw Blame History

status, last_updated

status	last_updated
draft	2026-06-01

Wraith Architecture

Current State

Pre-implementation. Feasibility assessment complete (see research/ssh-tunnel-vpn-alternative-feasibility.md). Architecture specification in progress.

Architecture Documents

Document	Status	Description
overview.md	draft	Package purpose, exports, dependencies
transport.md	draft	Transport abstraction: TCP, TLS, iroh
client.md	draft	Client connection, SOCKS5, port forwarding
server.md	draft	Server acceptance, channel handling, proxy
tun-shim.md	draft	Privileged TUN interface wrapper (separate process)
napi-and-pubsub.md	draft	NAPI wrapper and pubsub event target adapter

ADR Table

ADR	Title	Status
001	Pluggable transport via `AsyncRead+AsyncWrite` trait	Accepted
002	TUN shim as separate process	Accepted
003	iroh stream via `tokio::io::join`	Accepted
004	SSH runs over transport, not alongside	Accepted
005	SOCKS5 as primary interface, TUN as add-on	Accepted

Open Questions

See open-questions.md

Lifecycle Definitions

Status	Meaning	Transitions
`draft`	Under active development. May change significantly.	→ `reviewed` when open questions resolved
`reviewed`	Architecture final. Implementation may begin. Changes require review.	→ `stable` when implementation verified
`stable`	Locked. Changes require review and may warrant an ADR.	→ `deprecated` when superseded
`deprecated`	Superseded. Kept for reference.	Removed when no longer referenced

2.0 KiB Raw Blame History