body.test.ts

packages/gmail-client/test/body.test.ts

1. /**
2. * Reading a message body.
3. *
4. * The risks of reading full bodies, and what is tested here: sender-controlled markup reaching the page, a body that
5. * decodes to mojibake, and a walk that returns an attachment instead of the
6. * message.
7. */
9. import { describe, expect, it } from 'vitest'
10. import { SA } from './sa.js'
11. import {
12. ATTACHMENT_DOWNLOAD_CAP,
13. collectAttachments,
14. decodeB64Url,
15. decodeB64UrlBytes,
16. extractBody,
17. fetchAttachment,
18. fetchBody,
19. htmlToText,
20. splitAddressList,
21. } from '../src/index.js'
23. const b64 = (s: string) =>
24. btoa(String.fromCharCode(...new TextEncoder().encode(s))).replace(/\+/g, '-').replace(/\//g, '_')
26. describe('decodeB64Url', () => {
27. it('accepts Gmail’s URL-safe alphabet, which atob alone rejects', () => {
28. expect(decodeB64Url(b64('a?b>c'))).toBe('a?b>c')
29. })
31. it('decodes UTF-8 rather than latin-1', () => {
32. // atob gives bytes. Skipping the TextDecoder turns "café – €5" into mojibake
33. // in every message a European vendor sends.
34. expect(decodeB64Url(b64('café – €5 ✅'))).toBe('café – €5 ✅')
35. })
37. it('tolerates missing padding', () => {
38. expect(decodeB64Url(b64('abc').replace(/=+$/, ''))).toBe('abc')
39. })
40. })
42. describe('decodeB64UrlBytes', () => {
43. it('returns the bytes, including the ones no text codec survives', () => {
44. // 0xFD 0xFE 0xFF is invalid UTF-8. Through decodeB64Url each becomes
45. // U+FFFD, which is a PDF the recipient cannot open, which is the whole reason
46. // there are two decoders.
47. const bytes = new Uint8Array([0, 1, 2, 253, 254, 255])
48. let bin = ''
49. for (const b of bytes) bin += String.fromCharCode(b)
50. const b64url = btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
51. expect([...decodeB64UrlBytes(b64url)]).toEqual([...bytes])
52. })
53. })
55. describe('collectAttachments', () => {
56. const part = (over: Record<string, unknown> = {}) => ({
57. mimeType: 'application/pdf',
58. filename: 'flyer.pdf',
59. body: { attachmentId: 'a1', size: 2048 },
60. ...over,
61. })
63. it('returns nothing for a message with no filenamed parts', () => {
64. expect(collectAttachments({ mimeType: 'text/plain', body: { data: 'x' } })).toEqual([])
65. })
67. it('indexes in walk order, which is what the download route addresses', () => {
68. const got = collectAttachments({
69. mimeType: 'multipart/mixed',
70. parts: [part(), part({ filename: 'b.pdf' }), { mimeType: 'text/plain', body: { data: 'x' } }],
71. })
72. expect(got.map((a) => [a.index, a.name])).toEqual([
73. [0, 'flyer.pdf'],
74. [1, 'b.pdf'],
75. ])
76. })
78. it('reports an unmeasured size as null and never as 0', () => {
79. const got = collectAttachments({ parts: [part({ body: { attachmentId: 'a1' } })] })
80. expect(got[0]!.size).toBeNull()
81. // A part Gmail says is genuinely empty is a real zero and stays one.
82. const empty = collectAttachments({ parts: [part({ body: { attachmentId: 'a1', size: 0 } })] })
83. expect(empty[0]!.size).toBe(0)
84. })
86. it('marks an inline image inline, by the same signals a mail client uses', () => {
87. // A multi-party client thread can carry four of these: signature logos.
88. // Counted as attachments they read as "4 attachments" on a message with none.
89. const byDisposition = collectAttachments({
90. parts: [
91. part({
92. filename: 'image001.jpg',
93. mimeType: 'image/jpeg',
94. headers: [{ name: 'Content-Disposition', value: 'inline; filename="image001.jpg"' }],
95. }),
96. ],
97. })
98. expect(byDisposition[0]!.inline).toBe(true)
100. const byCid = collectAttachments({
101. parts: [part({ filename: 'logo.png', headers: [{ name: 'Content-ID', value: '<logo>' }] })],
102. })
103. expect(byCid[0]!.inline).toBe(true)
104. })
106. it('does not call an attached file inline just because it has a disposition', () => {
107. const got = collectAttachments({
108. parts: [part({ headers: [{ name: 'Content-Disposition', value: 'attachment; filename="flyer.pdf"' }] })],
109. })
110. expect(got[0]!.inline).toBe(false)
111. })
113. it('records a part with no attachmentId as having none, rather than skipping it', () => {
114. // Rule 9: a file that cannot be fetched is still a file that is there, and
115. // the page says why there is no link.
116. const got = collectAttachments({ parts: [part({ body: { size: 10 } })] })
117. expect(got[0]!.attachmentId).toBeNull()
118. })
119. })
121. describe('splitAddressList', () => {
122. it('does not split inside a quoted display name', () => {
123. // The client-thread case: `"Ortiz, Lena" <Lena.Ortiz@lakeside-expo.example>`.
124. // A split on ',' makes that two entries, one of which is an address that
125. // would be sent to.
126. expect(splitAddressList('"Ortiz, Lena" <Lena.Ortiz@lakeside-expo.example>, sasha@lakeside-expo.example')).toEqual([
127. '"Ortiz, Lena" <Lena.Ortiz@lakeside-expo.example>',
128. 'sasha@lakeside-expo.example',
129. ])
130. })
132. it('does not split inside angle brackets, and drops empty entries', () => {
133. expect(splitAddressList('a@b.com,, <c@d.com>')).toEqual(['a@b.com', '<c@d.com>'])
134. expect(splitAddressList('')).toEqual([])
135. expect(splitAddressList(' ')).toEqual([])
136. })
137. })
139. describe('htmlToText', () => {
140. it('drops the CONTENTS of style and script, not just their tags', () => {
141. // Stripping tags alone leaves a wall of CSS in the middle of the message,
142. // which is most of a marketing email by volume.
143. const out = htmlToText('<style>.a{color:red}</style><p>Hello</p><script>alert(1)</script>')
144. expect(out).toBe('Hello')
145. })
147. it('strips the zero-width filler marketing uses to pad preview text', () => {
148. // Every promotional snippet in the live inbox is "͏ ͏ ͏ ͏" for hundreds of
149. // characters. Left in, the message reads as a screen of blank lines.
150. const padded = 'Real text' + '‌­​'.repeat(200)
151. expect(htmlToText(padded)).toBe('Real text')
152. })
154. it('turns block ends into line breaks so paragraphs survive', () => {
155. expect(htmlToText('<p>one</p><p>two</p>')).toBe('one\ntwo')
156. })
158. it('unescapes entities', () => {
159. expect(htmlToText('<p>Tom &amp; Jerry &lt;3 &quot;x&quot;</p>')).toBe('Tom & Jerry <3 "x"')
160. })
162. it('leaves no markup behind for the page to interpret', () => {
163. const out = htmlToText('<img src=x onerror="alert(1)"><b>hi</b>')
164. expect(out).not.toContain('<')
165. expect(out).not.toContain('onerror')
166. })
167. })
169. describe('extractBody', () => {
170. const part = (mimeType: string, text: string, extra: Record<string, unknown> = {}) => ({
171. mimeType,
172. body: { data: b64(text) },
173. ...extra,
174. })
176. it('prefers text/plain over the HTML alternative', () => {
177. const out = extractBody({
178. mimeType: 'multipart/alternative',
179. parts: [part('text/plain', 'plain version'), part('text/html', '<p>html version</p>')],
180. })
181. // The raw HTML rides along even when plain wins the text field; the frame
182. // route renders it.
183. expect(out).toEqual({ text: 'plain version', kind: 'plain', html: '<p>html version</p>' })
184. })
186. it('falls back to HTML converted to text', () => {
187. const out = extractBody({ mimeType: 'multipart/alternative', parts: [part('text/html', '<p>only html</p>')] })
188. expect(out).toEqual({ text: 'only html', kind: 'html', html: '<p>only html</p>' })
189. })
191. it('digs through nested multiparts', () => {
192. const out = extractBody({
193. mimeType: 'multipart/mixed',
194. parts: [
195. { mimeType: 'multipart/alternative', parts: [part('text/plain', 'buried')] },
196. part('application/pdf', 'not text', { filename: 'invoice.pdf' }),
197. ],
198. })
199. expect(out.text).toBe('buried')
200. })
202. it('never returns an attachment as the body', () => {
203. const out = extractBody({
204. mimeType: 'multipart/mixed',
205. parts: [part('text/plain', 'attached note', { filename: 'note.txt' })],
206. })
207. expect(out).toEqual({ text: '', kind: 'none', html: '' })
208. })
210. it('reports an image-only message as having no text, not as blank', () => {
211. expect(extractBody({ mimeType: 'multipart/mixed', parts: [part('image/png', 'x')] }).kind).toBe('none')
212. })
213. })
215. describe('fetchBody', () => {
216. const CREDS = SA
217. const json = (b: unknown, status = 200) =>
218. new Response(JSON.stringify(b), { status, headers: { 'content-type': 'application/json' } })
220. const message = {
221. id: 'm1',
222. internalDate: '1788210063000',
223. payload: {
224. mimeType: 'multipart/mixed',
225. headers: [
226. { name: 'From', value: 'Upscaler Labs <news@upscaler.vendor.example>' },
227. { name: 'Subject', value: 'What is new this month' },
228. { name: 'To', value: 'hello@meridiandisplay.example' },
229. ],
230. parts: [
231. { mimeType: 'text/plain', body: { data: b64('Body text here.') } },
232. { mimeType: 'application/pdf', filename: 'flyer.pdf', body: { attachmentId: 'a1' } },
233. ],
234. },
235. }
237. const ok = (async (url: string | URL) =>
238. String(url).includes('oauth2') ? json({ access_token: 't', expires_in: 3599 }) : json(message)) as typeof fetch
240. it('asks for the full message, unlike the list', async () => {
241. const seen: string[] = []
242. const f = (async (url: string | URL) => {
243. seen.push(String(url))
244. return String(url).includes('oauth2') ? json({ access_token: 't', expires_in: 3599 }) : json(message)
245. }) as unknown as typeof fetch
246. await fetchBody('hello@meridiandisplay.example', 'm1', CREDS, f)
247. expect(seen.find((u) => u.includes('/messages/m1'))).toContain('format=full')
248. })
250. it('returns the text, the headers, and each attachment with its handle', async () => {
251. const r = await fetchBody('hello@meridiandisplay.example', 'm1', CREDS, ok)
252. expect('error' in r).toBe(false)
253. if ('error' in r) return
254. expect(r.text).toBe('Body text here.')
255. expect(r.sender).toBe('news@upscaler.vendor.example')
256. expect(r.to).toBe('hello@meridiandisplay.example')
257. // Attachments carry an id and a size, not just a name: a name cannot be
258. // fetched with and cannot be size-checked before fetching.
259. expect(r.attachments).toEqual([
260. {
261. index: 0,
262. name: 'flyer.pdf',
263. mimeType: 'application/pdf',
264. // The fixture part carries no `size`, so it is null and NOT 0; the
265. // page prints "size not reported" rather than claiming an empty file.
266. size: null,
267. attachmentId: 'a1',
268. inline: false,
269. },
270. ])
271. })
273. it('carries html:null for a plain-only message, and Gmail unread state', async () => {
274. const r = await fetchBody('hello@meridiandisplay.example', 'm1', CREDS, ok)
275. if ('error' in r) throw new Error('expected a body')
276. // No HTML part → null, not ''; the page decides frame-vs-text from this.
277. expect(r.html).toBeNull()
278. expect(r.htmlTruncated).toBe(false)
279. expect(r.unread).toBe(false) // no labelIds in the fixture message
280. })
282. it('keeps the raw HTML for the frame route, capped and labelled when cut', async () => {
283. // The spread in b64() blows the stack past ~100k chars; chunk it here.
284. const bigRaw = '<p>' + 'x'.repeat(500_000) + '</p>'
285. const bytes = new TextEncoder().encode(bigRaw)
286. let bin = ''
287. for (let i = 0; i < bytes.length; i += 8192) bin += String.fromCharCode(...bytes.subarray(i, i + 8192))
288. const bigB64 = btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
289. const htmlMsg = {
290. id: 'm2',
291. internalDate: '1788210063000',
292. labelIds: ['UNREAD', 'INBOX'],
293. payload: {
294. mimeType: 'multipart/alternative',
295. headers: [{ name: 'From', value: 'a@b.com' }],
296. parts: [{ mimeType: 'text/html', body: { data: bigB64 } }],
297. },
298. }
299. const f = (async (url: string | URL) =>
300. String(url).includes('oauth2') ? json({ access_token: 't', expires_in: 3599 }) : json(htmlMsg)) as typeof fetch
301. const r = await fetchBody('hello@meridiandisplay.example', 'm2', CREDS, f)
302. if ('error' in r) throw new Error('expected a body')
303. expect(r.html).toHaveLength(400_000)
304. // Truncated-and-labelled beats absent (rule 5), and the page says so.
305. expect(r.htmlTruncated).toBe(true)
306. expect(r.unread).toBe(true)
307. })
309. it('reports a failure rather than an empty message', async () => {
310. // A body we could not fetch and a body that is genuinely blank are different
311. // facts and must not render the same.
312. const f = (async (url: string | URL) =>
313. String(url).includes('oauth2') ? json({ access_token: 't', expires_in: 3599 }) : json({}, 404)) as typeof fetch
314. const r = await fetchBody('hello@meridiandisplay.example', 'gone', CREDS, f)
315. expect(r).toEqual({ error: 'Gmail returned HTTP 404 for that message.' })
316. })
318. it('surfaces a dead token with its cause rather than a bare failure', async () => {
319. const f = (async () => json({ error: 'invalid_grant' }, 400)) as unknown as typeof fetch
320. const r = await fetchBody('accounts@meridiandisplay.example', 'm1', CREDS, f)
321. expect('error' in r && r.error).toMatch(/invalid_grant/)
322. })
324. it('caps a runaway body and says it did', async () => {
325. const huge = { ...message, payload: { ...message.payload, parts: [{ mimeType: 'text/plain', body: { data: b64('x'.repeat(50_000)) } }] } }
326. const f = (async (url: string | URL) =>
327. String(url).includes('oauth2') ? json({ access_token: 't', expires_in: 3599 }) : json(huge)) as typeof fetch
328. const r = await fetchBody('hello@meridiandisplay.example', 'm1', CREDS, f)
329. if ('error' in r) throw new Error('unexpected')
330. expect(r.truncated).toBe(true)
331. expect(r.text.length).toBe(20_000)
332. })
333. })
335. /**
336. * The reply addressing fields.
337. *
338. * These are read here, on the server, because they are the only source of a
339. * reply's recipient, subject and thread; the compose form carries none of
340. * them. A form field a person can edit is a form field a request can set, and
341. * this board's one irreversible action must not take its recipient from the
342. * request that triggers it.
343. */
344. describe('fetchBody carries the threading headers', () => {
345. const json = (b: unknown, status = 200) =>
346. new Response(JSON.stringify(b), { status, headers: { 'content-type': 'application/json' } })
348. const message = (headers: { name: string; value: string }[], threadId?: string) => ({
349. id: 'm1',
350. ...(threadId === undefined ? {} : { threadId }),
351. internalDate: '1788210063000',
352. payload: {
353. mimeType: 'text/plain',
354. headers: [{ name: 'From', value: 'Client <client@example.com>' }, ...headers],
355. body: { data: b64('hi') },
356. },
357. })
359. const fetchOf = (m: unknown) =>
360. (async (url: string | URL) =>
361. String(url).includes('oauth2') ? json({ access_token: 't', expires_in: 3599 }) : json(m)) as unknown as typeof fetch
363. it('reads Message-ID, References, Reply-To, Cc and the thread id', async () => {
364. const body = await fetchBody(
365. 'hello@meridiandisplay.example',
366. 'm1',
367. SA,
368. fetchOf(
369. message(
370. [
371. { name: 'Message-ID', value: '<abc@mail.example.com>' },
372. { name: 'References', value: '<r1@x> <r2@x>' },
373. { name: 'Reply-To', value: 'Billing <billing@example.com>' },
374. { name: 'Cc', value: 'someone@example.com' },
375. ],
376. 't-99',
377. ),
378. ),
379. )
380. if ('error' in body) throw new Error(body.error)
381. expect(body.messageId).toBe('<abc@mail.example.com>')
382. expect(body.references).toBe('<r1@x> <r2@x>')
383. expect(body.replyTo).toBe('Billing <billing@example.com>')
384. expect(body.cc).toBe('someone@example.com')
385. expect(body.threadId).toBe('t-99')
386. })
388. it('reports an absent header as null or empty string, never undefined', async () => {
389. // The caller branches on these. `undefined` reads as a bug in the code
390. // rather than as "the sender did not send one", and the two need very
391. // different responses.
392. const body = await fetchBody('hello@meridiandisplay.example', 'm1', SA, fetchOf(message([])))
393. if ('error' in body) throw new Error(body.error)
394. expect(body.messageId).toBeNull()
395. expect(body.references).toBeNull()
396. expect(body.replyTo).toBe('')
397. expect(body.cc).toBe('')
398. expect(body.threadId).toBe('')
399. })
400. })
402. describe('fetchAttachment', () => {
403. const json = (b: unknown, status = 200) =>
404. new Response(JSON.stringify(b), { status, headers: { 'content-type': 'application/json' } })
406. /** Token call, then the attachment call. Nothing touches the network. */
407. const fetchOf = (res: Response, seen: string[] = []) =>
408. (async (url: string | URL) => {
409. const u = String(url)
410. seen.push(u)
411. return u.includes('oauth2') ? json({ access_token: 't', expires_in: 3599 }) : res
412. }) as unknown as typeof fetch
414. const b64urlBytes = (bytes: number[]) => {
415. let bin = ''
416. for (const b of bytes) bin += String.fromCharCode(b)
417. return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
418. }
420. it('asks the attachments endpoint for that message and hands back the bytes', async () => {
421. const seen: string[] = []
422. const got = await fetchAttachment(
423. 'hello@meridiandisplay.example',
424. 'm1',
425. 'att-1',
426. SA,
427. fetchOf(json({ size: 6, data: b64urlBytes([0, 1, 2, 253, 254, 255]) }), seen),
428. )
429. expect(seen.some((u) => u.includes('/messages/m1/attachments/att-1'))).toBe(true)
430. if ('error' in got) throw new Error(got.error)
431. expect([...got.bytes]).toEqual([0, 1, 2, 253, 254, 255])
432. })
434. it('reports an HTTP failure rather than returning empty bytes', async () => {
435. // The prime invariant on a download: a failed fetch and a zero-byte file
436. // must not arrive at the caller looking the same.
437. const got = await fetchAttachment('hello@meridiandisplay.example', 'm1', 'a', SA, fetchOf(json({}, 404)))
438. expect('error' in got && got.error).toContain('404')
439. })
441. it('reports a 200 with no data as a failure', async () => {
442. const got = await fetchAttachment('hello@meridiandisplay.example', 'm1', 'a', SA, fetchOf(json({ size: 10 })))
443. expect('error' in got && got.error).toContain('no data')
444. })
446. it('refuses bytes over the ceiling even when the part under-declared its size', async () => {
447. // The route checks the DECLARED size before calling; this checks what
448. // actually arrived, so a message that lies about a part cannot walk past
449. // the memory ceiling unnoticed.
450. const big = b64urlBytes(Array.from({ length: ATTACHMENT_DOWNLOAD_CAP + 16 }, () => 65))
451. const got = await fetchAttachment('hello@meridiandisplay.example', 'm1', 'a', SA, fetchOf(json({ data: big })))
452. expect('error' in got && got.error).toContain('ceiling')
453. })
455. it('never throws; a token failure comes back as a result', async () => {
456. const boom = (async () => {
457. throw new Error('network is down')
458. }) as unknown as typeof fetch
459. const got = await fetchAttachment('hello@meridiandisplay.example', 'm1', 'a', SA, boom)
460. expect('error' in got && got.error).toContain('network is down')
461. })
462. })