Skip to content

v1.20.0

Latest

Choose a tag to compare

@proofoftrinity proofoftrinity released this 06 Nov 03:38
· 4 commits to main since this release
v1.20.0
ce19856

Katacomb VPN 1.20.0

A desktop client for the Sentinel decentralized VPN network. Pick a node, pay for a
session on-chain, and tunnel through WireGuard, AmneziaWG, V2Ray, XRAY or Hysteria2.

1.20.0 adds Extend: buy more data or time on the node you are connected to, without
disconnecting. It also ends a session beside your connection through the VPN instead of
dropping it, and shortens the app's text, with the reasons one press away in a new Help
panel.

Highlights

  • Extend a session while connected. On a single-node session paid per GB or per hour,
    Extend (in the node's window, and on the connected session's card in Sessions) buys a
    new session on the same node, moves the connection onto it, then ends the old one. The
    unused part of the old deposit comes back when the chain settles it, about 2 hours
    later. In mainnet tests with the kill switch on, traffic paused for under a second over
    WireGuard and V2Ray and about 2 seconds over Hysteria2 on Linux, and about 11 seconds
    over WireGuard on Windows, and nothing got out during the pause. When a single-node
    session runs out, the banner now offers Buy again on that node.
  • Ending a session no longer drops your connection. Ending a session from Sessions
    while connected to another one used to disconnect, end it and reconnect, and the kill
    switch went down with the tunnel: in a test on Windows, about 14 seconds of traffic went
    out without the VPN. The app now ends it through the VPN. If the blockchain cannot be
    reached that way, it asks before ending it over your own connection, and says that your
    traffic goes out without the VPN until it reconnects.
  • Shorter text, with the reasons one press away. Each screen says one thing per line,
    and the explanation sits behind a ?. Many of them lead to a new Help panel, which the
    ? at the right of the header also opens. Tips open on keyboard focus as well as on
    hover.
  • The data warning comes earlier. The node counts the data it sends and the app counts
    what arrives, so on a lossy link the node runs ahead: in one test it cut a 1 GB session
    when the app read 86%. The warning now comes at 80% of the data (time stays at 90%).
    When a connection stops past that line, the banner says the session may have used up
    its data, instead of saying it is still open.
  • Sessions are counted the way nodes enforce them. Data counts download plus upload,
    a GB is 10^9 bytes, and time runs from the first handshake, gaps between connects
    included. Cards show when an hourly or plan session's paid time ends, and a renewed plan
    session is no longer offered a Reconnect that cannot work.
  • The End confirmation says what happens to your money. It said the remaining data or
    time was "forfeited". A P2P session pays the node for the usage it reported and returns
    the rest of the deposit when the chain settles it, about 2 hours after End; a plan
    session leaves what is left to the plan. For the same reason, the buy window now says you
    pay only for what you use, and the rest comes back about 2 hours after you end it.
  • Windows (beta): a working tunnel is no longer dropped when its counters miss a read.
    The byte counters come from the Windows service, and a slow reply was taken for a lost
    adapter: in a test, the app stood down a tunnel that carried traffic for another 76
    seconds.

Fixes in 1.20.0

  • Record the Windows measurements under REL-49
  • End a session beside the live connection through its tunnel (REL-49)
  • Record the Windows Extend measurements under REL-46
  • Say nothing about the kill switch in Extend until the setting is read
  • Keep a tunnel whose counters miss a read, and judge data early (REL-47, REL-48)
  • Header Help as a "?" icon on the far right
  • Short lines on the Provider, Plans and Multi-hop pages (RN-15)
  • Short lines in Sessions, Settings, wallets and the header (RN-15)
  • Short lines in the connect windows, details one press away (RN-15)
  • End and re-read on fresh sockets after an Extend switch
  • Keep the Sessions list through an Extend's switch
  • Record the Extend live checks in REL-46
  • Extend a live session: buy on the same node, move the tunnel, end the old one
  • Say what End does to the money instead of "forfeited"
  • Say in the buy window that over-buying a P2P session is safe
  • Score sessions the way the node enforces them
  • Give the CI verify job a 20-minute limit

