Abstract type representing a Magic Wormhole session.

Use runClient to get a Session on the Magic Wormhole Rendezvous server. Once you have a Session, use ping, list, allocate, claim, release, open, and close to communicate with the Rendezvous server.

Run a Magic Wormhole Rendezvous client. Use this to interact with a Magic Wormhole server.

Will throw a ServerError if the server declares we are unwelcome.

Short string to identify the application. Clients must use the same application ID if they wish to communicate with each other.

Recommendation is to use "$DNSNAME/$APPNAME", e.g. the Python wormhole command-line tool uses lothar.com/wormhole/text-or-file-xfer.

Short string used to differentiate between echoes of our own messages and real messages from other clients.

TODO: This needs to be cleanly encoded to ASCII, so update the type or provide a smart constructor.

Generate a random Side

Endpoint for a websocket connection.

Construct directly or with parseWebSocketEndpoint.

Parse a WebSocketEndpoint.

Allocate a nameplate on the server.

Throws a ClientError if the server rejects the message for any reason.

Identifier for a "nameplate".

A nameplate is a very short string that identifies one peer to another. Its purpose is to allow peers to find each other without having to communicate the Mailbox identifier, which is generally too lengthy and cumbersome to be easily shared between humans.

Typically, one peer will allocate a nameplate and then communicate it out-of-band to the other peer.

List the nameplates on the server.

Throws a ClientError if the server rejects the message for any reason.

Claim a nameplate on the server.

Throws a ClientError if the server rejects the message for any reason.

Identifier for a mailbox.

A mailbox is a shared access point between Magic Wormhole peers within the same application (specified by AppID). To get a mailbox, you must first acquire a Nameplate and then claim that nameplate for your side with claim.

A mailbox ID is defined in the spec as a "large random string", but in practice is a 13 character, lower-case, alpha-numeric string.

Open a mailbox on the server.

If there's already a mailbox open, the server will send an error message. In the current implementation, that error will arise in a strange and unexpected place.

See https://github.com/warner/magic-wormhole/issues/261#issuecomment-343192449

Close a mailbox on the server.

Throws a ClientError if the server rejects the message for any reason.

Error due to weirdness from the server.

Error caused by misusing the client.

Run an action that communicates with a Magic Wormhole peer through an encrypted connection.

Does the "pake" and "version" exchanges necessary to negotiate an encrypted connection and then runs the user-provided action. This action can then use sendMessage and receiveMessage to send & receive messages from its peer.

Can throw:

• PeerError, when we receive nonsensical data from the other peer
• PakeError, when SPAKE2 cryptography fails
• VersionsError, when we cannot agree on shared capabilities (this can sometimes imply SPAKE2 cryptography failure)

A connection to a peer via the Rendezvous server.

Normally construct this with open.

A Magic Wormhole peer-to-peer application session.

Construct one of these using withEncryptedConnection.

You get one of these after you have found a peer, successfully negotatiated a shared key, and verified that negotiation by exchanging versions. (Note that this does not include the "verifying" step mentioned in magic-wormhole's documentation, which is about a human being verifying the correctness of the code).

All messages in this session, sent & received, are encrypted using keys derived from this shared key.

Derive a new key for the given purpose

Construct a new key from the encrypted connection's session key for the given purpose

Something that went wrong with the client protocol.

An error occurred during versionExchange.

An error that occured during pakeExchange.

Send an encrypted message to the peer.

Obtain an EncryptedConnection with withEncryptedConnection.

The message will be encrypted using a one-off key deriving from the shared key.

Receive a decrypted message from the peer.

Obtain an EncryptedConnection with withEncryptedConnection.

Unencrypted text.

An offer made by a sender as part of the Magic Wormhole file transfer protocol.

Currently only supports sending simple text messages. A full version would also support sending files and directories.