---
status: draft
last_updated: 2026-06-29
---

# alknet-ssh — Phase 0 Research Findings

This document captures Phase 0 (Exploration) findings for the `alknet-ssh`
crate. The objective of Phase 0 per `docs/sdd_process.md` is: *"Capture vision
and guiding principles; research options; validate approaches; converge on a
recommended approach."* It is the input to Phase 1 (Architecture), where the
Architect will produce `docs/architecture/crates/ssh/*.md` specs, ADRs, and
open questions.

This document was initially drafted 2026-06-25 and **revised 2026-06-29** to
reflect two developments that changed the framing: (1) the WebTransport
architecture landed as ADRs 038/040/043, grounding the SSH-over-WebTransport
path that was previously speculative; (2) the recognition that SSH's channel
multiplexer is the natural decomposition point, dissolving the "massive v1
scope" problem into a stack of independently functional layers.

## Vision Recap

`alknet-ssh` is the SSH protocol handler for the ALPN-as-service architecture
(ADR-001). It registers the `alknet/ssh` ALPN on the shared `AlknetEndpoint`
and implements the `ProtocolHandler` trait (ADR-002, ADR-007).

The guiding insight, carried over from the reference implementation at
`/workspace/@alkdev/alknet-main/`, is:

> **SSH does not care where its underlying byte stream comes from.**

The reference implementation built on this — it ran the russh SSH-2 state
machine over a `Transport`-produced duplex stream (`AsyncRead + AsyncWrite +
Unpin + Send`) rather than over its own TCP sockets. The greenfield rebuild
keeps the insight and drops the messy transport-abstraction layer that grew
around it: in the new model the `AlknetEndpoint` hands the handler a
`Connection` (quinn/iroh QUIC), and the handler is responsible for
opening/accepting the bidirectional QUIC stream that carries the SSH-2
protocol. The same handler can equally be reached via a WebTransport stream
proxied through the `h3` ALPN-stream-proxy (ADR-040) — the handler sees a
`Connection` either way, and SSH doesn't care.

The reference implementation reportedly has ~3.5k clones in 14 days on the
GitHub push mirror (30-60 unique clones/day, a mix of bots and humans/LLMs
inspecting it). There is real-world demand for the "SSH-over-arbitrary-stream"
capability. The greenfield rewrite is a total rewrite; the vault was initially
copied and also since rewritten.

## Sources Investigated

| Source | Path | Note |
|--------|------|------|
| Existing arch docs (core) | `docs/architecture/crates/core/*` | ProtocolHandler, Connection, BiStream, AuthContext, IdentityProvider, Endpoint |
| Existing arch docs (http) | `docs/architecture/crates/http/*` | WebTransport substrate, ALPN-stream-proxy — **new since initial research** |
| Existing ADRs 001–043 | `docs/architecture/decisions/*` | ADR-002/007/010/004/011 (core); **ADR-038/040/043 (WebTransport, new)** |
| russh reference deep-dives | `docs/research/references/ssh/russh/01-06` | Overview, keys, protocol, crypto, internals, usage |
| russh-sftp reference deep-dives | `docs/research/references/ssh/russh-sftp/01-07` | SFTP protocol, client/server API, data flow |
| russh source (authoritative) | `/workspace/russh/` | `Cargo.toml` version `0.60.2`, edition 2024, MSRV 1.85. The cargo registry cache only contains `russh-0.49.2`; **use `/workspace/russh/` as canonical.** |
| russh-sftp source | `/workspace/russh-sftp/` | SFTP subsystem implementation, WASM-targeted protocol parsing |
| alknet Cargo.lock | `Cargo.lock` | Does not yet contain a russh entry |
| Reference implementation | `/workspace/@alkdev/alknet-main/` | `crates/alknet-core/src/{interface/ssh.rs, server/*, client/*, socks5/*}` |
| Concrete consumer | `/workspace/@alkdev/dispatch/` | axum + `russh = "0.60"` SSH **client** for "reverse git runner" over Docker/vast.ai. Textbook consumer of the SSH client + forwarding primitives. |

> **Note on the russh clone**: `/workspace/russh` declares `version = "0.60.2"`
> with `edition = "2024"` and MSRV 1.85 — matching the research references.
> The cargo-cache mismatch (0.49.2 only) matters because 0.49.2 → 0.60.2 spans
> major API changes (`server::run_stream` generic signature, `Auth` enum
> shape, `server::Handler` method set all differ). When alknet-ssh's
> `Cargo.toml` pins `russh = "0.60"`, Cargo will fetch the matching 0.60.x.

## The Channel Decomposition (Core Insight)

SSH's channel multiplexer is the natural decomposition point. The features
that make up alknet-ssh are layers that stack on top of it — each functional
on its own.

### How SSH channels work

SSH multiplexes multiple logical channels over a single encrypted transport
stream (RFC 4254). `ChannelId(u32)` identifies channels; all channel traffic
(`CHANNEL_OPEN`/`DATA`/`EOF`/`CLOSE`/...) is interleaved on the single
underlying SSH transport. This is **independent of QUIC's own stream
multiplexing** — one QUIC bistream (or one WebTransport stream, or one TCP
connection) ↔ one SSH connection ↔ many SSH channels riding inside it.

The crucial property: **channel types are negotiated.** If one side requests a
channel type the other doesn't implement, the request is rejected with an
error. This means a partial channel implementation is not "broken" — it
correctly negotiates the types it supports and rejects the ones it doesn't.
This is the opposite of a half-built protocol; it's a layered protocol where
each layer stands on its own.

### The layer stack

