mudmail protocol spec written by mogery version 0.1.1 (210606, rough draft) Chapter 1: Introduction mudmail is a collection of protocols for decentralized mailservers and clients in hackmud. It enables users to send and receive messages between different mail scripts. This is good, while people can selfhost a mailserver, if they do not trust the operator of an other one. The issue of trust could be avoided with chats.tell, however the throughput is very limited. mudmail has two components: * mail servers, that communicate with each other to deliver messages using the S2S (server-to-server) protocol * mail clients, that communicate with a mailserver to send and receive messages using the C2S (client-to-server) protocol mudmail must always be adressed to hackmud usernames. If servers were to maintain special inboxes, they should start with the character %, and follow the hackmud username format otherwise. Chapter 2: Mailservers mudmail-compatible mailservers must be FULLSEC, and must support both the S2S and C2S protocols. A mailserver needn't contain a mail client. A reference (quineable) mail client will be available at mail.box. If users do not trust it, they can use alternatives, or roll their own. A reference mailserver will also be available at mail.server. Chapter 3: S2S protocol The S2S protocol is based on scriptor calls. Mailservers must consider accepting S2S packets when context.is_scriptor, needn't consider accepting S2S packets when context.calling_script, and shouldn't consider accepting S2S packets otherwise. S2S packets must be delivered to the _s2s argument. The argument must be either an array of packet objects or a packet object. The response must be respectively either an array of packet objects or a packet object. If the response is an array of packet objects, the order of the responses must match the order of the requests. mailserver.call({ _s2s: { t: "mm_hello" } }); ----- { t: "mm_hello", v: "0.1.1" } mailserver.call({ _s2s: [ { t: "mm_hello" }, { t: "mm_send", o: "mogery", r: "mg", s: "greeting", c: "hi there, mg! -mogery" } ] }); ----- [ { t: "mm_hello", v: "0.1.1" }, {, t: "mm_send", k: true } ] Example of S2S packets. Chapter 3.1: Packets Packet mm_hello Description: Server handshake. Request properties: (none) Response properties: v: Implemented mudmail version (current: "0.1.1") Packet mm_send Description: E-mail send packet. Note: receiveing mailserver should store time of arrival and store it as a timestamp to use in the future. Request properties: o: Username of sender (origin) r: Username of recipient s: Subject (max. 256 chars) c: Content (max. chars to be decided per-instance. recommended max.: 5k chars) Response properties: k: Was the e-mail recieved successfully? e: Error object (only if k is false.) c: HTTP-like error code t: Error message shown to user Possible error codes: 400: Invalid properties 403: Sender/sender's mailserver is blacklisted 404: Recipient not found 429: Spam detected/Rate limited Chapter 4: C2S Protocol The C2S protocol is based on scriptor and subscript calls. Mailservers must consider accepting S2S packets when context.is_scriptor or context.calling_script, and shouldn't consider accepting C2S packets otherwise. C2S authentication is based on context.caller. Implementations can add custom authentication methods for accessing speical inboxes, however, if based on packets, their packet names must not start with mm_, rather a custom prefix. C2S packets must be delivered to the _c2s argument. The argument must be either an array of packet objects or a packet object. The response must be respectively either an array of packet objects or a packet object. If the response is an array of packet objects, the order of the responses must match the order of the requests. mailserver.call({ _c2s: { t: "mm_hello" } }); ----- { t: "mm_hello", v: "0.1.1" } mailserver.call({ _c2s: [ { t: "mm_hello" }, { t: mm_mailbox, c: 10, p: 0 } {, t: "mm_send", r: ["mg", targetMailServer], s: "re: greeting", c: "hi there, mg! -mogery" } ] }); ----- [ { t: "mm_hello", v: "0.1.1" }, {, t: mm_mailbox, m: [ { f: ["mg", "senderMailServer"], s: "greeting", c: "hi there, mogery! -mg", t: 1623009420048 } ] }, {, t: "mm_send", k: true } ] Example of C2S packets. Chapter 4.1: Packets Packet mm_hello Description: Server handshake. Request properties: (none) Response properties: v: Implemented mudmail version (current: "0.1.1") Packet mm_send Description: E-mail send packet. Request properties: r: Array of recipient name and mailserver scriptor. s: Subject (max. 256 chars) c: Content (max. chars to be decided per-instance. recommended max.: 5k chars) Response properties: k: Was the e-mail sent/received successfully? (Possible error from recipient's mailserver should be forwarded.) e: Error object (only if k is false.) c: HTTP-like error code t: Error message shown to user Possible error codes: 400: Invalid properties/Recipient mailserver does not match requirements (e.g. SECLEVEL) 403: Recipient/recipient's mailserver is blacklisted 404: Recipient not found 429: Spam detected/Rate limited + possible codes of S2S/mm_send Packet mm_mailbox Description: E-mail retrieve packet. Request properties: c: Count of messages to return p: Page to return (0-based) Response properties: m: Array of messages f: Array of recipient name and mailserver name. s: Subject c: Content t: Time of arrival to mailserver, from Date.now() Possible error codes: 400: Invalid properties/Recipient mailserver does not match requirements (e.g. SECLEVEL) 403: Recipient/recipient's mailserver is blacklisted 404: Recipient not found 429: Spam detected/Rate limited + possible codes of S2S/mm_send Appendix A: Changelog 0.1.1 changed 421 error codes to 429s changed version number format to be semver-compatible added mm_mailbox C2S packet