@bobfrankston/iflow-direct 0.1.63 → 0.1.65

package/imap-protocol.js

@@ -344,21 +344,64 @@ function unquote(s) {
         return s.slice(1, -1).replace(/\\(.)/g, "$1");
     return s;
 }
+/** Build a TextDecoder for an encoded-word charset label, trying progressively
+ *  looser readings of the label before giving up on UTF-8.
+ *
+ *  TextDecoder throws RangeError on a label it doesn't know, and the caller's
+ *  catch then returned the RAW encoded text — so ONE unrecognized label put
+ *  `London_Startup_Is_Selling_Permanent=2C_Painless=2C_=22Stick-On=22` in the
+ *  user's subject line (Bob 2026-08-02, NNSquad via mailman). Labels seen in
+ *  the wild that TextDecoder rejects:
+ *    `en_US.UTF-8` — a POSIX LOCALE (language_TERRITORY.CODESET), not a
+ *                    charset; the real charset is the codeset after the dot.
+ *    `utf-8*en`    — RFC 2231 language suffix appended to the charset.
+ *    `utf8`        — no hyphen.
+ *  The raw label is tried FIRST so legitimate dotted names (`ansi_x3.4-1968`)
+ *  are never mangled by the locale rule. Last resort is UTF-8, which decodes
+ *  leniently (U+FFFD for bad bytes) rather than throwing — a couple of
+ *  replacement characters beat a subject full of quoted-printable. */
+function decoderFor(label) {
+    const raw = label.trim().toLowerCase();
+    const candidates = [raw];
+    const noLang = raw.split("*")[0]; // RFC 2231 suffix
+    if (noLang !== raw)
+        candidates.push(noLang);
+    const locale = noLang.match(/^[a-z]{1,8}(?:_[a-z0-9]{1,8})?\.(.+)$/);
+    if (locale)
+        candidates.push(locale[1]); // POSIX codeset
+    candidates.push(noLang.replace(/^utf[_]?8$/, "utf-8"));
+    for (const cs of candidates) {
+        try {
+            return new TextDecoder(cs);
+        }
+        catch { /* unknown label — try the next reading */ }
+    }
+    return new TextDecoder("utf-8");
+}
 /** Decode IMAP encoded-word (=?charset?encoding?text?=) */
 function decodeImapString(s) {
     if (!s)
         return "";
     // RFC 2047 §6.2: whitespace between adjacent encoded-words must be ignored
     const unfolded = s.replace(/\?=\s+=\?/g, "?==?");
-    return unfolded.replace(/=\?([^?]+)\?([BQ])\?([^?]+)\?=/gi, (_match, charset, encoding, text) => {
+    // Some mailers FOLD INSIDE an encoded-word, stranding the closing `?=` on
+    // the next line ("=?utf-8?Q?…_has_Shipped\r\n\t?="). RFC 2047 forbids it,
+    // but a JavaMail/hybris sender does it on every order mail in Bob's
+    // archive; the unterminated word then matched nothing at all and the raw
+    // `=?utf-8?Q?=EF=BB=BFYour_Order_has_Shipped` became the subject line.
+    // `[^?]*?` can't cross a `?`, so this only rejoins words whose terminator
+    // was separated by folding whitespace — a properly closed encoded-word
+    // never has whitespace before its `?=`.
+    const rejoined = unfolded.replace(/(=\?[^?]+\?[BQ]\?[^?]*?)\s+\?=/gi, "$1?=");
+    const decodedWords = rejoined.replace(/=\?([^?]+)\?([BQ])\?([^?]+)\?=/gi, (_match, charset, encoding, text) => {
         try {
-            const cs = charset.toLowerCase().replace(/^utf8$/, "utf-8");
+            const decoder = decoderFor(charset);
             if (encoding.toUpperCase() === "B") {
                 const raw = atob(text);
                 const bytes = new Uint8Array(raw.length);
                 for (let j = 0; j < raw.length; j++)
                     bytes[j] = raw.charCodeAt(j);
-                return new TextDecoder(cs).decode(bytes);
+                return decoder.decode(bytes);
             }
             else {
                 // Quoted-printable: collect bytes then decode with charset
@@ -375,13 +418,20 @@ function decodeImapString(s) {
                         i++;
                     }
                 }
-                return new TextDecoder(cs).decode(new Uint8Array(bytes));
+                return decoder.decode(new Uint8Array(bytes));
             }
         }
         catch {
-            return text;
+            // Only reachable now for malformed base64 (atob throws). Strip the
+            // Q-encoding's underscore-for-space at least, so the fallback isn't
+            // more wrong than it has to be.
+            return encoding.toUpperCase() === "Q" ? text.replace(/_/g, " ") : text;
         }
     });
+    // A BOM inside the encoded-word (`=EF=BB=BF…`) is an encoding marker the
+    // sender leaked into the text, not content — invisible, but it still sorts,
+    // searches and truncates as a character. Drop it.
+    return decodedWords.replace(/\uFEFF/g, ""); // U+FEFF
 }
 /** Tokenize a parenthesized IMAP list (top-level only) */
 function tokenizeParenList(s) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/iflow-direct",
-  "version": "0.1.63",
+  "version": "0.1.65",
   "description": "Direct IMAP client — transport-agnostic, no Node.js dependencies, browser-ready",
   "main": "index.js",
   "types": "index.ts",
@@ -8,7 +8,8 @@
   "scripts": {
     "build": "tsc",
     "watch": "tsc -watch",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "test": "node test/encoded-word.test.mjs"
   },
   "keywords": [
     "imap",

package/test/encoded-word.test.mjs

@@ -0,0 +1,51 @@
+// RFC 2047 encoded-word decoding, exercised through parseEnvelope — an
+// ENVELOPE response is what a client actually stores subjects from.
+//
+// Regression origin (Bob 2026-08-02): a mailman sender labelled its charset
+// `en_US.UTF-8` — a POSIX locale, not a charset. TextDecoder rejected the
+// label, the catch returned the RAW encoded text, and the subject line read
+// `A London_Startup_Is_Selling_Permanent=2C_Painless=2C_=22Stick-On=22…`.
+//
+// Run: node test/encoded-word.test.mjs
+import { parseEnvelope } from "../imap-protocol.js";
+
+// IMAP quoting: only " and \ are escaped. JSON.stringify would ALSO escape the
+// tab a folded header carries, and unquote() would then hand the decoder a
+// literal "t" — the fixture has to look like what the wire really delivers.
+const imapQuote = (s) => `"${s.replace(/([\\"])/g, "\\$1")}"`;
+const env = (subject) =>
+    `("Sat, 1 Aug 2026 22:32:00 -0400" ${imapQuote(subject)} ` +
+    `(("Lauren Weinstein" NIL "lauren" "vortex.com")) NIL NIL ` +
+    `(("NNSquad" NIL "nnsquad" "vortex.com")) NIL NIL NIL "<x@y>")`;
+
+const cases = [
+    // The reported one: POSIX locale as charset, three adjacent encoded-words.
+    ["en_US.UTF-8 locale, adjacent words",
+     "[ NNSquad ] What could go wrong? - A =?en_US.UTF-8?Q?L?= =?en_US.UTF-8?Q?ondon_Startup_Is_Selling_Permanent=2C_Painless=2C_=22Stic?= =?en_US.UTF-8?Q?k-On=22_Tattoos=E2=80=94and?= It Wants to Do Mail Order",
+     "[ NNSquad ] What could go wrong? - A London Startup Is Selling Permanent, Painless, \"Stick-On\" Tattoos—and It Wants to Do Mail Order"],
+    ["plain utf-8 Q", "=?utf-8?Q?caf=C3=A9_r=C3=A9sum=C3=A9?=", "café résumé"],
+    ["utf8 (no hyphen)", "=?utf8?Q?na=C3=AFve?=", "naïve"],
+    ["RFC 2231 language suffix", "=?utf-8*en?Q?hello_world?=", "hello world"],
+    ["iso-8859-1 B", "=?iso-8859-1?B?SmVhbi1S6Q==?=", "Jean-Ré"],
+    ["windows-1252 Q", "=?windows-1252?Q?=93quoted=94?=", "“quoted”"],
+    // Dotted label that is a REAL charset — the locale rule must not mangle it.
+    ["dotted real charset (ansi_x3.4-1968)", "=?ansi_x3.4-1968?Q?plain_ascii?=", "plain ascii"],
+    ["koi8-r B", "=?koi8-r?B?89DBzQ==?=", "Спам"],
+    // Fold INSIDE an encoded-word: the closing ?= sits on the next line, and
+    // the transport's literal handler drops the newline but keeps the leading
+    // whitespace — so the decoder sees "…Shipped\t?=". Also checks the BOM the
+    // sender encoded into the text is not left in the subject.
+    ["terminator folded onto next line", "=?utf-8?Q?=EF=BB=BFYour_Order_has_Shipped\t?=", "Your Order has Shipped"],
+    ["second word terminator folded", "=?UTF-8?Q?=EF=BB=BFThanks!_We_got_your_order_16536?=\t=?UTF-8?Q?3791 ?=", "Thanks! We got your order 165363791"],
+    ["no encoded words", "just a plain subject", "just a plain subject"],
+];
+
+let fail = 0;
+for (const [name, raw, want] of cases) {
+    const got = parseEnvelope(env(raw)).subject;
+    const ok = got === want;
+    if (!ok) fail++;
+    console.log(`${ok ? "✓" : "✗"} ${name}${ok ? "" : `\n    got  ${JSON.stringify(got)}\n    want ${JSON.stringify(want)}`}`);
+}
+console.log(fail ? `\n${fail} FAILED` : `\nall ${cases.length} passed`);
+process.exit(fail ? 1 : 0);