feat: havenlink-tools — OS device management CLI

[SkogsErik]

Overview

havenlink-tools is the OS-level companion CLI to the havenlink chat application. It owns all device lifecycle operations that the chat app should not need to know about.

The tool is pre-installed at /usr/local/bin/havenlink-tools on every HavenLink OS image.

---

Motivation

The havenlink chat app is focused on messaging. Device-level concerns — USB key formatting, WiFi AP management, secure wipe — do not belong there. Keeping them separate gives a clean boundary:

Tool	Responsibility
havenlink	Chat, identity keypair usage, message transport
havenlink-tools	USB key init/rotate/verify, WiFi AP, device setup, wipe

The two tools share the USB key layout as a contract (see below).

---

USB Key Layout (shared contract)

<usb>/
  havenlink/
    version          — layout version (currently "1")
    wifi-salt        — 32 random bytes, owned by havenlink-tools
    identity.enc     — encrypted identity keypair, written by havenlink --init-usb-key

havenlink-tools owns version and wifi-salt. The chat app owns identity.enc. Neither tool touches the other's files.

---

Commands

havenlink-tools usb init   --device /dev/sdb    # format + write wifi-salt
havenlink-tools usb verify --device /dev/sdb    # check layout integrity
havenlink-tools usb rotate --device /dev/sdb    # rotate wifi-salt (new passphrase)
havenlink-tools usb show   --device /dev/sdb    # summary (no secrets printed)

havenlink-tools wifi start           --device /dev/sdb  # derive passphrase + start hostapd
havenlink-tools wifi stop                               # stop hostapd + wipe passphrase
havenlink-tools wifi status                             # show service state
havenlink-tools wifi show-passphrase --device /dev/sdb  # print passphrase for sharing

havenlink-tools setup    # interactive first-boot guide
havenlink-tools wipe --confirm  # emergency wipe of all runtime state

---

Implementation

A skeleton is already in place at tools/havenlink-tools.py. It includes:

• All subcommand stubs with argument parsing
• usb init/verify/rotate/show fully implemented
• wifi start — mounts USB, reads wifi-salt, derives WPA2 passphrase via HKDF-SHA256, writes to /run/hostapd.psk (tmpfs), starts hostapd
• wifi stop — stops hostapd, overwrites and unlinks /run/hostapd.psk
• wifi show-passphrase — derives and prints passphrase for sharing with trusted users
• wipe — shreds tmpfs state and stops WiFi

Remaining work

• Wire into build-image.sh: install tools/havenlink-tools.py to /usr/local/bin/havenlink-tools
• Add py3-cryptography to apk packages in build script (needed for HKDF)
• Integration test: init USB key, start WiFi, verify passphrase derivation is stable across reboots
• Update scripts/setup-device.sh to call havenlink-tools setup instead of doing its own thing
• Depends on: feat: WiFi AP mode with USB key-derived passphrase #22 (WiFi AP mode) for end-to-end testing

---

Security Notes

• wifi-salt is never printed; only the derived passphrase is shown via show-passphrase
• The derived passphrase lives only in tmpfs (/run/hostapd.psk, mode 0600), wiped on stop/reboot
• HKDF is one-way: recovering wifi-salt from the passphrase is computationally infeasible
• Rotating wifi-salt invalidates all previously shared passphrases