Files

glm-5.1 af8e7e8b44 Review architecture specs, address critical/warning issues, mark reviewed

Address 5 critical and 7 warning issues from architecture review:
- Fix duplicate sentence in napi-and-pubsub.md server side section
- Add wraith- namespace reservation to server.md constraints (ADR-018)
- Document stealth mode TLS-only requirement in server.md
- Create ADR-019 for --proxy dual semantics (client vs server)
- Clarify NAPI connect() vs CLI wraith connect distinction
- Add SOCKS5h default as privacy design decision in client.md
- Expand reconnection section (always-on, re-register port forwards)
- Add graceful shutdown sections to client.md and server.md
- Specify OpenSSH key format for path-or-buffer inputs across all docs
- Resolve pubsub alternative approach ambiguity (ADR-018 is primary)
- Replace server.md handler impl block with behavioral description
- Standardize iroh endpoint ID terminology (base58-encoded)
- Remove iroh API implementation details from transport.md/server.md
- Add error handling pattern as cross-cutting concern in overview.md
- Update all document statuses from draft to reviewed

2026-06-02 07:44:42 +00:00

3.5 KiB

Raw Blame History

status, last_updated

status	last_updated
reviewed	2026-06-02

Wraith Architecture

Current State

Architecture specification reviewed and ready for implementation. All open questions resolved. 19 ADRs accepted.

Architecture Documents

Document	Status	Description
overview.md	reviewed	Package purpose, exports, dependencies
transport.md	reviewed	Transport abstraction: TCP, TLS, iroh
client.md	reviewed	Client connection, SOCKS5, port forwarding
server.md	reviewed	Server acceptance, channel handling, proxy
tun-shim.md	deprecated	TUN interface wrapper — deferred, use tun2proxy
napi-and-pubsub.md	reviewed	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	Superseded by ADR-014
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
006	No logging of tunnel destinations	Accepted
007	NAPI exposes single duplex stream	Accepted
008	ACME/Let's Encrypt certificate provisioning	Accepted
009	Default iroh relay with override	Accepted
010	Transport chaining in CLI	Accepted
011	Programmatic-first API, no file-based config	Accepted
012	Ed25519 keys + OpenSSH cert-authority, no password auth	Accepted
013	Fail2ban-friendly logging + built-in rate limiting	Accepted
014	Defer TUN, recommend local SOCKS5 + tun2proxy	Accepted
015	napi-rs for FFI bridge	Accepted
016	NAPI exposes both connect() and serve()	Accepted
017	Stealth mode — protocol multiplexing on port 443	Accepted
018	Control channel for pubsub over SSH	Accepted
019	`--proxy` dual semantics (client vs server)	Accepted

Open Questions

All open questions have been resolved. See open-questions.md for details on each resolution.

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

3.5 KiB Raw Blame History