glm-5.1
af8e7e8b44
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
58 lines
3.5 KiB
Markdown
58 lines
3.5 KiB
Markdown
---
|
|
status: reviewed
|
|
last_updated: 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](overview.md) | reviewed | Package purpose, exports, dependencies |
|
|
| [transport.md](transport.md) | reviewed | Transport abstraction: TCP, TLS, iroh |
|
|
| [client.md](client.md) | reviewed | Client connection, SOCKS5, port forwarding |
|
|
| [server.md](server.md) | reviewed | Server acceptance, channel handling, proxy |
|
|
| [tun-shim.md](tun-shim.md) | deprecated | TUN interface wrapper — **deferred**, use tun2proxy |
|
|
| [napi-and-pubsub.md](napi-and-pubsub.md) | reviewed | NAPI wrapper and pubsub event target adapter |
|
|
|
|
## ADR Table
|
|
|
|
| ADR | Title | Status |
|
|
|-----|-------|--------|
|
|
| [001](decisions/001-pluggable-transport.md) | Pluggable transport via `AsyncRead+AsyncWrite` trait | Accepted |
|
|
| [002](decisions/002-tun-separate-process.md) | TUN shim as separate process | Superseded by ADR-014 |
|
|
| [003](decisions/003-iroh-stream-join.md) | iroh stream via `tokio::io::join` | Accepted |
|
|
| [004](decisions/004-ssh-over-transport.md) | SSH runs over transport, not alongside | Accepted |
|
|
| [005](decisions/005-socks5-before-tun.md) | SOCKS5 as primary interface, TUN as add-on | Accepted |
|
|
| [006](decisions/006-no-logging-of-tunnel-destinations.md) | No logging of tunnel destinations | Accepted |
|
|
| [007](decisions/007-napi-single-stream.md) | NAPI exposes single duplex stream | Accepted |
|
|
| [008](decisions/008-acme-lets-encrypt.md) | ACME/Let's Encrypt certificate provisioning | Accepted |
|
|
| [009](decisions/009-default-iroh-relay.md) | Default iroh relay with override | Accepted |
|
|
| [010](decisions/010-transport-chaining-cli.md) | Transport chaining in CLI | Accepted |
|
|
| [011](decisions/011-no-ssh-config-programmatic-api.md) | Programmatic-first API, no file-based config | Accepted |
|
|
| [012](decisions/012-auth-ed25519-and-cert-authority.md) | Ed25519 keys + OpenSSH cert-authority, no password auth | Accepted |
|
|
| [013](decisions/013-fail2ban-friendly-logging.md) | Fail2ban-friendly logging + built-in rate limiting | Accepted |
|
|
| [014](decisions/014-defer-tun-recommend-socks5-proxy.md) | Defer TUN, recommend local SOCKS5 + tun2proxy | Accepted |
|
|
| [015](decisions/015-napi-rs-for-ffi-bridge.md) | napi-rs for FFI bridge | Accepted |
|
|
| [016](decisions/016-napi-expose-connect-and-serve.md) | NAPI exposes both connect() and serve() | Accepted |
|
|
| [017](decisions/017-stealth-mode-protocol-multiplexing.md) | Stealth mode — protocol multiplexing on port 443 | Accepted |
|
|
| [018](decisions/018-control-channel-for-pubsub.md) | Control channel for pubsub over SSH | Accepted |
|
|
| [019](decisions/019-proxy-dual-semantics.md) | `--proxy` dual semantics (client vs server) | Accepted |
|
|
|
|
## Open Questions
|
|
|
|
All open questions have been resolved. See [open-questions.md](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 | |