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

1.9 KiB

Raw Blame History

ADR-017: Stealth Mode — Protocol Multiplexing on Port 443

Status

Accepted

Context

When running a wraith server with TLS transport on port 443, the server should be indistinguishable from a regular HTTPS web server to port scanners and deep packet inspection (DPI) systems. This is important for censorship circumvention — if SSH traffic on port 443 is detectable, it can be blocked.

After the TLS handshake completes, the server sees a raw byte stream. SSH protocol identification starts with SSH-2.0-, while HTTP starts with HTTP method verbs (GET, POST, etc.). The server can inspect the first bytes to determine the protocol.

Decision

When --stealth is enabled with TLS transport:

After completing the TLS handshake, peek at the first few bytes of the connection
If the connection starts with SSH-2.0-, proceed with SSH session via server::run_stream()
If the connection starts with anything else (HTTP, random data), respond with HTTP/1.1 404 Not Found\r\nServer: nginx\r\n\r\n and close the connection

This makes the server appear as an nginx web server returning 404 errors to all non-SSH connections. Scanners and DPI systems see a typical HTTPS site with no SSH exposure.

The fake response uses Server: nginx headers to match the most common web server profile.

Consequences

Positive: TLS+wraith servers on port 443 are indistinguishable from ordinary HTTPS sites to automated scanners.
Positive: Simple implementation — just peek at the first bytes and branch.
Positive: Consistent with censorship circumvention best practices.
Negative: Legitimate HTTPS traffic to the same port gets a 404. If the same IP needs to serve real web content, use a reverse proxy (nginx/haproxy) in front that routes by SNI or path.
Negative: The --stealth flag only applies to TLS transport. It has no effect on TCP or iroh transports.

References

server.md

1.9 KiB Raw Blame History