Best practices for Misfin clients and servers

(updated 11 May 2023)

(for comments, suggestions, well-wishes, insults, etc. - send a Misfin letter to rfc@misfin.org)

This is a living document, listing (in no particular order) things that Misfin software writers *should* keep in mind. Expect things to change as the first real servers and clients get written, and of course feel free to make suggestions.

1 Sending messages

Misfin messages are described as a "single line" of text - and they can be! - but they're not intended to be single sentences/paragraphs. Clients that include a text editor should allow users to add newlines (0xA) to their messages.

If a message is too big to fit within one request, prompt the user to split it into two messages. Making the user split the message means servers don't need to pay attention to a "message 1 of n..." field, and avoids messages having random splits between words or sentences.

When sending mail, take care not to send sender lines ("<") or timestamp lines ("@") - those are up to the receiving mailserver to add. (You should include them if you're forwarding a message, or more precisely, you shouldn't change anything about a forwarded message and send it as-is).

There is no formal way to send attachments, but hyperlinks are supported, so you can link to any content you want to attach. For privacy, you can secure these files with the fingerprint you receive from the recipient's mailserver, so only your recipient can download the attachment.

Clients are welcome to support a "rich" view of incoming messages, and replace or reformat sender/timestamp/recipient lines to make viewing easier, just like Gemini clients can style link or heading lines.

Redirects and temporary failures imply that the message should be resent, but clients should ask the user before resending anything, so they're kept informed. Try not to spam, either - if you get a temp failure, wait a few minutes before resending.

2 Receiving messages

Following links in messages, by necessity, reveals your IP address to the sender (thanks, Jeremy). If this is undesireable, consider downloading attachments via your mailserver - its IP is public anyway.

You don't need to store mail with sender/recipient/timestamp lines, if you want to store them some other way (like in a database)...

...but they should be added as per the spec when replying to messages or sending mail to other mailservers (e.g. forwards, replies, etc).

3 Technical details

Misfin servers are allowed to serve other protocols, which is why requests have "misfin://" prepended. The intention is to use this for serving attachments or mailboxes over Gemini. Don't add Misfin support to your Gemini server if it's not listening over port 1958! Clients are welcome to support sending mail to mailservers on alternate ports, but for everyone else's sake, keep your mailserver on the known port.

The fingerprint sent alongside a 20 status code should be the fingerprint of that mailbox, if it has its own certificate. Alongside securing attachments, the fingerprint is intended for use validating senders of messages you've received, via sending a blank message back to the sender's address and seeing if the fingerprint matches. Obviously, this won't work if you're not sending the right fingerprint.

Mailboxes that don't have their own certificate - in other words, a mailbox that doesn't strictly *exist* on the mailserver, but that the mailserver chooses to receive mail for - are an open question. I'm leaning towards sending the fingerprint of the mailserver's certificate, but maybe we're better off sending nothing and letting clients interpret that as "can't receive from them".

The reference implementation generates 2048-bit RSA keys, but anything supported by TLS should also be supported by Misfin. It was suggested that lighter devices might benefit from using elliptical-curve or ASCON keys, which are smaller.

A fun bug discovered in the reference implementation: don't assume the client or server will send its *whole* message in one go. Set a timeout and attempt to read until you get CRLF.

4 "Do something sensible"

Above all, Misfin is intended to fit into the small web ecosystem. Respect the user, respect privacy, play nice with others.