```
Layer 7: SFTP subsystem          (channel type: "subsystem", name: "sftp")
Layer 6: SOCKS5 server            (consumer of Layer 5 — opens direct-tcpip channels)
Layer 5: Port forwarding          (channel types: "direct-tcpip", "forwarded-tcpip")
Layer 4: Session / exec           (channel type: "session"; exec/shell/pty requests)
Layer 3: Channel multiplexer      (russh internal — CHANNEL_OPEN/DATA/CLOSE)
Layer 2: SSH connection           (key exchange, auth, encrypted session)
Layer 1: Stream transport         (QUIC bistream / WebTransport stream / TCP)
```

Each layer is functional when built:

- **Layers 1-4** (stream + SSH connection + channels + session/exec): a working
  SSH server that authenticates and runs commands. This is immediately useful
  — it's the dispatch "reverse git runner" primitive (`exec` on a session
  channel) and the foundation everything else builds on.
- **+ Layer 5** (port forwarding): add `direct-tcpip` (local→remote) and
  `forwarded-tcpip`/`tcpip_forward` (remote→local) channel types. Now the SSH
  connection can forward ports in both directions. Each forwarded connection is
  a channel, not a separate transport stream. This unlocks the VPN-like
  topology (WireGuard + Postgres + Redis over SSH forwarding) that the reference
  implementation was built for.
- **+ Layer 6** (SOCKS5): a SOCKS5 server that accepts local connections and
  opens `direct-tcpip` channels to forward them. It's a *consumer* of the
  forwarding API, not a new channel type — SOCKS5 is a protocol spoken on the
  *client side* (the entity that wants to proxy), and the forwarding channel
  is what carries the bytes. This is where the "maybe a separate crate"
  question lives: SOCKS5 is a consumer of Layer 5's API, so if that API is
  clean, SOCKS5 can be in alknet-ssh or extracted — a two-way door.
- **+ Layer 7** (SFTP): a subsystem channel ("subsystem", name "sftp") that
  runs the SFTP protocol. `russh-sftp::server::run` takes the channel's stream
  (`channel.into_stream()` → `AsyncRead + AsyncWrite + Unpin + Send`) and a
  handler. It's another channel-layer consumer, stacking on Layer 3/4.

**No layer ships broken.** You build 1-4, ship a working SSH+exec appliance.
You add 5, ship a working SSH+forwarding appliance. You add 6, ship a working
  SSH+SOCKS5 proxy. You add 7, ship SFTP. Each increment is a complete,
functional SSH server for the channel types it supports — and a clean
rejection for the ones it doesn't. This is decomposition, not phasing: there
is no "phase 1 ships something that can't be used."

### What this means for the crate boundary

The decomposition clarifies which pieces are "foundational to SSH" vs
"consumers of SSH":

- **Foundational (in alknet-ssh)**: Layers 1-5. The stream transport, SSH
  connection, channel multiplexer, session/exec, and port forwarding are the
  SSH protocol itself. Forwarding (`direct-tcpip`/`forwarded-tcpip`) is
  defined by RFC 4254 §7; it's not an add-on, it's part of the protocol.
- **Consumer (in alknet-ssh or extractable)**: Layers 6-7. SOCKS5 and SFTP are
  *consumers* of the channel API. SOCKS5 is a proxy protocol that opens
  forwarding channels; SFTP is a file protocol that runs over a subsystem
  channel. Both could live in alknet-ssh or in separate crates — the decision
  is a two-way door because they consume a clean interface (the channel/stream
  API), so extraction is cheap if a second consumer appears.

The "maybe a separate socks proxy crate, and maybe not" question is answered
by this framing: **start with SOCKS5 in alknet-ssh** (the VPN-like use case
needs it there), and extract only if a second consumer of the forwarding API
appears — the stream-agnostic philosophy makes extraction cheap. SFTP is the
same: start with it as a subsystem the SSH handler can serve, extract only if
warranted. Neither is deferred; both are built as stacking layers.

## What's Changed Since Initial Research

Three things changed between the initial 2026-06-25 research and this
revision:

### 1. WebTransport is now architecturally grounded

ADRs 038 (HTTP/3 + WebTransport as first-class), 040 (WebTransport
ALPN-stream-proxy), and 043 (WebTransport as a bidirectional ALPN transport
substrate) now exist. The path "a browser opens a WebTransport session to
`/alknet/ssh`, the `h3` handler proxies the stream to `SshAdapter::handle()`,
the browser runs a WASM SSH client over the stream" is no longer speculative
— the substrate is specified. ADR-040 Assumption 2 states the constraint
explicitly: *the target ALPN handler accepts a proxied `Connection`; if a
handler assumes its `Connection` came from a specific QUIC source, it breaks
the proxy.* alknet-ssh must not assume its stream came from `accept_bi()` on a
native QUIC connection — it could be a WebTransport stream wrapped as a
`Connection`.

This is a **constraint on alknet-ssh's design**, not a feature to add later:
the handler's stream-acquisition path must be source-agnostic from the start.
The `tokio::io::join(recv, send)` adapter works identically whether the halves
came from a QUIC bistream or a WebTransport stream — both produce
`AsyncRead + AsyncWrite + Unpin + Send`. The constraint is satisfied by
construction if alknet-ssh uses the `BiStream`/`Connection` abstraction rather
than reaching for concrete quinn types.

### 2. The SSH client can run in WASM

The initial research (DP-7) framed tokio as a hard transitive dependency and
treated WASM as a one-way-door closure on the server side (OQ-09). That's
correct for the *server* dispatch path (the accept loop uses `tokio::spawn`,
the endpoint is quinn-bound), but **incorrect for the client side.**
Verifying against `/workspace/russh/russh-util/src/runtime.rs`:

```rust
#[cfg(target_arch = "wasm32")]
macro_rules! spawn_impl { ($fn:expr) => { wasm_bindgen_futures::spawn_local($fn) }; }
#[cfg(not(target_arch = "wasm32"))]
macro_rules! spawn_impl { ($fn:expr) => { tokio::spawn($fn) }; }
```

