Files

glm-5.1 af7f4d0006 docs: add auth, call protocol architecture specs and ADRs 023-025

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.

2026-06-05 08:19:41 +00:00

4.5 KiB

Raw Blame History

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

4.5 KiB Raw Blame History