docs: add connection key compression (rtun2) design spec

2026-08-02 12:03:41 -06:00
parent 9f1d04fcaf
commit ab1f74214a
1 changed files with 76 additions and 0 deletions
@@ -0,0 +1,76 @@
+# Connection Key Compression (rtun2) — Design
+
+## Goal
+
+Shrink the copy-paste connection key string so it is easy to copy and paste, without
+changing any user-facing workflow. A current `rtun1.` key is roughly 4 KB as a single
+unwieldy line; the goal is roughly half that.
+
+## Approach
+
+Compress the existing JSON payload with pure-Rust DEFLATE (`miniz_oxide`) before
+base64url-encoding. This is a clean break on the wire format:
+
+- New keys: `rtun2.` + `base64url(deflate(json))`
+- `decode` accepts only `rtun2.` keys; legacy `rtun1.` keys are dropped (per user decision)
+- `ConnectionKey` struct, CLI, and `listen`/`connect` integration are unchanged
+
+## Format
+
+```
+rtun2.<base64url-no-padding-of-deflate-of-json>
+```
+
+The JSON payload keeps the same shape, with `version` bumped to `2`:
+
+```json
+{
+  "version": 2,
+  "target": "127.0.0.1:4180",
+  "ca_cert_pem": "...",
+  "server_cert_pem": "...",
+  "server_key_pem": "...",
+  "client_cert_pem": "...",
+  "client_key_pem": "...",
+  "auth_token": "..."
+}
+```
+
+## Components
+
+| File | Change |
+| ---- | ------ |
+| `Cargo.toml` | Add `miniz_oxide` dependency |
+| `src/connkey.rs` | Prefix `rtun2.`, compress on `encode`, decompress on `decode`, version `2` |
+| `src/redact.rs` | `is_connection_key` detects `rtun2.` prefix |
+| Wiki (`droid-wiki/**`) | Document the `rtun2.` format and compression |
+
+## Validation
+
+`decode` validates, in order:
+
+- String starts with `rtun2.`
+- Base64url decode succeeds
+- DEFLATE decompression succeeds
+- JSON deserialization succeeds
+- `version == 2`
+- All string fields non-empty after trim
+
+## Testing
+
+- Round-trip test: encode → decode returns identical material; assert prefix `rtun2.`
+- Size assertion test: encoded key must be materially smaller than the raw JSON
+  (`base64url(json)` without compression), with a generous threshold so the build
+  stays robust across certificate size variation
+- Update redaction prefix tests
+
+## Docs
+
+Update wiki pages that document the key format: `features/connection-keys.md`,
+`reference/data-models.md`, `overview/glossary.md`, `applications/rustunnel-cli.md`,
+`security.md`, and `how-to-contribute/patterns-and-conventions.md`.
+
+## Out of scope
+
+- QR codes, binary container formats, zstd/brotli, key registry/rotation
+- `generate` command and file-based credential output