Send files directly between devices over the internet - no cloud storage, no size limits.
@altersend/core
The peer-to-peer protocol and transfer orchestration for AlterSend. Hosts a Bare worklet that owns Hyperswarm peer discovery, file transfer, and the wire protocol — isolated from Electron and React Native renderers.
Bytes move over @altersend/drive: the sender reads chunks from the original file and the receiver writes them straight to the destination. Hyperdrive remains wired up as a fallback for peers on older builds that don't offer a drive channel — worklet/transfer/receiver.ts picks per file.
Architecture
This package has two halves:
- Worklet (
src/worklet/) — runs inside a Bare process spawned by the host app. Owns the network stack and never touches the UI directly. Communicates with the host over IPC. - Client (
src/client/) — typed RPC wrapper used by the host (Electron main process / React Native bridge) to invoke worklet commands and subscribe to events.
┌─────────────────────────────┐
│ Host app (Electron / RN) │
│ uses createTransferWorker │
│ Client(...) from this pkg │
└──────────────┬──────────────┘
│ IPC
┌──────────────▼──────────────┐
│ Bare worklet (this pkg) │
│ - TransferOrchestrator │
│ - TransferSwarm (DHT) │
│ - TransferStorage │
│ - Sender / Receiver │
│ - Pairing / Discovery / │
│ Recognition / Remember │
│ - DeviceIdentityStore │
│ - RememberedPeerStore │
│ - PeerControlChannel │
│ - RelayConfig │
└─────────────────────────────┘
Public API
From the host (renderer / main process)
import { createTransferWorkerClient } from '@altersend/core';
const client = createTransferWorkerClient(workerProcess, {
onEvent: (event) => {
},
});
await client.ready;
await client.host(); // generate + join a topic
await client.join(topicHex); // join an existing topic
await client.shareFiles(['/path/to/file']); // stage + announce files
await client.downloadFiles([...]); // pull from a peer
await client.disconnect(); // tear down + wipe storage
await client.closePeers(); // tear down without ending session
await client.initDeviceSecret({ ... }); // inject the keychain-sealed device secret
await client.hostPairing(); // open the pairing swarm (show a QR)
await client.joinPairing(topicHex); // join a pairing code (scan a QR)
await client.rememberVote({ ... }); // vote to remember a connected peer
await client.peersList(); // list remembered devices
await client.inviteDevice({ ... }); // invite a remembered device (no code)
await client.respondToInvite({ ... }); // accept / decline an incoming invite
await client.forgetPeer(devicePubkeyHex); // remove a remembered device
await client.setRelayConfig({ ... }); // enable / disable the relay fallback
Wire protocol
Exported types describe every message that crosses the IPC boundary between host and worklet:
TransferRPC— the command surfaceRendererTransferEvent,TransferStatus,TransferRole— events flowing worklet → rendererTransferMethod,API— command identifiers (API.methodsfor request/reply,API.channelsfor emit-only streams)HostReply,JoinReply,ShareFilesReply,DownloadFilesReply,DisconnectReply— RPC reply DTOsDownloadFileRequest,DownloadFileResult,IncomingFileOffer— request and result DTOs
Anything not re-exported from @altersend/core (the wire-format codecs, command-id constants, validation error class, peer-channel types) is internal and may change without notice.
Utilities
isPathSafe(value)— generic null-byte +..traversal check; safe to call from the renderer (no Bare-only deps)
Worklet entry point
Built output of src/worklet/index.ts is what the host spawns:
const worker = pear.run('packages/core/dist/worklet/index.js', [`--storage=${storageRoot}`])
The worklet exports nothing — it sets up RPC over IPC and handles SIGTERM, SIGINT, beforeExit, plus Bare's suspend / resume lifecycle events.
Storage
The transfer corestore is wiped on every disconnect — transfers do not resume across sessions, by design. What does persist: the device keypair (secret sealed in the OS keychain and injected via initDeviceSecret; only the public key + metadata hit disk) and the remembered-peer list (RememberedPeerStore, on HyperDB). Resumable transfers remain out of scope.
Security
Input that comes from peers (control messages) and from the renderer (download requests) is validated at the trust boundary:
- 64-hex-char check on every Hyperdrive key and Hyperswarm topic
- File-name traversal check (no
/,\,.., NUL byte, length > 255) - Bounded lengths on every wire field: ids 128, paths 4096, text 65536, display names 256, and 10,000 files per transfer. File size itself is not capped — only required to be a non-negative integer
- Hyperdrive entry signature check against wire-claimed size — sender can't lie about file size
- On drive transfers the same guarantee comes from the offer: the receiver rejects a
startwhose size differs, and every chunk is checked against its BLAKE2b hash before it is written
Out of scope: no rate limit on inbound peer control messages. A connected peer already shares our transfer topic, so a flood of download-progress events is treated as a connectivity nuisance, not a security boundary. If your threat model includes hostile paired peers, gate or throttle in the host before forwarding to the renderer.
Building
npm run build
Bundles via tsup (see tsup.config.ts) into dist/. Three entry points: index (host-side public API), client/worker-client (RPC wrapper), and worklet/index (the Bare worklet entry).
Testing
npm test
Pure-function tests covering the wire protocol, file-name and path-safety validation, and hex-key validation. The orchestrator / sender / receiver modules don't yet have integration tests — that's a tracked gap.
License
Apache-2.0