glm-5.1
af7f4d0006
Unified authentication (ADR-023): SSH and WebTransport auth share the same
Ed25519 key material. Token auth uses signed timestamps verified against the
same authorized_keys set. IdentityProvider trait decouples core from identity
storage.
Bidirectional call protocol (ADR-024): Generalizes control channel (ADR-018)
to support hub→spoke and spoke→hub calls. Operation paths use /{spoke}/{service}/{op}
format for three-level routing. EventEnvelope wire format, five call events,
PendingRequestMap for correlation.
Handler/spec separation (ADR-025): Downstream consumers register operations
without modifying core. OperationRegistry maps paths to specs + handlers.
Service discovery via /services/list and /services/schema.
Resolves OQ-17 (transport-aware auth), OQ-21 (spoke routing), OQ-CFG-04 and
OQ-CFG-06 (WebTransport auth and transport-aware auth layer). Adds OQ-18
through OQ-22 for remaining open questions.
status, last_updated
| status | last_updated |
|---|---|
| draft | 2026-06-04 |
Wraith Architecture
Current State
Architecture specification in active development. 22 ADRs accepted. Unified auth and call protocol architecture being specified — see auth.md and call-protocol.md. Configuration architecture under exploration — see research/configuration.md.
Architecture Documents
| Document | Status | Description |
|---|---|---|
| overview.md | reviewed | Package purpose, exports, dependencies |
| transport.md | reviewed | Transport abstraction: TCP, TLS, iroh |
| auth.md | draft | Unified auth: SSH + token, IdentityProvider trait |
| call-protocol.md | draft | Bidirectional call/event protocol, operation registry |
| 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 |
Research Documents
| Document | Status | Description |
|---|---|---|
| configuration.md | draft | Configuration architecture: static/dynamic split, hot reload, forwarding policy |
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 |
| 023 | Unified auth with shared key material + token auth | Accepted |
| 024 | Bidirectional call protocol (EventEnvelope) | Accepted |
| 025 | Handler/spec separation for downstream service registration | Accepted |
Open Questions
Most open questions have been resolved. Open questions remain for configuration, auth, and call protocol — see open-questions.md for details.
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 |