@ronomon/mime - npm Package Compare versions

Comparing version 1.1.0 to 1.1.1

package.json

 {
   "name": "@ronomon/mime",
-  "version": "1.1.0",
-  "description": "Fast, robust, compliant MIME decoder.",
+  "version": "1.1.1",
+  "description": "Fast, robust, standards-compliant MIME decoder. Ships with extensive tests and fuzz tests.",
   "main": "index.js",
@@ -11,4 +11,16 @@ "repository": {
   "keywords": [
+    "buffer",
+    "decode",
+    "decoder",
+    "email",
+    "message",
     "mime",
-    "decoder"
+    "RFC 2045",
+    "RFC 2046",
+    "RFC 2047",
+    "RFC 2183",
+    "RFC 2231",
+    "RFC 5322",
+    "smtp",
+    "standards-compliant"
   ],
@@ -15,0 +27,0 @@ "author": "Joran Dirk Greef",

README.md

 # mime
-Fast, robust, compliant MIME decoder. Ships with extensive tests and fuzz tests.
+Fast, robust, standards-compliant MIME decoder. Ships with extensive tests and fuzz tests.
 
-## Standards Compliant
+## Installation
+```
+npm install @ronomon/mime
+```
+
+## Fast
+
+* Decodes on demand only as much as necessary to access a particular property. For example, if you need `mime.subject`, then `MIME` will search for the `CRLF` pair marking the end of the headers and decode only the `subject` header, without decoding any other headers and without decoding the body. This works well with the first few layers of spam defenses, which often only need to decode particular headers to reject an email.
+
+* Caches decoded properties for subsequent use.
+
+* Uses native fuzz-tested C++ [Base64](https://github.com/ronomon/base64) and [Quoted-Printable](https://github.com/ronomon/quoted-printable) bindings. `MIME`'s Base64 decoder in particular was developed for decoding wrapped Base64 [more efficiently](https://github.com/ronomon/base64#motivation) and detecting obvious corruption and character truncation.
+
+* Uses custom lookup tables to minimize the cost of branching through too many conditionals when decoding.
+
+* Avoids unnecessary string and buffer allocations. Algorithms accept and work with buffers directly, and allocate and copy buffers only when necessary.
+
+* Avoids regular expression decoders.
+
+## Robust
+
+* Provides detailed error messages which refer to the relevant RFCs to assist debugging, and which can be used directly as part of an SMTP `reply`.
+
+* Accepts `CRLF` and `LF` line-endings (which are common) but not `CR` line-endings (which are rare).
+
+* Accepts illegal transport padding frequently added by intermediaries (e.g. within the angle brackets of a `msg-id` or `angle-addr`, and between tokens in an `encoded-word`).
+
+* Decodes a variety of malformed but common mailbox syntaxes (e.g. no angle brackets around the `addr-spec`, with a `display-name` present on the left or right).
+
+* Removes balanced single quotes around the `display-name` or `addr-spec` in an email address (sometimes added by Outlook).
+
+* Decodes `encoded-words` not separated by `WSP`.
+
+* Decodes `encoded-words` with empty `encoded-text`.
+
+* Decodes `encoded-words` found in `Content-Type` and `Content-Disposition` parameters (used by Outlook and Gmail contrary to [RFC 2047 5 Use of encoded-words in message headers](https://tools.ietf.org/html/rfc2047#section-5)).
+
+* Removes any directory path components from an attachment name or filename (when accessed via `mime.filename`, see Usage below).
+
+* Decodes `msg-ids` not separated by whitespace or commas (i.e. separated only by angle brackets).
+
+* Rejects unrecognized `Content-Transfer-Encoding` mechanisms contrary to [RFC 2045 6.4 Interpretation and Use](https://tools.ietf.org/html/rfc2045#section-6.4) (e.g. anything other than `7bit`, `8bit`, `binary`, `base64`, or `quoted-printable`). This is to avoid accepting responsibility for content which will not display correctly, if at all. In contrast, the spec advocates silently altering the `Content-Type`.
+
+* Rejects malicious `RFC 2231` continuation indices designed to cause overallocation.
+
+* Rejects Base64 data containing illegal characters (anything which is not a valid Base64 or whitespace character, e.g. null bytes which could cause security issues).
+
+* Rejects Base64 data which is clearly truncated (as opposed to just missing padding).
+
+* Rejects Quoted-Printable data containing illegal characters (anything which is not a valid Quoted-Printable character, e.g. null bytes which could cause security issues).
+
+* Rejects illegal character sequences according to the specified `charset`.
+
+* Rejects truncated character sequences according to the specified `charset`.
+
+* Normalizes and aliases a variety of character sets to the canonical character set, (e.g. `ks_c_5601-1987` which is sometimes used by Outlook is aliased to `CP949` - Korean, otherwise the text would decode incorrectly).
+
+* Rejects unknown character sets not supported by [`iconv`](https://github.com/bnoordhuis/node-iconv).
+
+* Decodes `text/*` body parts to `UTF-8` buffers if the `Content-Type` indicates that the body is encoded in any other character set.
+
+* Rejects unterminated `comments` and `quoted-strings`.
+
+* Rejects invalid `Content-Type` syntax.
+
+* Detects missing multipart parts (e.g. no terminating boundary delimiter).
+
+* Rejects dangerous `message/external-body` and `message/partial` media types.
+
+* Decodes a variety of time zones and year formats.
+
+* Rejects invalid `Date` syntax.
+
+* Rejects missing `From` header.
+
+* Rejects headers containing forbidden characters.
+
+* Rejects folded header lines which exceed the 998 line length limit, but only after applying grace for clients such as Outlook.com which exclude the `field-name` and `colon` from their character count, and which mistake the limit to be 1000 characters excluding the CRLF. The limit is in fact 998 characters excluding the CRLF.
+
+* Rejects multipart boundaries containing forbidden characters.
+
+* Rejects malicious data designed to cause CPU-intensive decoding and stack overflows.
+
+* Rejects malicious multiple occurrences of crucial headers and parameters, which could cause clients to render an email differently from that scanned by anti-virus software.
+
+## Standards-Compliant
+
 * [RFC 5322](https://tools.ietf.org/html/rfc5322) - Internet Message Format.
@@ -17,31 +103,44 @@
 
-## Installation
-```
-npm install @ronomon/mime
-```
-
 ## Usage
-#### Decoding
-`MIME` decodes on demand only as much as necessary to access a particular property. For example, if you need `mime.subject`, then `MIME` will search for the end of the headers, and then decode only the `subject`, and not all other headers, or the body.
 
 ```javascript
 var MIME = require('@ronomon/mime');
+
+// Instantiate a new mime instance (no decoding will take place):
+
 var mime = new MIME.Message(buffer);
 
-mime.headers;
-mime.body;
+// Decoding will only take place when the following getter properties are accessed.
+// These getter properties may throw an exception for malformed MIME data.
 
-mime.from;
-mime.to;
-mime.cc;
-mime.bcc;
-mime.date;
-mime.subject;
-mime.parts;
+mime.headers;             // { 'received': [<Buffer>] }
+mime.body;                // <Buffer>
+
+mime.from;                // [ { name: <String>, email: <String> } ]
+mime.sender;              //   { name: <String>, email: <String> } / undefined
+mime.replyTo;             // [ { name: <String>, email: <String> } ]
+mime.to;                  // [ { name: <String>, email: <String> } ]
+mime.cc;                  // [ { name: <String>, email: <String> } ]
+mime.bcc;                 // [ { name: <String>, email: <String> } ]
+
+mime.messageID;           //   <String> / undefined
+mime.references;          // [ <String>, <String> ]
+mime.inReplyTo;           // [ <String>, <String> ]
+
+mime.date;                // <Unix Timestamp Integer> / undefined
+mime.subject;             // <String>
+
+mime.contentDisposition;  // { value: <String>, parameters: {} }
+mime.contentType;         // { value: <String>, parameters: {} }
+mime.contentID;           // <String> / undefined
+mime.filename;            // <String> / undefined
+
+mime.parts;               // [ <MIME.Message>, <MIME.Message> ]
 ```
 
 ## Tests
-To run all included tests:
+
+To run all included tests and fuzz tests:
 ```
 node test.js
 ```

No alert changes

Improved metrics

Total package byte prevSize

195715

increased by3.32%

Number of lines in readme file

146

increased by210.64%

No dependency changes