@airterm/protocol

Browser-safe AirTerm protocol primitives shared by the web client and CLI agent. The package implements capability URLs, HKDF key separation, Noise transport, binary framing, and terminal message codecs for protocol version 1.

Its additive streaming-transfer extension uses feature negotiation, 64-bit offsets, bounded acknowledgement windows, and purpose-specific policies for encrypted terminal fonts and clipboard images. Receivers can stream directly to disk, allowing later file-transfer features to grow without replacing the wire format.

npm install @airterm/protocol

AirTerm uses Noise_NNpsk0_25519_ChaChaPoly_BLAKE2b. Applications should import the public APIs from the package root.

import { deriveCapabilityKeys, NoiseTransport } from '@airterm/protocol';

Requires Node.js 22.12 or newer for Node-based consumers. Browser consumers need Web Crypto and WebAssembly support.

Direct transport extension

Protocol v1 framing is unchanged. SessionDescription advertises p2p-v1; peers must explicitly accept it before using inner types 21 (P2PControl), 22 (OutputAck), and 23 (RecoveryComplete). Older peers remain on relay. Acceptance can enable byte-offset recovery without attempting WebRTC.

EncryptedConnection owns each path's Noise state and bounded outbound queue. Relay and direct paths have independent handshakes. Direct handshake binding includes the session ID, relay pairing ID, and random negotiation ID. Signaling and handoff coordination travel inside relay encryption. The gateway requires no SDP/ICE parsing or protocol changes. Exactly one path carries application data; acknowledgement and lifecycle coordination may still use relay.

SDP is limited to 32 KiB, candidates to 2 KiB each and 64 per peer, and signaling to 256 KiB per peer. Direct frames are encrypted once, then fragmented into messages no larger than 16 KiB. Receivers assemble one bounded frame at a time. Negotiation has a ten-second deadline, transfer draining thirty seconds, and handoff two seconds. Ambiguous handoffs require a fresh relay pairing.

Output acknowledgements refer to contiguous PTY byte offsets consumed by the terminal renderer, not merely received by the socket. Never acknowledge across a gap, reuse a cipher after failure, or replay uncertain terminal input.

Account encryption envelopes (0.4 prerelease)

The vault and pairing exports are additive application envelopes; terminal protocol v1 framing is unchanged. Vaults use RSA-OAEP-3072/SHA-256, AES-256-GCM, and context-bound HKDF. Version 1 fixes passphrase Argon2id parameters at 64 MiB, three iterations, one lane, 16-byte salt, and 32-byte output; browser derivation lives in the application worker. Unknown fields, algorithms, versions, sizes, or substituted account/session context must fail closed.

Exactly one primary vault wrapper and one user-held recovery wrapper are supported. The pairing encryption secret is distinct from the polling credential and never reaches the server. These primitives do not authenticate a downloaded browser application or provide an independent cryptographic audit.

The backend pins a reproducible prerelease tarball until separately authorized registry publication. Publish the protocol before any CLI release that depends on it; do not relabel a prerelease artifact as an already published version.