noisytransfer-cli

This CLI serves as an experimental playground for PQ-secure, end-to-end encrypted file transfer. In the short to medium term, this CLI will be optimized, and the insights will feed into a yet-to-be-built application for browsers and mobile devices. When those applications are released, this CLI will be ported to a language better suited to CLI apps (e.g., Rust or Go).

Fast end-to-end encrypted (E2EE) file transfer over WebRTC with short, human-readable pairing codes. The CLI speaks DTLS by default and can opt-in to a post-quantum (PQ) handshake with SAS confirmation. Additional documentation can be found here.

Installation

Requires Node.js 22 or newer.

npm

# CLI (global)
npm i -g @noisytransfer/cli
# or as a lib:

# library usage (local dependency)
npm i @noisystransfer/cli

# quick try without installing
npx noisytransfer-cli --help

Binaries

Download the latest release artifacts or build them locally:

# local build
npm run build
npm pack

Quick start

Send

# send a file
nt send ./photo.jpg

# send multiple paths (bundled as .tar on the wire)
nt send report.pdf ./docs ./assets

You’ll see:

Code: 4932
  nt 4932
  nt recv 4932 

Receive

You can use any of the following:

# simplest: positional shorthand
nt 4932

# explicit command & code, default output = current dir
nt recv 4932

Post-quantum (PQ) mode

Pass --pq:

# sender prints "Code: 5527e74d-pq"
nt send ./big.iso --pq
> Code: 1234-pq
# receiver can use the code.
nt recv 1234-pq ./downloads 

Behavior & flags

• --name <string>: override the advertised filename (single stream).
• Multi-path sends are tarred; receiver writes bundle.tar. If a file exists and --overwrite is not set, the receiver dedupes as bundle-1.tar, bundle-2.tar, …
• --overwrite: replace existing file instead of deduping.
• -y, --yes: auto-accept SAS (useful for non-interactive invocations). Does not imply --overwrite.
• -v: increase verbosity; includes [NT_DEBUG] traces.
• Filenames are sanitized on the receiver (no path traversal / reserved names). Output directory is always the receiver’s choice.

Build from source

Requirements: Node 18+.

# install (generates package-lock if missing)
npm install

# tests
npm test

# build JS bundles + types
npm run build

# make standalone binaries (Linux/macOS/Windows)
npm pack

Security model (short)

• Transport is WebRTC datachannel (DTLS). PQ mode wraps auth with a KEM-based handshake and SAS confirmation.
• Rendezvous codes are short-lived; both sides display a 6-digit SAS you can compare out-of-band.
• The receiver owns the destination directory; announced filenames are sanitized to safe leaf names.

Current Limitations

• The encoding of frames is currently extremely inefficient, which reduce the theoretical optimal throughput by roughly 4x in default DTLS and 5x in the PQ-case.
• XWING is a good alternative to the deprecated HybridkemX25519Kyber768 standard that is currently used here. But there are caveats that are discussed here. Currently i'm reviewing the starfighter publication, which might shift my opinion towards starfighter.
• Binary distributables are planned. Linux distributables work and have been tested with pkg and SEA on Ubuntu 22 and newer. However, .exe distributables on Windows are more complex and currently out of scope; see issue #39 in the node-webrtc fork. Nothing has been tested on macOS yet.

Future features

Status: currently disabled/broken; will be re-enabled with proper tests.

• Graceful WebRTC shutdown (remove hard-exit workaround) Plan to replace the current hard process exit (hard-exit.js) with a proper, graceful shutdown of the WebRTC stack once upstream issues in the dependency are resolved/worked around. The hard-exit is a temporary measure due to known problems in node-webrtc (see #35, #36, #37). The goal is to reliably close data channels/peer connections, tear down transports, and let the process exit cleanly without forcing it.

• Custom endpoints via config file Support a user config (e.g., ~/.config/noisytransfer/config.json, or %APPDATA%\NoisyTransfer\config.json on Windows) to override network endpoints and auth:

    {
      // planned fields
      "relay":   "wss://rvz.example.com/relay",
      "api":     "https://rvz.example.com",
      "headers": { "Authorization": "Bearer …" }
    }

  The CLI will use built-in defaults when the file is absent. A matching set of env vars may be recognized too.

• Explicit endpoint flags (optional override) After config lands, we may re-introduce CLI overrides like --relay/--api/--headers for advanced users and scripts. (In the current release these flags are intentionally disabled.)

• ICE/TURN configuration Optional --ice (or config stanza) for custom STUN/TURN servers used by the WebRTC peer connection.

• --stdin-name (re-enable) When sending from stdin (nt send -), allow announcing a filename for the receiver:

  cat report.pdf | nt send - --stdin-name report.pdf
  # default would be "stdin.bin" if omitted

License

AGPL-3.0-only