{"id":50951724,"url":"https://github.com/suir1/kiko","last_synced_at":"2026-06-18T02:04:25.270Z","repository":{"id":365507714,"uuid":"1272339961","full_name":"suir1/kiko","owner":"suir1","description":"C++20 croc-like encrypted file transfer with public relay, PAKE, NAT-aware direct attempts, and TUI","archived":false,"fork":false,"pushed_at":"2026-06-17T17:19:37.000Z","size":167,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T17:32:26.383Z","etag":null,"topics":["cpp20","croc","encrypted-transfer","file-transfer","nat-traversal","p2p","relay","tui"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/suir1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-17T14:12:15.000Z","updated_at":"2026-06-17T17:20:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/suir1/kiko","commit_stats":null,"previous_names":["suir1/kiko"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/suir1/kiko","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suir1%2Fkiko","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suir1%2Fkiko/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suir1%2Fkiko/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suir1%2Fkiko/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/suir1","download_url":"https://codeload.github.com/suir1/kiko/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suir1%2Fkiko/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34472831,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp20","croc","encrypted-transfer","file-transfer","nat-traversal","p2p","relay","tui"],"created_at":"2026-06-18T02:04:24.691Z","updated_at":"2026-06-18T02:04:25.259Z","avatar_url":"https://github.com/suir1.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kiko\n\n`kiko` is a C++20 croc-like file transfer tool: rendezvous relay, mnemonic pairing codes, PAKE end-to-end encryption (libsodium CPace / Ristretto255 + XChaCha20-Poly1305), zstd stream compression, resumable multi-file transfers, multiplexed relay connections, IPv6-first dual-stack networking, NAT-aware adaptive TCP punching with relay fallback, and CLI or FTXUI front-ends.\n\n## Install\n\nDownload prebuilt binaries from [Releases](https://github.com/suir1/kiko/releases), or install the latest release.\nCurrent packages cover Linux x64, Linux ARM64, macOS, and Windows x64.\n\nmacOS / Linux:\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/suir1/kiko/main/scripts/install.sh | sh\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/suir1/kiko/main/scripts/install.ps1 | iex\n```\n\nThe installer writes to `~/.local/bin/kiko` on macOS/Linux and `~/bin/kiko.exe` on Windows. Set\n`KIKO_INSTALL_DIR` to choose another directory, or `KIKO_VERSION=v0.1.2-alpha` to install a specific release.\n\nQuick check:\n\n```sh\nkiko doctor\nkiko send ./file-or-folder\nkiko recv \u003ccode\u003e --out ./downloads\n```\n\n## Features\n\n- **Short pairing codes** – auto-generated 6-character codes (e.g. `x7k9m2`). Pass any custom code with `--code` (short alphanumeric, or croc-style `4827-stone-iris-lake-ruby` with `-` splitting room label and PAKE secret).\n- **Terminal QR code** – when sending from a TTY, a QR code for the pairing code is printed (disable with `--no-qrcode`).\n- **IPv6 + IPv4 dual stack** – `AF_UNSPEC` resolve, dual-stack listeners (`::`), IPv6-first dial with IPv4 fallback. Bracketed endpoints: `[::1]:9000`.\n- **Resume** – writes to `\u003cname\u003e.kikopart`, renames on success. Re-run the same send/recv pair to continue; SHA-256 verifies the whole file. **imohash** fingerprints skip files you already have.\n- **Parallel connections** – relay path uses `--connections N` (default 4) with per-stream XChaCha20-Poly1305 subkeys.\n- **LAN discovery** – UDP multicast finds local relays; sender embeds a croc-style LAN relay (`--no-local` to disable). Receiver races LAN and external relays in parallel (`--local`, `--no-local`).\n- **Relay health check** – JSON `ping`/`pong` on each relay connection before rendezvous registration.\n- **LAN upgrade** – after the relay pipe is up, the receiver can probe sender LAN addresses before E2E PAKE.\n- **`.gitignore` support** – directory sends respect `.gitignore` rules (`--no-gitignore` to disable).\n- **Proxy** – `--proxy http://host:port` or `socks5://host:port` for relay connections.\n- **NAT awareness** – LAN candidates first, then reflexive addresses; adaptive punch timing before relay fallback.\n- **Connectivity planning** – STUN NAT probe (`--udp-probe`), rule-based `RoutePlan`, VPN-filtered LAN candidates, relay outbound path probing, and `~/.config/kiko/profile.json` success memory.\n- **Doctor** – `kiko doctor [--udp-probe] [--json] [--ai-explain]` probes relay reachability and suggests a transfer path.\n- **AI assist (BYOK, opt-in)** – OpenAI-compatible route advice and human-readable doctor explanations via env-configured API key.\n\n## Security model\n\nDefault codes are a single short string used for both relay rendezvous and PAKE. If the code contains `-`, the part before the first `-` is a public rendezvous label and the remainder is the PAKE secret (croc-style). The relay only sees `SHA256(\"kiko-room:\" + label)`. Peers run CPace-style PAKE over Ristretto255, mutual key confirmation, then XChaCha20-Poly1305 with HKDF-derived per-direction subkeys. The relay is a blind forwarder and cannot decrypt traffic.\n\n## Build\n\nPrimary build uses **vcpkg manifest mode** (dependencies in [`vcpkg.json`](vcpkg.json)).\n\n```sh\n# Bootstrap local vcpkg (first time)\ngit clone https://github.com/microsoft/vcpkg.git .vcpkg\n./.vcpkg/bootstrap-vcpkg.sh\n\ncmake --preset local-vcpkg\ncmake --build build\nctest --preset local-vcpkg\n```\n\nPresets (see [`CMakePresets.json`](CMakePresets.json)):\n\n| Preset | Use |\n|--------|-----|\n| `local-vcpkg` | `.vcpkg/` checkout in the repo |\n| `default` | `$VCPKG_ROOT` environment variable |\n| `system-deps` | Homebrew/pkg-config fallback + FetchContent |\n\nOn macOS you may need build tools for vcpkg ports: `brew install pkg-config autoconf automake libtool`.\n\n## Usage\n\nInteractive TUI:\n\n```sh\n./build/kiko tui\n```\n\nRun a relay (LAN-announced via multicast):\n\n```sh\n./build/kiko relay --listen [::]:9000\n./build/kiko relay --listen [::]:9000 --pass my-secret --room-ttl 10800\n```\n\nClients use `--relay-pass` or `KIKO_RELAY_PASS` when the relay requires a password.\n\n`kiko` uses `106.53.170.243:9000` as the built-in public relay when `KIKO_RELAY` is unset.\nOverride it for private/self-hosted relays:\n\n```sh\nexport KIKO_RELAY=relay.example.com:9000\nexport KIKO_RELAY_PASS=my-secret\n```\n\nBuild with a compile-time default relay (when `KIKO_RELAY` is unset):\n\n```sh\ncmake -DKIKO_DEFAULT_RELAY=relay.example.com:9000 --preset local-vcpkg\n```\n\nSend:\n\n```sh\n./build/kiko send ./file.bin\n./build/kiko send ./my-folder --relay [::1]:9000 --connections 8\n./build/kiko send ./repo --proxy socks5://127.0.0.1:1080\n```\n\nReceive:\n\n```sh\n./build/kiko recv \u003ccode\u003e --out ./downloads\n```\n\nNetwork diagnostics:\n\n```sh\n./build/kiko doctor\n./build/kiko doctor --udp-probe --json\n./build/kiko doctor --ai-explain   # requires OPENAI_API_KEY or KIKO_AI_API_KEY\n```\n\n`doctor` reports local LAN IPs, VPN/TUN IPs, the route/interface used for the relay target, and STUN mapped\naddresses when `--udp-probe` is enabled. This helps spot cases where a relay IP is being captured by a TUN\ninterface instead of going out through the physical LAN/Wi-Fi route.\n\nWhen VPN/TUN interfaces are detected and no proxy or manual bind is set, `send`, `recv`, and `doctor` probe both\nthe default relay path and a likely physical interface path, then use the reachable path with lower relay RTT.\nThe `doctor --json` output includes `outbound_path`, `outbound_reason`, and `outbound_probes` for this decision.\n\nTo test a physical-interface route while VPN/TUN is active:\n\n```sh\n./build/kiko doctor --avoid-vpn\n./build/kiko doctor --bind-interface en0\n```\n\n`--avoid-vpn` picks a likely physical interface automatically. `--bind-interface \u003cname\u003e` forces outbound TCP\nsockets onto a named interface where the platform supports it (macOS uses `IP_BOUND_IF` / `IPV6_BOUND_IF`;\nLinux tries `SO_BINDTODEVICE`, which may require privileges). These options apply to relay probing, relay\nrendezvous, relay mux connections, and active direct TCP dials. If the scoped physical route exists but relay\nping still fails, the physical network or relay port may be blocked; use a VPN DIRECT rule or a reachable relay\nport.\n\nOptional AI configuration (BYOK):\n\n```sh\nexport OPENAI_API_KEY=sk-...\nexport KIKO_AI_BASE_URL=https://api.openai.com/v1   # or http://localhost:11434/v1 for local\nexport KIKO_AI_MODEL=gpt-4o-mini\n```\n\nFlags: `--relay-pass`, `--auto-connections`, `--no-direct`, `--no-lan`, `--no-local`, `--local`, `--ip`, `--udp-probe`, `--ai-route`, `--ai-route-plan-only`, `--no-gitignore`, `--no-qrcode`, `--proxy`, `--bind-interface`, `--avoid-vpn`, `--tui`.\n\n`--ip` overrides the relay target (port from `--relay`) and the addresses advertised to the peer for direct/punch paths. When set, LAN relay discovery is skipped.\n\n## Tests\n\n```sh\nctest --preset local-vcpkg --output-on-failure\n```\n\nDocker network labs:\n\n```sh\nscripts/netlab_matrix.sh\nscripts/netlab_double_nat.sh\n```\n\n`netlab_matrix.sh` currently verifies fake-VPN outbound physical fallback in `doctor`, manual\n`--avoid-vpn`/`--bind-interface` overrides, fake-VPN relay transfer over the physical outbound path,\nsender-only and receiver-only fake-VPN relay transfers, same-LAN direct TCP, same-LAN isolated relay\nfallback, one-side-NAT direct TCP, and double-NAT relay fallback. The first Docker run builds the\n`kiko-netlab:local` image; later runs reuse the cache.\n\nThe Docker labs are also available as optional CTest targets:\n\n```sh\ncmake -S . -B build -DKIKO_ENABLE_NETLAB_TESTS=ON\nctest --test-dir build -L netlab --output-on-failure\n```\n\n`KIKO_ENABLE_NETLAB_TESTS` defaults to `OFF` so normal `ctest` runs do not require Docker or privileged networking.\n\n- `handshake` – PAKE session key agreement and rejection of wrong codes\n- `transfer` – multi-file directory round-trip, resume from partial\n- `progress` – `ProgressReporter` event sequence\n- `mux` – parallel relay connections and resume\n- `adaptive` – NAT classification and punch planning\n- `connectivity` – RoutePlan rule generation\n- `ai` – AI route plan validation and merge\n\n## Releases\n\nTags matching `v*` trigger the release workflow. It builds and tests Linux, macOS, and Windows packages, then\nuploads the packaged binaries to the matching GitHub Release.\n\n```sh\ngit tag v0.1.0-alpha\ngit push origin v0.1.0-alpha\n```\n\n## Stack\n\n| Layer | Choice |\n|-------|--------|\n| Crypto | libsodium (Ristretto255 PAKE, XChaCha20-Poly1305, SHA-256/HKDF) |\n| Network | Standalone Asio + C++20 coroutines (relay) / sync I/O (transfer) |\n| Compression | zstd |\n| CLI | CLI11 + nlohmann-json control messages |\n| UI | FTXUI (optional `--tui`) |\n| QR | Nayuki qrcodegen (vcpkg) |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuir1%2Fkiko","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsuir1%2Fkiko","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuir1%2Fkiko/lists"}