Files

glm-5.1 13b0991fb8 Resolve all architecture open questions, add 13 ADRs, update specs

Resolved all 11 open questions based on project guidance:

Transport:
- OQ-01/OQ-07: ACME/Let's Encrypt with domain + IP paths (ADR-008)
- OQ-02: Default to n0 relay, --iroh-relay override (ADR-009)
- OQ-05: Transport chaining supported natively (ADR-010)

Client:
- OQ-06: Programmatic-first API, no ~/.ssh/config (ADR-011)

Server:
- OQ-04: Ed25519 + OpenSSH cert-authority, no password auth (ADR-012)
- OQ-08: fail2ban-friendly logging + built-in rate limiting (ADR-013)

TUN:
- OQ-03/OQ-09: Deferred entirely, recommend tun2proxy (ADR-014)
- tun-shim.md marked deprecated

NAPI:
- OQ-10: Expose both connect() and serve() (ADR-016)
- OQ-11: Use napi-rs for FFI bridge (ADR-015)

Additional ADRs created during review:
- ADR-006: No logging of tunnel destinations (was phantom reference)
- ADR-017: Stealth mode protocol multiplexing
- ADR-018: Control channel for pubsub over SSH

Fixed: ADR-002 status → Superseded, ADR-007 title typo,
WRAUTH_SERVER typo, ADR-005 stale wraith-tun refs,
undefined ACL feature removed from server.md,
--proxy semantic difference documented.

2026-06-01 17:31:28 +00:00

2.7 KiB

Raw Blame History

ADR-018: Control Channel for PubSub over SSH

Status

Accepted

Context

The NAPI wrapper and pubsub integration need a way to use wraith's SSH channel as a data plane for event routing. When a wraith connect client opens an SSH session to a server, the direct_tcpip channel type is used to reach specific TCP targets (host:port).

For the pubsub use case, the client needs a dedicated bidirectional stream to the server's event bus — not a TCP connection to a random host. There are several approaches:

Special destination: Use direct_tcpip with a reserved destination (e.g., wraith-control:0) that the server recognizes and routes internally instead of connecting to a TCP target.
Port forwarding: The server runs a pubsub hub on a specific port (e.g., 9736) and the client uses normal port forwarding (-L 9736:hub:9736).
Custom channel type: Define a new SSH channel type beyond direct_tcpip and forwarded_tcpip.

Decision

Use approach 1: a reserved direct_tcpip destination string. When the server receives a channel_open_direct_tcpip request for wraith-control:0:

The channel_open_direct_tcpip handler detects the special target via string matching
Instead of connecting to a TCP target, it bridges the channel to the local pubsub event bus
EventEnvelope JSON flows bidirectionally over the SSH channel

The destination string wraith-control is reserved. Regular TCP targets are hostnames or IP addresses, so there is no collision risk.

Approach 2 (port forwarding to a specific port) is still supported as an alternative — the client can use --forward 9736:localhost:9736 if the server runs a pubsub hub on that port. But the control channel approach is simpler and doesn't require a separate listening port.

Approach 3 (custom channel type) was rejected because russh's direct_tcpip handler is well-understood and adding custom channel types requires modifying russh.

Consequences

Positive: Simple implementation — just string matching in the server's channel_open_direct_tcpip handler.
Positive: No separate port or service needs to run on the server. The control channel is built into wraith.
Positive: Compatible with the NAPI wrapper's single-duplex-stream model.
Positive: Port forwarding to a specific port is still available as an alternative.
Negative: The string wraith-control is a magic constant. It should be defined as a constant in the crate.
Negative: Regular TCP destinations accidentally matching wraith-control would be misrouted. Mitigated by reserving the entire wraith- prefix namespace.

2.7 KiB Raw Blame History