fix(gmail): exclude address comments from mailbox extraction

packages/integrations/src/google.ts

@@ -193,10 +193,35 @@ function decodeSnippet(value: string): string {
   );
 }
 function addresses(value: string): string[] {
+  // Comments may contain addresses, nested comments and escaped parentheses.
+  // Quoted display names treat parentheses literally instead.
+  let uncommented = "";
+  let depth = 0;
+  let quoted = false;
+  let escaped = false;
+  // Encoded words are display text, never mailbox syntax, even if their raw
+  // payload happens to contain an address or parentheses.
+  for (const character of value.replace(/=\?[^?]+\?[bq]\?[^?]*\?=/gi, "")) {
+    if (escaped) {
+      if (!depth) uncommented += character;
+      escaped = false;
+    } else if (character === "\\") {
+      if (!depth) uncommented += character;
+      escaped = true;
+    } else if (!depth && character === '"') {
+      quoted = !quoted;
+      uncommented += character;
+    } else if (!quoted && character === "(") {
+      if (!depth) uncommented += " ";
+      depth++;
+    } else if (depth && character === ")") {
+      depth--;
+    } else if (!depth) uncommented += character;
+  }
   // A quoted display name may itself contain an e-mail-looking string; only
   // addresses outside display names count.
   return (
-    value
+    uncommented
       .replace(/"(?:[^"\\]|\\.)*"\s*(?=<)/g, " ")
       .match(/[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9.-]+/g) ?? []
   );
@@ -340,8 +365,9 @@ function mapMessage(message: z.infer<typeof messageSchema>): Mail {
     if (!attached) for (const child of part.parts ?? []) visit(child, depth + 1);
   };
   if (message.payload) visit(message.payload, 0);
-  const from = decodeHeader(metadata.get("from") ?? "");
-  const address = addresses(from)[0] ?? from;
+  const rawFrom = metadata.get("from") ?? "";
+  const from = decodeHeader(rawFrom);
+  const address = addresses(rawFrom)[0] ?? from;
   const displayName = from.includes("<")
     ? from.slice(0, from.indexOf("<")).trim().replace(/^"|"$/g, "")
     : "";

tests/google.test.ts

@@ -37,6 +37,88 @@ const eventResponse = {
 };
 const base64url = (text: string) => Buffer.from(text).toString("base64url");
 
+test("mail addresses exclude comments, including nested and escaped parentheses", async () => {
+  for (const comment of [
+    "(old@example.com)",
+    "(old@example.com (another@example.com))",
+    "(legacy \\) old@example.com)",
+  ]) {
+    const client = clientWith(() =>
+      json({
+        id: "thread1",
+        messages: [
+          {
+            id: "msg1",
+            threadId: "thread1",
+            payload: {
+              headers: [
+                { name: "From", value: `Support ${comment} <sender@example.com>` },
+                {
+                  name: "To",
+                  value: `${comment} <reader@example.com>, second@example.com ${comment}`,
+                },
+              ],
+            },
+          },
+        ],
+      }),
+    );
+    const [mail] = await client.getThread("thread1");
+    assert.equal(mail.from, "sender@example.com", comment);
+    assert.deepEqual(mail.to, ["reader@example.com", "second@example.com"], comment);
+  }
+});
+
+test("parentheses inside a quoted display name do not start address comments", async () => {
+  const client = clientWith(() =>
+    json({
+      id: "thread1",
+      messages: [
+        {
+          id: "msg1",
+          threadId: "thread1",
+          payload: {
+            headers: [
+              { name: "From", value: '"Support (West" <sender@example.com>' },
+              { name: "To", value: '"Help \\"desk (west@example.com)" <reader@example.com>' },
+            ],
+          },
+        },
+      ],
+    }),
+  );
+  const [mail] = await client.getThread("thread1");
+  assert.equal(mail.from, "sender@example.com");
+  assert.deepEqual(mail.to, ["reader@example.com"]);
+});
+
+test("encoded display-name punctuation does not become address syntax", async () => {
+  for (const name of ["Support (West", "Support ) West", "old@example.com (West)"]) {
+    const encoded = `=?UTF-8?B?${Buffer.from(name).toString("base64")}?=`;
+    const client = clientWith(() =>
+      json({
+        id: "thread1",
+        messages: [
+          {
+            id: "msg1",
+            threadId: "thread1",
+            payload: {
+              headers: [
+                { name: "From", value: `${encoded} <sender@example.com>` },
+                { name: "To", value: "=?UTF-8?Q?old@example.com_=28West?= <reader@example.com>" },
+              ],
+            },
+          },
+        ],
+      }),
+    );
+    const [mail] = await client.getThread("thread1");
+    assert.equal(mail.from, "sender@example.com", name);
+    assert.equal(mail.sender, name);
+    assert.deepEqual(mail.to, ["reader@example.com"]);
+  }
+});
+
 test("mail reads nested plain text and attachment references over authenticated Gmail paths", async () => {
   const paths: URL[] = [];
   const client = clientWith((request) => {