Skip to content

Releases

Adhal 0.1.2

Choose a tag to compare

@khartig khartig released this 28 Oct 04:06

Two fixes in @ad-hal/engine, and none in how a drop works: the wire
format is unchanged, the CLI behaves as before, and a 0.1.0, 0.1.1, or
0.1.2 peer can drop files to any of the others.

npm install --global @ad-hal/cli

Node.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 that a peer can reach. One
hardens the handshake classes against a caller that misuses them
(Q-22, below). 0.1.0 and 0.1.1 are not deprecated.

What changed

  • A handshake object ends at its first failure, as at its success
    (Q-22). Initiator and Responder wipe their secret material whichever
    way a step ends, but they locked themselves only after a success. So a
    program that called one again after a failure, on the same object, had
    it compute with zeros. A REPLY forged without the code was accepted, or
    a HELLO under an all-zero password was answered. No peer could reach
    this: the CLI, and every entry point the engine's README lists, build a
    new handshake object for each connection and stop using it once it
    throws. Only code calling the two exported classes directly could. Now
    any call after a failure throws "the handshake has already failed".
  • A reason a peer sends is cut at a character boundary. The reason
    in a CANCEL, a DECLINE, or a RESULT error is capped at 256 bytes. Cut
    inside a multi-byte character, it decoded to a replacement character
    and came out up to two bytes over the cap.

Behind both: the first full mutation run over the engine modules that
enforce the protocol, with every surviving mutant triaged and a test
added for each gap it showed, so 92.5% of 751 mutants are now killed
(history/W12-MUTATION-TRIAGE.md).
The tests are not part of either package.

Checking this release

Each of these runs on its own:

npm view @ad-hal/cli@0.1.2 dist.attestations.provenance.predicateType
gh release download v0.1.2 --repo khartig/adhal
sha256sum -c SHA256SUMS
gh attestation verify ad-hal-cli-0.1.2.tgz --repo khartig/adhal
gh attestation verify ad-hal-engine-0.1.2.tgz --repo khartig/adhal

The first command prints https://slsa.dev/provenance/v1. On macOS,
use shasum -a 256 -c SHA256SUMS in place of sha256sum. After an
install, npm audit signatures verifies the registry signatures of
everything installed, and the attestations of both Adhal packages.

The SBOMs list the dependency tree that was locked and tested. Neither
package ships a lockfile, so an install can resolve newer versions of
the packages that Adhal's dependencies depend on. npm sbom describes
what an install actually resolved.

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 @noble and OpenSSL, and the CPace
    implementation reproduces the CFRG test vectors. The review in
    SECURITY-REVIEW.md,
    21 findings and one found since, was AI-assisted, not independent.
  • The JavaScript API of @ad-hal/engine is 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 --json events.

What a drop does, the protocol, and what has been measured are in the
0.1.0 release notes.

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.

Adhal 0.1.1

Choose a tag to compare

@khartig khartig released this 22 Oct 04:19

Adhal works exactly as it did in 0.1.0: the code in both packages is
unchanged, and so is the wire format. What is new is how this release
was published. It is the first one built and published by GitHub
Actions, with no npm token, and anyone can check that the packages on
npm came from this repository.

npm install --global @ad-hal/cli

Node.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. 0.1.0 is not deprecated, and
a 0.1.0 peer and a 0.1.1 peer can drop files to each other.

What changed

  • Both packages were published by GitHub Actions through npm trusted
    publishing. npm accepts a publish of @ad-hal/engine or
    @ad-hal/cli only from this repository's release workflow, in an
    environment where each publish is approved by hand. No long-lived npm
    token exists to steal.
  • Each package has a provenance attestation on npm, so the package
    page shows which commit and workflow run built it, and
    npm audit signatures checks it.
  • The release carries its own artifacts: both tarballs, exactly as
    published, a SHA256SUMS file, and a CycloneDX SBOM for each package.
    Each tarball also has a GitHub build attestation, signed through
    Sigstore.
  • Both package READMEs link to these release notes, so the npm page
    says where to find out what changed in each version and which
    versions have security fixes.

Checking this release

Each of these runs on its own:

npm view @ad-hal/cli@0.1.1 dist.attestations.provenance.predicateType
gh release download v0.1.1 --repo khartig/adhal
sha256sum -c SHA256SUMS
gh attestation verify ad-hal-cli-0.1.1.tgz --repo khartig/adhal
gh attestation verify ad-hal-engine-0.1.1.tgz --repo khartig/adhal

The first command prints https://slsa.dev/provenance/v1. On macOS,
use shasum -a 256 -c SHA256SUMS in place of sha256sum. After an
install, npm audit signatures verifies the registry signatures of
everything installed, and the attestations of both Adhal packages.

The SBOMs list the dependency tree that was locked and tested. Neither
package ships a lockfile, so an install can resolve newer versions of
the packages that Adhal's dependencies depend on. npm sbom describes
what an install actually resolved.

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 @noble and OpenSSL, and the CPace
    implementation reproduces the CFRG test vectors. The review of 21
    findings in
    SECURITY-REVIEW.md
    was AI-assisted, not independent.
  • The JavaScript API of @ad-hal/engine is 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 --json events.

What a drop does, the protocol, and what has been measured are in the
0.1.0 release notes.

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.

Adhal 0.1.0

Choose a tag to compare

@khartig khartig released this 22 Oct 01:05

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/cli

Node.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-argv sends
    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 @noble and 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/engine is 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 --json events.

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.