russh's `spawn` swaps to `wasm_bindgen_futures::spawn_local` on `wasm32`, and
`russh-util/src/time.rs` swaps to a chrono-based `Instant` on WASM. The client
`connect_stream<H, R>(config, stream, handler)` path takes a generic
`R: AsyncRead + AsyncWrite + Unpin + Send + 'static` — if the stream is
provided externally (a WebTransport `BiStream` implemented in WASM), the
client state machine runs in WASM. The `russh-sftp` protocol parsing already
targets WASM, confirming the pattern.

**The browser case is real:** a browser connects via WebTransport to
`/alknet/ssh`, the hub's `h3` handler proxies the stream to `SshAdapter`, and
the browser runs a WASM build of the alknet-ssh **client** (russh client +
`connect_stream` over a WebTransport `BiStream`) to speak SSH over the proxied
stream. The browser doesn't open native ports — it sends packets over the SSH
protocol, which forwards them as channels. The server side stays tokio-native
(the accept loop, the endpoint); the client side is the WASM target.

This reframes DP-7: tokio is a hard dependency for the **server** path, but
the **client** path is WASM-compatible because russh already abstracted its
runtime. alknet-ssh's client API must not reach for tokio-specific types
(`TcpStream`, `tokio::net`) in its public surface — the client should take a
stream, like russh's `connect_stream` does, so a WASM build can feed it a
WebTransport `BiStream`.

### 3. The http crate intersection is now visible

The alknet-http specs are drafted (ADR-036 through ADR-043). The
ALPN-stream-proxy (ADR-040) means `alknet-http`'s `h3` handler holds a
`HandlerRegistry` reference and routes WebTransport streams to ALPN handlers by
CONNECT path. alknet-ssh is one of those handlers. This is a structural
relationship: alknet-ssh doesn't depend on alknet-http, but alknet-http's
WebTransport path depends on alknet-ssh (and every other ALPN handler) being
source-agnostic about its `Connection`. The specs must be consistent on this
point — ADR-040 Assumption 2 is the contract both crates must honor.

## Straightforward Parts

These are settled by existing ADRs, the reference implementation, and the
channel decomposition. Phase 1 should document them as spec rather than
re-litigate them.

### 1. SSH is a `ProtocolHandler` on `alknet/ssh`

Confirmed by overview.md's ALPN Registry and core-types.md. `SshAdapter`
implements `ProtocolHandler::handle(&self, connection: Connection, auth:
&AuthContext) -> Result<(), HandlerError>` with `alpn() = b"alknet/ssh"`. The
handler owns the entire `Connection` lifecycle (ADR-006: one ALPN, one
connection, one handler) and may open/accept multiple QUIC streams because it
multiplexes SSH channels inside a single bistream.

### 2. SSH runs over a single bidirectional stream — source-agnostic

The reference implementation's `transport/iroh_transport.rs` proves the
approach: open a QUIC bistream, **join the two halves into a single duplex
type with `tokio::io::join(recv, send)`** and feed that to russh. This is a
one-liner:

```rust
// from alknet-main/.../iroh_transport.rs:94
let conn = self.endpoint.connect(self.node_id, ALPN).await?;
let (send, recv) = conn.open_bi().await?;
Ok(io::join(recv, send))   // produces: AsyncRead + AsyncWrite + Unpin + Send
```

`tokio::io::join` already produces the `AsyncRead + AsyncWrite` combo russh
requires (russh internally re-splits via `tokio::io::split`). **No custom
adapter struct is required** — `Connection::accept_bi()` / `open_bi()` plus
`tokio::io::join` is sufficient for the QUIC path, and the same `join` pattern
works for a WebTransport stream wrapped as a `Connection` (ADR-040).

This is now a **constraint**, not just a finding: per ADR-040 Assumption 2,
the handler must accept a `Connection` that came from a WebTransport stream,
not assume it came from a native QUIC `accept_bi()`. The `BiStream`/`Connection`
abstraction (ADR-007) is what makes this work — alknet-ssh must use it, not
reach for concrete quinn types.

### 3. russh accepts a generic stream on both client and server side

Verified from `/workspace/russh/russh/src/`:

- `server::run_stream<H, R>(config: Arc<Config>, stream: R, handler: H)` where
  `R: AsyncRead + AsyncWrite + Unpin + Send + 'static` — `server/mod.rs:997`.
- `client::connect_stream<H, R>(config: Arc<Config>, stream: R, handler: H)`
  with the same bound — `client/mod.rs:982`.

Neither path assumes TCP — TCP-specific code (`set_nodelay`, `TcpListener`) is
confined to `run_on_socket` / `connect` / `run_on_address`. The generic stream
path is clean of TCP assumptions. russh writes its own SSH identification banner
first, then reads the peer's — no caller-side banner pre-work is needed.

### 4. SSH channels multiplex *inside* the stream — this is the decomposition axis

`ChannelId(u32)` identifies channels; all channel traffic is interleaved on
the single underlying SSH transport stream that russh owns. Port forwarding
(`direct-tcpip`, `forwarded-tcpip`) is ordinary channel traffic — each
forwarded TCP connection is a channel, not a separate stream. SFTP is a
subsystem channel. SOCKS5 is a consumer of forwarding channels.

This is the cleanest mapping and the right default: alknet-ssh does not try to
map SSH channels onto QUIC streams (which would require bypassing russh's own
multiplexer). It hands russh one bistream and lets russh multiplex inside it.
**The channel multiplexer is the decomposition point** — each feature
(forwarding, SOCKS5, SFTP) is a channel type or a consumer of channel types,
stacking on Layer 3. See "The Channel Decomposition" above.

### 5. Auth routes through the shared `IdentityProvider`

