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.

$3

``bash


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
`

$3

Download the latest release artifacts or build them locally:

`bash


local build


npm run build
npm pack
`

Quick start

$3

`bash


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
`

$3

You can use any of the following:

`bash


simplest: positional shorthand

nt 4932

explicit command & code, default output = current dir

nt recv 4932
`

$3

Pass --pq:

`bash


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 : 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+.

`bash


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:

`jsonc
{
// 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:

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

License

AGPL-3.0-only