# alktunnels

Arbitrary bidirectional tunnels over [alkcall](https://crates.io/crates/alkcall)
channels: TCP, UDP, unix sockets, and other stream or datagram
substrates — in the `ssh -L` / `ssh -D` / `ssh -R` sense, without SSH.

A producer/consumer protocol crate riding alkcall channels the same
way [alktty](https://crates.io/crates/alktty) does (`alk/tty` is the
sibling precedent): the producer half registers the `alk/tunnel` open
op and pumps bytes between the channel and the substrate; the consumer
half is the typed session (`TunnelSession`) that opens tunnel channels
and owns teardown.

## A tunnel is a resource, not an address

Open-op params identify a produced resource + substrate:

```json
{ "resource": "postgres-primary", "substrate": "tcp" }
```

The producer owns the backing — the consumer never learns an address.
Rich addressing (SOCKS5 ATYP, per-datagram remotes) enters only
through the `-D`/dynamic composition path, inside the tunnel payload,
never in the wire (ADR-001).

- Wire format: `docs/architecture/wire.md` (+ the BAST document at
  `docs/architecture/bast.md`)
- Open-op params: ADR-001; codec: ADR-003; ALPN: ADR-002
- Producer shapes: ADR-004; consumer session: ADR-005; ACL: ADR-006
- The full spec set: `docs/architecture/` (overview, wire, producer,
  consumer, six ADRs, OQ tracker)

## Status

v0.1.0 — the v1 protocol implementation, Phase-2 complete (spec:
`docs/architecture/`; reviews: `docs/reviews/`). The wire surface
(params, ALPN, codec) is one-way-door stable from this point; the
API surface becomes ABI-stable at the first external consumer.

## Features

| Feature | Contents | wasm |
|---------|----------|------|
| *(default)* | params, wire codec, open-op spec, establisher shapes, `TunnelSession` — protocol only | yes |
| `local` | TCP/UDP/unix dial + listen helpers (real sockets) | no |

## Verification

```bash
cargo test                                    # default crate (wasm-clean)
cargo test --features local                   # + real-socket suites
cargo clippy --all-targets -- -D warnings
cargo fmt --check
cargo check --target wasm32-unknown-unknown   # the wasm-clean guard
```

## License

MIT OR Apache-2.0