Known limitations

  • A chain has a hard life of about two hours. Measured on mainnet: exit hops report
    no usage to the chain, so the exit's idle deadline is pinned at purchase and never
    moves, even while the entry still has quota. This is node-side behaviour, not a client
    bug, but it is yours to plan around. The app warns you about 10 minutes before the
    exit closes.
  • Chains can only be built from V2Ray and XRAY nodes. The other protocols have no
    equivalent of the relay mechanism a chain needs.
  • Expect roughly 2 to 3 MB/s and a large latency increase on a chain. Chains are for
    privacy, not speed.
  • Without systemd-resolved, a missing resolvconf still shows up after you pay. The
    app cannot safely install one on such a system, so a WireGuard or AmneziaWG connection
    there pays first, then offers Retry without VPN DNS on the same session, which sends
    your DNS queries outside the tunnel. To avoid it, set up a resolvconf provider such as
    openresolv the way your distribution documents.
  • Local-proxy mode tunnels only the apps you point at its SOCKS address. Everything else
    leaks, by design, and the kill switch does not apply.
  • A node that does not sign its handshake reply can be impersonated, and today that
    is nearly every node. The TLS and Reality wrapping does not authenticate the node, and
    there is nothing on chain to check its certificate against, so an attacker on your
    local network can answer the handshake in its place. A node reported at dvpnd 9.4 or
    later is required to sign, which closes this for it, but almost no node runs that
    version yet.
  • The wallet link check sees direct transfers only. Two wallets funded from the same
    third account of yours are still linked on chain, and the review cannot tell.
  • Windows is a beta. It was tested on Windows 11 only. Multi-hop chains and local proxy
    mode have not been tried on Windows yet: a chain runs the same XRAY path the Windows
    checks passed, but no chain was bought there.
  • Extend over WireGuard and AmneziaWG needs a node running dvpnx. On dvpnd, a new
    session closes the current tunnel before the node's reply can come back through it, so
    the app turns Extend off there, and on nodes it cannot identify, and says why. Plan
    sessions and chains cannot be extended yet.
  • On Windows, only the account that ran the installer can connect. The service admits
    that account and refuses the other accounts on the same PC.

Platform support

Linux x86_64. Tested on Debian 11+, Ubuntu 20.04+, and derivatives (Mint,
Pop!_OS, Zorin). The packaging and the VPN helper are unchanged since 1.19.0, whose .deb
was checked in containers on Debian 12 and 13 and Ubuntu 22.04, 24.04 and 26.04, and its
AppImage on those and Fedora 44. 1.20.0's .deb and AppImage were checked on a clean
Ubuntu 24.04 desktop.

Windows 10 and 11, x64 (beta). The installer and the Windows service are unchanged
since 1.19.0. 1.20.0's installer was checked in a clean Windows 11 VM (install, the
service, the app, reinstall over a running copy, uninstall), and connecting, Extend and
ending a session while connected were tested there on mainnet. Windows 10 has not been
tested.

Installation

Recommended: .deb

sudo apt install ./katacomb-vpn_1.20.0_amd64.deb

Installs a root daemon, so connect and disconnect never prompt for a password. It needs
one log out and log back in after the first install before that takes effect.

Alternative: AppImage

chmod +x katacomb-vpn-1.20.0.AppImage
./katacomb-vpn-1.20.0.AppImage

No install needed. The first connection that needs the VPN helper installs it, with one
password prompt. After that each privileged operation prompts for a password, cached for
a few minutes.

Windows 10 and 11 (beta): installer

Run katacomb-vpn-1.20.0-setup.exe and approve the administrator prompt. SmartScreen
warns first because the installer is not code-signed: check the download as below, then
choose More info and Run anyway. To remove it, use Settings > Apps; your wallets
and settings stay in %APPDATA%\katacomb-vpn.

Verifying your download

sha256sum -c SHA256SUMS --ignore-missing
gpg --verify SHA256SUMS.asc SHA256SUMS

Signed with key 740A F267 B0D8 162B E477 779D 7315 246A 6E67 F3C6. Import it first if
you have not already:

curl -sS https://keybase.io/proofoftrinity/pgp_keys.asc | gpg --import

On Windows, Get-FileHash .\katacomb-vpn-1.20.0-setup.exe in PowerShell prints the hash
to compare with its line in SHA256SUMS, and Gpg4win's gpg runs the same --verify.

Important

  • Connecting spends real funds. Sessions are blockchain transactions priced in
    udvpn, and a failed connection is refunded automatically, but an expired one is not.
  • The AppImage needs a fusermount before it starts, which stock desktops already
    have. If command -v fusermount3 fusermount prints nothing, install fuse3; on Arch,
    nss too. AppImageLauncher 2.2.0 cannot start it: upgrade to 3.0 or remove it. The
    APPIMAGE_EXTRACT_AND_RUN=1 workaround avoids needing FUSE. See the README.
  • AppImage on Ubuntu 24.04+ runs with the Chromium sandbox disabled. An AppImage can
    install neither an AppArmor profile nor a SUID sandbox helper, so prefer the .deb there.

Security model

Node operators are treated as adversaries. Everything a node sends is validated before it
reaches a privileged operation, because a VPN config can otherwise run shell commands as
root. See CLAUDE.md
for the full threat model and architecture.

License

GPL-3.0-or-later. Bundled binaries (v2ray, xray, hysteria, and Wintun's driver library
on Windows) and the libraries compiled
into the app and its VPN helper are under their own licenses, whose texts ship in the
packages. See
THIRD-PARTY-LICENSES.md.