Repository navigation
Adhal 0.1.0
The first release of Adhal: a one-shot, no-account file drop between two
machines. The receiver shows a five-word code, as words or as a QR
symbol. The sender types or scans it, and the file goes directly between
the two machines over the Holepunch DHT, encrypted end to end.
npm install --global @ad-hal/cliNode.js ≥ 24, on macOS or Linux. The packages are
@ad-hal/cli and
@ad-hal/engine, which
the CLI depends on. Any other package that claims to be Adhal is
unofficial.
Security fixes in this release: none. It is the first release.
What a drop does
- The code is split. A two-word public nameplate names the DHT
topic. A three-word secret (~38.8 bits) is the password to a
CPace-X25519-SHA512 PAKE, and it is never hashed into anything an
observer can see. A guess costs a live run against a peer that is
counting, and 100 failed guesses burn the drop. - Every byte after the handshake is sealed with ChaCha20-Poly1305,
under keys from the PAKE, with the frame length authenticated. - The receiver is asked first. Each offer shows its name, size, and
SHA-256 before anything is written, and a name that would run when
opened is warned about, even with--yes. - The file is verified, and nothing is overwritten. It is saved under
its name only once its digest matches, never in place of an existing
file, and only then is the sender told it arrived. - Streaming and resume.
ad-hal-send <code> - --code-on-argvsends
stdin as a stream of unknown length. An interrupted transfer resumes
from what the receiver already holds, once the sender has proved that
prefix is really its own. - A taken drop is reported. If someone else with the code reaches the
receiver first, both sides are told.
The commands are ad-hal-receive, ad-hal-send, and ad-hal-code.
--help on each lists every flag.
The protocol
The wire format is v2, frozen at the tag v2-final and specified in
PROTOCOL.md.
Section 12 states what v2 claims and what it does not. A change to the
wire from here on is a v3 break. A v1 peer gets a version-skew error,
not a session.
Measured
Between macOS behind an eero on Xfinity and Linux behind Starlink CGNAT,
on the public DHT: 40 trials of 10 MB, 20 in each direction, and all 40
were confirmed on both sides with matching hashes (2026-10-15). That is
one pair of networks. It shows the frozen wire works there. It is not a
success rate for other networks, and dual hard NAT has not been measured.
Before you use it
- Adhal is not anonymous. Each side's IP address is visible to the
other, and to the DHT nodes near the drop's topic. - The code is a bearer capability. Whoever holds it can complete the
drop. - Windows is not supported for security purposes yet.
- The cryptographic composition has not been independently reviewed.
The primitives come from@nobleand OpenSSL, and the CPace
implementation reproduces the CFRG test vectors. The review of 21
findings in
SECURITY-REVIEW.md
was AI-assisted, not independent. - This release has no provenance attestation, SBOM, or signed
checksums. They are planned for a later release. - The JavaScript API of
@ad-hal/engineis not stable before 1.0, and
the CLI's flags may still change. The wire protocol will not. - Not built yet: LAN discovery, a relay for networks where a direct
connection fails, and stable--jsonevents.
Support
The latest npm release and the default branch are supported. Report a
vulnerability privately, as
SECURITY.md
describes, not in a public issue. A version with a known vulnerability
will be deprecated on npm, so installing it prints a warning.