ADR-004 establishes the hybrid auth model: the endpoint resolves what it can
(TLS client cert → fingerprint), the handler resolves what it must (SSH key
fingerprint). `auth.md` shows the `SshAdapter` pattern exactly — constructor-
inject `Arc<dyn IdentityProvider>`, call `resolve_from_fingerprint()` inside
`handle()` when `auth.identity` is `None`, store the resolved `Identity` on the
`Connection` via `set_identity()` for observability (OQ-11). The
`ConfigIdentityProvider` already resolves SSH key fingerprints against
`DynamicConfig::auth::authorized_keys_fingerprints`. No new auth machinery
is needed for SSH.

### 6. Outbound credentials (if any) come from `Capabilities`

ADR-014 / ADR-022 establish that handlers get outbound credentials through the
registration bundle's `capabilities` field, populated by the assembly layer
from the vault. SSH itself typically needs no outbound credentials (the SSH
host key is a network-identity concern, the SSH *client* key for auth comes from
the peer), but if alknet-ssh ever needs an outbound secret (e.g., to dial an
upstream SOCKS proxy), it comes from `Capabilities`, not from env vars or
vault-on-wire.

### 7. TCP SSH is a handler concern, not an endpoint concern

ADR-010 is explicit: "TCP is NOT an endpoint concern... the SSH handler can
listen on a TCP socket independently." This means alknet-ssh may optionally bind
a plain TCP listener (port 22-style) and accept raw SSH connections *outside*
the ALPN endpoint. The `alknet/ssh` ALPN path and the bare-TCP path can coexist;
they share the same `russh::server::Config` and the same `server::Handler`
implementation, differing only in how the stream is obtained. This is a
two-way-door additive capability — the TCP listener can be added without
touching the ALPN path.

### 8. The WebTransport path is grounded — SSH-over-WebTransport is a constraint

Per ADR-040/043, the `h3` handler proxies WebTransport streams to ALPN
handlers. A browser opening a WebTransport session to `/alknet/ssh` gets its
stream handed to `SshAdapter::handle()` as a `Connection`. The browser runs a
WASM SSH client (the alknet-ssh client, built for `wasm32`) over the stream.
The handler must be source-agnostic about its `Connection` — this is a
constraint on the design, satisfied by using the `BiStream`/`Connection`
abstraction rather than concrete quinn types. **This is no longer an open
question; it's a requirement.**

## Less Straightforward Parts (Decision Points)

These are the points where Phase 0 surfaced genuine choices that affect the
architecture. Each is tagged with a door type per ADR-009. The Architect
should turn the *accepted* recommendations into ADRs, and the genuinely
unresolved ones into open questions. **Door type classifies reversal cost, not
urgency — a two-way door is a decision made now that can be reverted later,
not a decision to defer** (ADR-009 §"What this framework is NOT").

### DP-1: Host key sourcing — vault-derived vs config-loaded vs both
*(Recommended: one-way door — needs an ADR)*

russh's `server::Config.keys: Vec<PrivateKey>` holds the SSH host keys the
server presents during key exchange. The host key is the SSH layer's analogue
of the TLS layer's network identity — it is what the *SSH client* verifies
against `known_hosts`. Three sourcing paths exist:

- **(a) Vault-derived**: derive an Ed25519 key from the alknet-vault seed (HD
  path) and use it as the SSH host key. Aligns with the project's "everything
  keys-from-seed" philosophy (ADR-020, ADR-026) and means the SSH host key is
  deterministic from the mnemonic — a node restored from mnemonic gets the same
  SSH host key fingerprint.
- **(b) Config-loaded**: operator provides SSH host key file path(s) in
  `StaticConfig`/`DynamicConfig`. Matches how OpenSSH works
  (`/etc/ssh/ssh_host_ed25519_key`). Simplest, decoupled from the vault.
- **(c) Both**: vault-derived by default, config override for operators who
  bring their own keys. Mirrors the TLS identity model (ADR-027's
  `TlsIdentity::RawKey` default + `X509`/`Acme` for domain-hosted).

**Recommendation**: **(c) both**, with vault-derived as the default. This
matches the symmetry with `TlsIdentity` in endpoint.md and respects the
"fingerprint-based, keys-from-seed" identity model. The vault is local-only by
construction (ADR-025) and assembly-layer-only access (ADR-019), so the SSH host
key is derived at startup and injected into `SshAdapter::Config` the same way
TLS RawKey identity is. Operators who want stable host keys independent of the
mnemonic can supply a key file. Phase 1 should write an ADR for this and a
corresponding OQ if the exact config-field shape is unresolved.

### DP-2: Per-connection host key selection
*(Recommended: one-way door — needs an ADR, ties to DP-1)*

When supporting multiple host keys (e.g., an Ed25519 default + an RSA key for
legacy clients), russh's `server::Config.keys` is a `Vec` and russh negotiates
which to use based on the client's offered algorithms. The selection is
deterministic per-russh-version but not configurable per-connection. Question:
do we need per-peer host key selection (e.g., present different host keys to
different peer networks)? **No** — one host key set per node, advertised
uniformly. Per-connection selection is not needed; if a use case arises, it's
an additive two-way-door. Phase 1 records the simple model.

### DP-3: Crypto backend — `aws-lc-rs` (default) vs `ring`
*(Recommended: two-way door — decided: `aws-lc-rs`, can flip later)*

russh 0.60.2 requires exactly one of `aws-lc-rs` (default) or `ring` enabled;
enabling both silently picks `aws-lc-rs`. Both produce AES-GCM / ChaCha20-Poly1305.

- `aws-lc-rs` is the russh default, has broader algorithm coverage, but brings
  NIST build machinery (a heavier build, requires a C compiler + cmake).
- `ring` is lighter-weight, smaller binary, simpler build.
- **Cross-crate consequence**: alknet-core already depends on `rustls-acme =
  "0.12"` with `features = ["aws-lc-rs"]`, so `aws-lc-rs` is already in the
  workspace's build. Choosing `ring` for russh while alknet-core uses
  `aws-lc-rs` would put *both* crypto backends in the final binary — wasteful
  but not incorrect.

