Signed Caravan swarms

The signed swarm is the availability layer beneath a cryptocursor. It is not the cursor itself and it does not grant authority.

The five security boundaries

1. Invitation: an invited body receives a pinned Ed25519 public key, a random BEP44 salt, a minimum accepted sequence, and a 32-byte secret manifest key.
2. DHT directory: the native Caravan bridge derives the BEP44 target from the public key and salt, fetches the mutable record, verifies its DHT signature and sequence, and rejects stale or differently signed heads.
3. Encrypted manifest: the DHT value contains only an AES-256-GCM envelope. The decrypted manifest supplies the magnet URI, webseeds, cursor root, capability root, payload cipher, epoch, and expiry.
4. Encrypted swarm: the torrent contains ciphertext chunks. Ordinary BitTorrent hashes protect block integrity; the declared payload cipher protects confidentiality and final authenticity.
5. Cursor authorization: signed cursor records and attenuated capability chains determine whether decrypted work is accepted and which effects a body may cause.

Keeping those boundaries separate matters. Torrent possession is not identity. A valid directory signature is not decryption authority. Decryption authority is not permission to continue every cursor. A capability does not prove that bytes remain available.

What a hostile peer can do

If an outsider learns only the DHT target, they can query or republish the encrypted directory value. If they learn an infohash, they can join that transport swarm, request ciphertext, seed ciphertext, measure timing and size, and attempt denial of service.

They still cannot:

• replace the accepted directory head without the pinned signing key;
• roll an invited body back below its minimum sequence;
• decrypt the directory manifest without the invitation's manifest key;
• decrypt a properly packaged encrypted payload;
• alter blocks without failing torrent hashes and authenticated decryption;
• author an accepted cursor or exercise an effect without valid record and capability chains.

This is deliberately not described as “nobody can join.” Public DHT and BitTorrent transports cannot enforce that claim once routing identifiers leak. The useful property is that an unauthorized participant gains no plaintext or accepted authority and may, at most, contribute storage and bandwidth while remaining an untrusted transport peer.

Publish a directory head

Prepare encrypted payload files and a torrent before publishing the directory. The publisher configuration is private and must contain:

• an Ed25519 private-key PEM path;
• a random 1–64 byte salt, encoded as base64url;
• a random 32-byte manifestKey, encoded as base64url;
• a monotonically increasing sequence and application epoch;
• a short expiry;
• a manifest with swarmId, cursorRoot, capabilityRoot, magnet source, and an explicit encrypted payload format.

Publish it from a native network body:

npm run swarm:publish -- ./private-swarm-publisher.json > ./invite-output.json

The command emits a DHT target and an invite object. The invite contains a decryption key: distribute it over an authenticated confidential channel and never commit it.

Resolve invitations in the bridge

Store one or more invite objects in a private JSON array, then start the bridge:

CURSOR_SWARM_INVITES_FILE=./private-invites.json \
CURSOR_ALLOWED_ORIGINS=https://curso.rs,https://spaceghost.github.io \
CURSOR_BRIDGE_HOST=0.0.0.0 \
npm run bridge

The bridge accepts no public mutation endpoint. It resolves each configured invite, verifies and decrypts the head, joins only the resulting allowlisted magnet with payload deselected, and exposes redacted security state to the operations console.

Remaining production work

The current implementation provides real Ed25519 verification, BEP44 sequence checks, AES-256-GCM manifest encryption, expiry checks, and a native DHT resolution path. It does not yet provide the encrypted payload packer, invite rotation UX, threshold directory keys, hardware key custody, global revocation, cover traffic, or admission-rate defense. Those claims remain explicitly out of scope until implemented and adversarially tested.