glm-5.1
13b0991fb8
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.
38 lines
2.7 KiB
Markdown
38 lines
2.7 KiB
Markdown
# 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:
|
|
|
|
1. **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.
|
|
2. **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`).
|
|
3. **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`:
|
|
|
|
1. The `channel_open_direct_tcpip` handler detects the special target via string matching
|
|
2. Instead of connecting to a TCP target, it bridges the channel to the local pubsub event bus
|
|
3. `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.
|
|
|
|
## References
|
|
- [napi-and-pubsub.md](../napi-and-pubsub.md)
|
|
- [server.md](../server.md) |