**Recommendation**: **`aws-lc-rs`** (aligns with the rest of the workspace and
avoids a duplicate crypto backend). This is a decision, not a deferral — it's
a two-way door that can be flipped by changing `default-features = false` on
russh if binary-size pressure arises later. Phase 1 notes this; likely not a
full ADR (it's a default, not a structural decision) but a documented design
choice in the ssh spec.

### DP-4: Client + forwarding + SOCKS5 + SFTP scope — reframed as layer order
*(Recommended: one-way door on "all in alknet-ssh"; two-way door on extraction)*

The channel decomposition answers the scope question. The question is not "do we
ship it all at once" but "what's the build order, and are all the layers in
alknet-ssh?"

**Server side** (the `ProtocolHandler` for `alknet/ssh`): owns Layers 1-5
(stream transport, SSH connection, channels, session/exec, port forwarding).
These are the SSH protocol itself. Forwarding is defined by RFC 4254 §7 — it's
not an add-on. The server also serves SFTP (Layer 7) as a subsystem channel
when configured.

**Client side** (outbound SSH dialing): owns the same layers, as a client. The
client opens session channels for `exec` (the dispatch "reverse git runner"
pattern), opens `direct-tcpip` channels for local→remote forwarding, and
requests `tcpip_forward` for remote→local forwarding. **The client is the WASM
target** — russh's `connect_stream` runs in WASM when fed a WebTransport
`BiStream`. This is why the client lives in alknet-ssh, not in each consumer:
dispatch and the VPN-like topology both consume the same client + forwarding
primitives, and the browser case needs the client in WASM.

**SOCKS5** (Layer 6): a consumer of the forwarding API. The SOCKS5 server
accepts local connections and opens `direct-tcpip` channels to forward them.
It lives in alknet-ssh because the VPN-like use case needs it there; if a
second consumer of the forwarding API appears, the SOCKS5 codec can extract to
a tiny `alknet-socks5` crate (consuming a byte stream) — a two-way door, cheap
because the interface (the forwarding channel API) is clean.

**SFTP** (Layer 7): a subsystem channel. `russh-sftp::server::run` takes the
channel's stream and a handler. It's in alknet-ssh as a subsystem the server
can serve; the client side uses `russh-sftp::client::SftpSession` over a
channel stream. Same extraction logic as SOCKS5 — start in alknet-ssh, extract
only if warranted.

**Recommendation**: alknet-ssh owns **all layers** (server + client +
forwarding + SOCKS5 + SFTP). The build order is 1-4 first (functional SSH+exec),
then 5 (forwarding), then 6 (SOCKS5) and 7 (SFTP) — each layer functional when
built, none shipped broken. Phase 1 writes an ADR confirming this scope and the
layered build order. The extraction question (SOCKS5/SFTP to separate crates)
is a two-way door, decided as "in alknet-ssh, extract if a second consumer
appears" — a decision, not a deferral.

### DP-5: Channel-policy surface — which SSH services does alknet-ssh expose?
*(Recommended: one-way door — needs an ADR; the default-deny baseline is
non-negotiable)*

russh's `server::Handler` defaults every channel-request method to reject/no-op
(or, for `auth_publickey_offered`, accept the offer through to signature
verification). alknet-ssh must decide its default channel policy:

- **session channels**: the dispatch use case uses `channel_open_session().exec()`
  heavily — the "reverse git runner" pattern (run a command on the remote
  instance, capture stdout/stderr/exit). For the **server side** of
  `alknet/ssh`, the question is whether alknet-ssh *runs a real shell* on its own
  node. Given the VPN-like / forwarding use case is primary and the "shell
  server" use case is secondary, the default is **exec-only**:
  `shell_request` and `pty_request` default-reject; `exec_request` permitted
  (gated by ACL). This keeps alknet-ssh a focused forwarding/exec appliance
  rather than a general-purpose interactive login server. Interactive shell is
  an explicit opt-in (two-way door).
- **port forwarding in both directions** (`direct-tcpip` in, `tcpip_forward` /
  `forwarded-tcpip` out): in scope (Layer 5). The *policy* (which destinations
  are allowed, whether to restrict by ACL/scope) needs specifying.
- **SFTP subsystem**: in scope (Layer 7), gated by ACL.
- **PTY/X11/agent forwarding**: default-reject for security; explicit opt-in.
  (Consistent with the exec-only session stance.)

**Default-deny baseline**: russh's `server::Handler` already defaults every
channel/auth/forwarding callback to reject or no-op — so alknet-ssh gets
default-deny for free by overriding only the methods it wants to enable. This
is the explicit baseline: every forwarding destination, every exec command,
every channel type must be *explicitly permitted* by config + ACL, never
implicitly allowed. This applies to **both** the ALPN/QUIC path and the
bare-TCP path (DP-10) — a TCP-listener client gets exactly the same policy
treatment; only the transport differs.

**ACL gating**: forwarding destinations and exec commands are gated by scopes on
the resolved `Identity`. The exact scope vocabulary (e.g., `ssh:forward:*`,
`ssh:forward:127.0.0.1:5432`, `ssh:exec:git-upload-pack`) is a design choice the
Architect makes — likely a small, capability-shaped scope set with wildcards,
consistent with `Identity.scopes` / `Identity.resources` (auth.md). The
"resources" field on `Identity` (populated only by composition per
`CompositionAuthority::as_identity`, ADR-022) is *not* available to
fingerprint/token-resolved external identities, so per-destination ACLs for
inbound SSH must live in `scopes`, not `resources`.

**Recommendation**: Phase 1 writes an ADR defining the channel-policy surface:
exec (gated) + bidirectional port forwarding (gated) + SFTP (gated), with
shell/PTY/X11/agent forwarding default-rejected. Default-deny baseline
inherited from russh. Forwarding destinations + exec commands gated by ACL
scopes. The exact scope vocabulary is an OQ for Phase 1 (it interacts with how
operators express "allow forwarding to 127.0.0.1:5432" in `DynamicConfig`).

### DP-6: Auth method coverage — publickey-only vs password/kbdint too
*(Recommended: two-way door — decided: publickey-only, extend later if needed)*

russh supports `none`, `password`, `publickey`, `keyboard-interactive`, and
OpenSSH certificate auth server-side. alknet's identity model (auth.md) is
*fingerprint-based* — SSH key fingerprint → `IdentityProvider` → `Identity`.
This maps naturally onto **publickey** (the fingerprint is the SHA-256 of the
presented public key) and **OpenSSH certificate** auth (cert fingerprint).
Password / keyboard-interactive don't fit the fingerprint model as cleanly
(there's no `resolve_from_password` on `IdentityProvider`).

**Recommendation**: **publickey-only** (and certificate auth, which is a
superset of publickey from the fingerprint POV). Password /
keyboard-interactive are a two-way door — can be added later if a use case
arises. Phase 1 notes this as a documented design choice in the ssh spec,
likely not a full ADR (it's a default, not a structural decision).

### DP-7: Runtime — tokio (server) vs WASM-compatible (client)
*(Recommended: acknowledged constraint — server needs tokio, client is
WASM-compatible)*

russh 0.60.2 uses `russh-util::runtime::spawn`, which swaps to
`wasm_bindgen_futures::spawn_local` on `wasm32` and `tokio::spawn` otherwise.
`russh-util::time::Instant` swaps to a chrono-based implementation on WASM.
This means:

- **Server side** (the `ProtocolHandler` accept path): requires tokio. The
  endpoint's accept loop uses `tokio::spawn`, the `Connection` is quinn-bound,
  and the dispatch path is a one-way door away from WASM (OQ-09). alknet-ssh's
  server inherits this — it runs inside the tokio runtime that alknet-core's
  endpoint already provides (`tokio = { version = "1", features = ["full"] }`).
- **Client side** (outbound dialing / the WASM target): WASM-compatible. The
  client `connect_stream` path takes a generic stream; if the stream is a
  WebTransport `BiStream` implemented in WASM, the client state machine runs in
  WASM. **alknet-ssh's client API must not reach for tokio-specific types**
  (`TcpStream`, `tokio::net`) in its public surface — it should take a stream,
  like russh's `connect_stream` does, so a WASM build can feed it a
  WebTransport `BiStream`. The browser runs the alknet-ssh client in WASM to
  speak SSH over the proxied WebTransport stream (ADR-040/043).

**Recommendation**: Phase 1 records the split: server = tokio (hard
constraint, consistent with workspace), client = WASM-compatible (russh
already abstracted its runtime; alknet-ssh's client API preserves this by
taking a stream, not a socket). This is a known constraint, not a decision to
fight. OQ-09 (WASM boundaries) documents the server-side closure; the
client-side WASM compatibility is a new finding that keeps the browser door
open.

### DP-8: The `ssh-key` crate is forked
*(Recommended: acknowledged constraint — use the russh re-export)*

russh 0.60.2 depends on `internal-russh-forked-ssh-key = "0.6.18"` (a renamed
fork), **not** upstream `ssh-key`. alknet-ssh must not add upstream `ssh-key`
directly — that would put two `ssh-key` versions in the tree and the
`PublicKey`/`PrivateKey` types wouldn't unify. The fork is re-exported through
`russh::keys::ssh_key`, so alknet-ssh should always reach key types via
`russh::keys::*` (or `russh::keys::ssh_key::*`) to stay on the same fork. Phase
1 notes this as an implementation constraint; it's a real footgun if missed.

### DP-9: End-to-end over a non-TCP stream is untested upstream
*(Recommended: de-risk early with a POC test)*

russh's own test suite only exercises the client↔server round trip over real
TCP loopback. There is **no** test connecting `connect_stream` ↔ `run_stream`
over `tokio::io::duplex()` or any other in-memory pipe. The `SshRead::read_ssh_id`
unit tests feed `&[u8]` directly, proving the banner parser works on
non-socket streams — but a full client↔server round trip over a non-TCP stream
is unverified upstream.

The reference implementation uses this path in production (`transport/iroh_transport.rs`
using `tokio::io::join`), which is strong empirical evidence it works. But the
greenfield rewrite should **close this gap early** with an integration test
using `tokio::io::duplex()` connecting `connect_stream` ↔ `run_stream` *before*
going near real QUIC. **The WebTransport path adds a second POC target**: a
WebTransport stream wrapped as a `BiStream`/`Connection` fed to `run_stream`,
validating the ADR-040 Assumption 2 contract (the handler accepts a proxied
`Connection`).

**Recommendation**: per `sdd_process.md` Phase 0, this is a candidate for a
POC Specialist task (`.worktrees/research/ssh-stream-poc/`). Two POC scenarios:
(1) `duplex()`-based round trip, (2) WebTransport-stream-as-`Connection` →
`run_stream`. Phase 1's architecture docs reference the POC outcomes. If the
POC surfaces issues (half-open stream handling, `poll_shutdown` semantics,
maximum packet size), they feed back into the spec as constraints.

### DP-10: Bare-TCP SSH listener — first-class path for git-over-SSH
*(Recommended: one-way door on the config shape, two-way door on the listener
itself)*

ADR-010 establishes that bare-TCP SSH is a handler concern — the SSH handler
can listen on a TCP socket independently of the `alknet/ssh` ALPN path.
Git-over-SSH (`ssh git@host ...`) runs on TCP port 22, not over QUIC — git
clients (`git`, libgit2, `gix`) dial a TCP socket and expect the SSH-2 protocol
directly. To make alknet-ssh a viable git-over-SSH target, the bare-TCP listener
must be a first-class path.

The two paths (ALPN/QUIC vs bare-TCP) share the same `russh::server::Config` and
the same `server::Handler` implementation; they differ only in how the duplex
stream is obtained:

- **ALPN path**: `handle()` receives the QUIC `Connection`, calls
  `accept_bi()`, `tokio::io::join`s the halves, hands to `run_stream`.
- **TCP path**: a `tokio::net::TcpListener` accept loop hands each accepted
  `TcpStream` directly to `run_stream` (or `run_on_socket`, keeping config/
  handler identical across both paths).
- **WebTransport path** (new): `handle()` receives a `Connection` wrapped from
  a WebTransport stream (ADR-040); same `run_stream` call, same config/handler.

All three paths share the same `server::Config` + `Handler` + ACL policy —
only the stream source differs. The TCP listener is **off by default** (must
be explicitly configured to bind), consistent with the default-deny posture.

**Recommendation**: Phase 1 records the three-path model in the ssh spec —
ALPN/QUIC primary, bare-TCP as a co-equal first-class path (off by default),
WebTransport as the browser path (via ADR-040). **Reserve the TCP-listener
config fields** (one-way door on the config schema — retrofitting is messier
than reserving the shape up front). The listener implementation is a two-way
door; the config shape is locked.

## Recommended Approach: Layered Build Order

Based on the channel decomposition and the decision points above, the
recommended approach to take into Phase 1:

### Crate

`alknet-ssh`, depends on `alknet-core` and `russh = "0.60"` (default features,
i.e. `aws-lc-rs`). Implements `ProtocolHandler` for `b"alknet/ssh"`. **Owns
both the SSH server and the SSH client** — the server is the `ProtocolHandler`;
the client is the shared primitive dispatch, the VPN-like topology, and the
browser-WASM case all consume. Owns all channel layers (1-7): stream
transport, SSH connection, channel multiplexer, session/exec, port
forwarding, SOCKS5, SFTP.

### Build order (each layer functional when built)

**Layer 1-4: SSH connection + channels + session/exec**
- Stream wiring: `handle()` accepts the `Connection`, calls `accept_bi()` (or
  receives a WebTransport-proxied stream), `tokio::io::join`s the halves, hands
  to `russh::server::run_stream`. Source-agnostic (ADR-040 constraint).
- Auth: constructor-injected `Arc<dyn IdentityProvider>`. Inside `handle()`, if
  `auth.identity` is `None`, russh's `server::Handler::auth_publickey` resolves
  the offered key's fingerprint through the provider; on success, store the
  resolved `Identity` on the `Connection` via `set_identity()` (OQ-11).
  Publickey-only (plus OpenSSH cert).
- Host keys (DP-1): vault-derived Ed25519 by default, optional config override.
- Channel policy: exec (gated) only; shell/PTY/X11/agent default-reject.
- Client: `connect_stream` over a provided stream (WASM-compatible); session
  channel `exec` for the dispatch "reverse git runner" pattern.
- **Result**: a working SSH+exec appliance (server + client). Immediately useful.

**Layer 5: Port forwarding (bidirectional)**
- `direct-tcpip` (local→remote) and `forwarded-tcpip`/`tcpip_forward`
  (remote→local) channel types, both gated by ACL scopes.
- Client-side: opens `direct-tcpip` channels (dispatch's `start_forward`
  pattern); requests `tcpip_forward` for remote→local.
- **Result**: a working SSH+forwarding appliance. The VPN-like topology
  (WireGuard + Postgres + Redis over SSH forwarding) works.

**Layer 6: SOCKS5 server**
- A SOCKS5 server that accepts local connections and opens `direct-tcpip`
  channels to forward them. Consumer of Layer 5's API.
- In alknet-ssh (the VPN-like use case needs it there). Extractable to
  `alknet-socks5` if a second consumer appears (two-way door).
- **Result**: a working SSH+SOCKS5 proxy. The reference implementation's
  SOCKS5 feature is preserved.

**Layer 7: SFTP subsystem**
- Server: `russh-sftp::server::run` over a subsystem channel's stream.
- Client: `russh-sftp::client::SftpSession` over a channel stream.
- In alknet-ssh; extractable if warranted (two-way door).
- **Result**: SFTP file transfer over SSH.

### De-risk POC (DP-9)

A Phase 0 POC validating `connect_stream` ↔ `run_stream` over
`tokio::io::duplex()`, plus a WebTransport-stream-as-`Connection` →
`run_stream` POC validating the ADR-040 contract. Timeboxed; if they pass, the
stream-wiring spec is straightforward; if they surface constraints, they fold
into the spec.

### Three-path model (DP-10)

ALPN/QUIC primary, bare-TCP co-equal (off by default, config reserved in the
schema for git-over-SSH), WebTransport as the browser path (ADR-040). All three
share `server::Config` + `Handler` + ACL; only the stream source differs.

## Open Questions to Carry into Phase 1

The following should become OQs in `docs/architecture/open-questions.md`
(numbering assigned by the Architect — likely OQ-41 onwards, since OQ-01–OQ-40
exist):

- **OQ-SSH-01 (host key sourcing)**: vault-derived default + config override —
  resolved by the DP-1 ADR. The exact config-field shape may stay open.
- **OQ-SSH-02 (channel policy v1 surface + default-deny scope vocabulary)**:
  the set of allowed channel types / request types is resolved by the DP-5
  ADR; the exact scope vocabulary for forwarding destinations + exec commands
  (e.g., `ssh:forward:127.0.0.1:5432` vs a resources-style shape) stays open —
  it interacts with how operators express allow-lists in `DynamicConfig` and
  with the fact that `Identity.resources` is composition-only (ADR-022).
- **OQ-SSH-03 (SOCKS5/SFTP extraction)**: confirm SOCKS5 and SFTP start in
  alknet-ssh and extract only if a second consumer of the forwarding/channel
  API appears — resolved (in favor of in-alknet-ssh-now, extract-later) by
  the DP-4 ADR. Two-way door.
- **OQ-SSH-04 (POC outcome)**: did the `duplex()`-based round-trip POC pass, and
  did the WebTransport-stream POC validate the ADR-040 contract? Resolved by
  POC Specialist results.
- **OQ-SSH-05 (client WASM surface)**: confirm alknet-ssh's client API takes a
  stream (not a socket), preserving the WASM door russh's runtime abstraction
  opened. This is a design constraint, not a deferral — the client must not
  reach for `tokio::net` types in its public surface.
- **OQ-SSH-06 (bare-TCP listener)**: config shape reserved; listener
  implementation is a two-way door. Git-over-SSH is the forcing function —
  decide based on whether the build needs to be a git-over-SSH target.

## Next Steps (Phase 0 → Phase 1)

1. **You decide** on the DP recommendations (or amend them). DP-1, DP-4, DP-5,
   DP-10 are the load-bearing architectural choices. DP-2, DP-3, DP-6, DP-7,
   DP-8 are defaults recommended as-is; DP-9 is a POC task.
2. **POC** (DP-9): spawn a POC Specialist to validate `connect_stream` ↔
   `run_stream` over `tokio::io::duplex()` and the WebTransport-stream path.
   Timeboxed; if it passes, the stream-wiring spec is straightforward; if it
   surfaces constraints, they fold into the spec.
3. **Phase 1 (Architect)**: produce `docs/architecture/crates/ssh/README.md` +
   component specs organized by channel layer (e.g., `ssh-stream.md` for
   Layer 1, `ssh-connection.md` for Layer 2, `ssh-channels.md` for Layer 3,
   `ssh-exec.md` for Layer 4, `ssh-forwarding.md` for Layer 5, `ssh-socks5.md`
   for Layer 6, `ssh-sftp.md` for Layer 7, `ssh-client.md` for the client/WASM
   path, `ssh-tcp-listener.md` for the bare-TCP path), ADRs for the accepted DPs
   (host-key sourcing, channel policy + default-deny, ssh server+client+
   forwarding+socks5+sftp scope + layered build order, bare-TCP config shape),
   and the OQs above in `open-questions.md`. Update `docs/architecture/README.md`
   index and ADR table.

## References

- `docs/sdd_process.md` — Phase 0 process definition
- `docs/architecture/overview.md` — ALPN-as-service, crate graph, ProtocolHandler
- `docs/architecture/crates/core/core-types.md` — ProtocolHandler, Connection, BiStream
- `docs/architecture/crates/core/auth.md` — AuthContext, IdentityProvider, SshAdapter example
- `docs/architecture/crates/http/webtransport.md` — WebTransport substrate spec
- `docs/architecture/decisions/001-alpn-protocol-dispatch.md` — ALPN dispatch
- `docs/architecture/decisions/002-protocol-handler-trait.md` — ProtocolHandler trait
- `docs/architecture/decisions/004-auth-as-shared-core.md` — hybrid auth
- `docs/architecture/decisions/007-bistream-type-definition.md` — BiStream trait
- `docs/architecture/decisions/010-alpn-router-and-endpoint.md` — endpoint, TCP-is-handler-concern
- `docs/architecture/decisions/014-secret-material-flow-and-capability-injection.md` — Capabilities
- `docs/architecture/decisions/022-handler-registration-provenance-and-composition-authority.md` — registration bundle
- `docs/architecture/decisions/025-vault-local-only-dispatch.md` — vault local-only
- `docs/architecture/decisions/027-tls-identity-redesign-acme-rawkey-decoupling.md` — TLS identity model (symmetry reference for DP-1)
- `docs/architecture/decisions/038-http3-and-webtransport-as-first-class.md` — h3/WebTransport first-class
- `docs/architecture/decisions/040-webtransport-alpn-stream-proxy.md` — ALPN-stream-proxy (SSH-over-WebTransport path)
- `docs/architecture/decisions/043-webtransport-bidirectional-alpn-substrate.md` — WebTransport as bidirectional ALPN substrate
- `docs/research/references/ssh/russh/01-06` — russh deep-dives (overview, keys, protocol, crypto, internals, usage)
- `docs/research/references/ssh/russh-sftp/01-07` — russh-sftp deep-dives (overview, wire protocol, key types, client/server API, data flow, quick reference)
- `/workspace/russh/` — russh 0.60.2 source (authoritative; `russh-util/src/runtime.rs` shows the WASM runtime swap)
- `/workspace/russh-sftp/` — russh-sftp source (WASM-targeted protocol parsing)
- `/workspace/@alkdev/alknet-main/crates/alknet-core/src/` — reference implementation
  (`transport/iroh_transport.rs:94` shows the `tokio::io::join` adapter; `server/`,
  `interface/ssh.rs`, `client/`, `socks5/` for prior art)
- `/workspace/@alkdev/dispatch/` — concrete downstream consumer the user wants to
  replace with this stack: axum + `russh = "0.60"` SSH **client** for "reverse git
  runner" over Docker/vast.ai. `src/ssh.rs` (russh client wrapper, 143 lines),
  `src/handlers.rs::start_forward` (`channel_open_direct_tcpip` local→remote
  forwarding), `src/sftp.rs` (russh-sftp client). No SOCKS5 — that's the
  alknet-original feature preserved here. Dispatch is a textbook consumer of the
  alknet-ssh **client** + **forwarding** primitives, which is why those live in
  alknet-ssh rather than being duplicated per-consumer.