send.test.ts

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

1. /**
2. * Sending a reply: the only outbound write this board makes.
3. *
4. * Nothing here touches the network: every test injects a fake fetch. The first
5. * real send is made by hand; a build that could send a real email as a side
6. * effect of a test run is not a build anyone should trust with a client's inbox.
7. *
8. * What is worth testing is not "does it POST"; it is the handful of things
9. * that would produce a technically-successful send that is wrong: a subject
10. * that stacks "Re: Re: Re:", a thread id sent to the wrong mailbox, an accented
11. * body that arrives as mojibake, and a failure that names one cause instead of
12. * listing the candidates.
13. */
15. import { describe, expect, it } from 'vitest'
16. import {
17. buildRawMessage,
18. encodeHeaderWord,
19. mimeParam,
20. rawToB64Url,
21. replySubject,
22. safeMimeType,
23. sendMessage,
24. textToHtml,
25. type OutgoingMessage,
26. } from '../src/index.js'
28. const CRED = { clientId: 'id', clientSecret: 'sec', refreshToken: 'rt' }
30. const json = (body: unknown, status = 200) =>
31. new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } })
33. /** Token call first, then the send call. Both faked. */
34. const fakeFetch = (sendResponse: Response, calls: { url: string; body: string }[] = []) =>
35. (async (url: string | URL | Request, init?: RequestInit) => {
36. const u = String(url)
37. calls.push({ url: u, body: String(init?.body ?? '') })
38. if (u.includes('oauth2.googleapis.com/token')) {
39. return json({ access_token: 'tok', expires_in: 3599, scope: 'https://www.googleapis.com/auth/gmail.send' })
40. }
41. return sendResponse
42. }) as unknown as typeof fetch
44. const reply = (over: Partial<OutgoingMessage> = {}): OutgoingMessage => ({
45. from: 'hello@meridiandisplay.example',
46. to: 'client@example.com',
47. cc: null,
48. subject: 'Re: Banner proof',
49. text: 'Proof attached in Gmail.',
50. signatureHtml: null,
51. inReplyTo: '<abc@mail.example.com>',
52. references: '<abc@mail.example.com>',
53. threadId: null,
54. attachments: [],
55. ...over,
56. })
58. /** A file part, with bytes that are not text so a text path would corrupt it. */
59. const bin = (name = 'proof.pdf', bytes = new Uint8Array([0, 1, 2, 253, 254, 255])) => ({
60. name,
61. mimeType: 'application/pdf',
62. bytes,
63. })
65. /**
66. * Is there a header line of this name anywhere in the message?
67. *
68. * A line test, not a substring test. `Cc: a@b.com Bcc: v@x.com` contains the
69. * text "Bcc:" and is harmless; the injection is what makes it a header, which
70. * means starting a line. An `expect(raw).not.toContain('Bcc:')` passes only
71. * until someone folds a value, and then it fails on a message that is fine.
72. */
73. const hasHeader = (raw: string, name: string): boolean =>
74. raw.split('\r\n').some((l) => new RegExp(`^${name}:`, 'i').test(l))
76. /** The named boundary's parts, headers and raw body kept separate. */
77. const sections = (raw: string, boundary: string): { head: string; body: string }[] =>
78. raw
79. .split(`--${boundary}`)
80. .slice(1, -1)
81. .map((p) => {
82. const i = p.indexOf('\r\n\r\n')
83. return { head: p.slice(0, i), body: p.slice(i + 4) }
84. })
86. const boundaryOf = (raw: string, type: string): string =>
87. new RegExp(`Content-Type: ${type}; boundary="([^"]+)"`).exec(raw)![1]!
89. /** Pull one base64 body part out of the raw message and decode it. */
90. const parts = (raw: string): string[] => {
91. const m = /boundary="([^"]+)"/.exec(raw)
92. if (!m) return []
93. return raw
94. .split(`--${m[1]!}`)
95. .slice(1, -1)
96. .map((p) => {
97. const b64 = p.split('\r\n\r\n').slice(1).join('\r\n\r\n').trim().replace(/\r\n/g, '')
98. return new TextDecoder().decode(Uint8Array.from(atob(b64), (c) => c.charCodeAt(0)))
99. })
100. }
102. describe('replySubject', () => {
103. it('adds Re: once', () => {
104. expect(replySubject('Banner proof')).toBe('Re: Banner proof')
105. })
107. it('is idempotent, whatever the case or spacing', () => {
108. // Three replies deep, a naive prefix gives "Re: Re: Re: Banner proof" and
109. // the client sees the board talking to itself.
110. for (const s of ['Re: Banner proof', 'RE: Banner proof', 're:Banner proof', ' Re : x']) {
111. expect(replySubject(s)).toBe(replySubject(replySubject(s)))
112. }
113. expect(replySubject('Re: Banner proof')).toBe('Re: Banner proof')
114. })
116. it('names an empty subject rather than sending a bare "Re:"', () => {
117. expect(replySubject(' ')).toBe('Re: (no subject)')
118. })
119. })
121. describe('encodeHeaderWord', () => {
122. it('leaves printable ASCII alone', () => {
123. // Encoding everything would make every subject unreadable in the raw source
124. // for no gain.
125. expect(encodeHeaderWord('Banner proof #4')).toBe('Banner proof #4')
126. })
128. it('RFC 2047-encodes anything that is not', () => {
129. for (const s of ['Café résumé', 'Año nuevo 🎉', '设计稿']) {
130. const out = encodeHeaderWord(s)
131. expect(out).toMatch(/^=\?UTF-8\?B\?[A-Za-z0-9+/=]+\?=$/)
132. const b64 = out.slice('=?UTF-8?B?'.length, -2)
133. expect(new TextDecoder().decode(Uint8Array.from(atob(b64), (c) => c.charCodeAt(0)))).toBe(s)
134. }
135. })
137. it('cannot carry a newline into the header block', () => {
138. // Header injection: a CR or LF in a value turns one header into two, and
139. // the value that reaches here came off a message a stranger sent us.
140. const out = encodeHeaderWord('Subject\r\nBcc: attacker@example.com')
141. expect(out).not.toContain('\r')
142. expect(out).not.toContain('\n')
143. })
144. })
146. describe('buildRawMessage', () => {
147. it('carries In-Reply-To and References when given, and omits them when null', () => {
148. expect(buildRawMessage(reply())).toContain('In-Reply-To: <abc@mail.example.com>')
149. const bare = buildRawMessage(reply({ inReplyTo: null, references: null }))
150. expect(bare).not.toContain('In-Reply-To:')
151. expect(bare).not.toContain('References:')
152. })
154. it('is multipart/alternative with both a text and an HTML part', () => {
155. const raw = buildRawMessage(reply())
156. expect(raw).toContain('Content-Type: multipart/alternative; boundary="')
157. expect(raw).toContain('Content-Type: text/plain; charset=UTF-8')
158. expect(raw).toContain('Content-Type: text/html; charset=UTF-8')
159. expect(parts(raw)).toHaveLength(2)
160. })
162. it('round-trips a non-ASCII body byte for byte', () => {
163. // The whole reason both encoders go through TextEncoder: btoa on a string
164. // containing 'é' throws, and a "fix" that drops to latin-1 silently sends
165. // mojibake to the client instead.
166. const text = 'Hola Begoña, el diseño está listo 🎉 设计稿'
167. const raw = buildRawMessage(reply({ text }))
168. expect(parts(raw)[0]).toBe(text)
169. const back = new TextDecoder().decode(
170. Uint8Array.from(atob(rawToB64Url(raw).replace(/-/g, '+').replace(/_/g, '/') + '=='.slice(0, (4 - (rawToB64Url(raw).length % 4)) % 4)), (c) => c.charCodeAt(0)),
171. )
172. expect(back).toBe(raw)
173. })
175. it('puts the signature in BOTH parts when given, and neither when not', () => {
176. const sig = '<p><b>Meridian Display</b> · Northside office</p>'
177. const withSig = buildRawMessage(reply({ signatureHtml: sig }))
178. const [plain, html] = parts(withSig)
179. expect(html).toContain(sig)
180. // The plain part gets the same signature as text, from the same converter
181. // the reader sees, not a second rendering to keep in step by hand.
182. expect(plain).toContain('Meridian Display')
183. expect(plain).toContain('\r\n-- \r\n')
185. const [p2, h2] = parts(buildRawMessage(reply()))
186. expect(p2).not.toContain('--')
187. expect(h2).not.toContain('Meridian Display')
188. })
190. it('uses CRLF throughout, which is what RFC 2822 requires', () => {
191. const raw = buildRawMessage(reply())
192. expect(raw).toContain('\r\n')
193. expect(raw.replace(/\r\n/g, '')).not.toContain('\n')
194. })
196. it('writes a Cc header only when there is one', () => {
197. expect(buildRawMessage(reply({ cc: 'boss@example.com' }))).toContain('Cc: boss@example.com')
198. // null and '' must both mean "no Cc": an empty Cc header is legal and
199. // reads, in a Sent folder, as a Cc sent to nobody.
200. expect(buildRawMessage(reply({ cc: null }))).not.toContain('Cc:')
201. expect(buildRawMessage(reply({ cc: '' }))).not.toContain('Cc:')
202. })
204. it('cannot be made to inject a header through the Cc', () => {
205. const raw = buildRawMessage(reply({ cc: 'a@b.com\r\nBcc: victim@elsewhere.com' }))
206. // The CRLF is flattened to a space, so the whole thing stays one Cc value
207. // and no Bcc header exists. (The Worker's parseRecipients refuses this
208. // input outright; the encoder is the second line of defence, not the only.)
209. expect(hasHeader(raw, 'Bcc')).toBe(false)
210. expect(raw).toContain('Cc: a@b.com Bcc: victim@elsewhere.com')
211. })
212. })
214. describe('buildRawMessage with attachments', () => {
215. it('is byte-identical to the old shape when there are none', () => {
216. // The reason `mixed` is conditional. A mixed wrapper around a single
217. // alternative part renders the same, but this is the one output nobody can
218. // inspect after the fact, so nothing changes for a message that asked for
219. // no change.
220. const raw = buildRawMessage(reply())
221. expect(raw).toContain('Content-Type: multipart/alternative; boundary="')
222. expect(raw).not.toContain('multipart/mixed')
223. })
225. it('wraps the alternative in a mixed part and adds one part per file', () => {
226. const raw = buildRawMessage(reply({ attachments: [bin(), bin('quote.pdf')] }))
227. const mixed = boundaryOf(raw, 'multipart/mixed')
228. const secs = sections(raw, mixed)
229. expect(secs).toHaveLength(3)
230. expect(secs[0]!.head).toContain('multipart/alternative')
231. expect(secs[1]!.head).toContain('Content-Disposition: attachment; filename="proof.pdf"')
232. expect(secs[2]!.head).toContain('filename="quote.pdf"')
233. // The text and HTML parts are still both there, nested inside the first.
234. const alt = boundaryOf(raw, 'multipart/alternative')
235. expect(sections(raw, alt)).toHaveLength(2)
236. })
238. it('round-trips the file bytes exactly, including ones no text codec survives', () => {
239. // 0xFD 0xFE 0xFF is not valid UTF-8. Through a text path each becomes
240. // U+FFFD and the recipient gets a file that opens as garbage, which is
241. // why there is a separate bytes encoder at all.
242. const bytes = new Uint8Array([0, 1, 2, 253, 254, 255, 10, 13])
243. const raw = buildRawMessage(reply({ attachments: [bin('x.bin', bytes)] }))
244. const mixed = boundaryOf(raw, 'multipart/mixed')
245. const body = sections(raw, mixed)[1]!.body.trim().replace(/\r\n/g, '')
246. expect([...Uint8Array.from(atob(body), (c) => c.charCodeAt(0))]).toEqual([...bytes])
247. })
249. it('wraps the base64 at 76 columns like every other part', () => {
250. const raw = buildRawMessage(reply({ attachments: [bin('big.bin', new Uint8Array(1000))] }))
251. const mixed = boundaryOf(raw, 'multipart/mixed')
252. const lines = sections(raw, mixed)[1]!.body.trim().split('\r\n')
253. expect(lines.length).toBeGreaterThan(1)
254. expect(Math.max(...lines.map((l) => l.length))).toBeLessThanOrEqual(76)
255. })
257. it('a filename cannot end the parameter or forge a header', () => {
258. // The filename is chosen by whoever picked the file and goes straight into
259. // Content-Disposition. A quote closes the parameter; a CRLF starts a header.
260. const raw = buildRawMessage(reply({ attachments: [bin('a".pdf\r\nBcc: v@x.com')] }))
261. expect(hasHeader(raw, 'Bcc')).toBe(false)
262. expect(raw).toContain('filename="a.pdfBcc: v@x.com"')
263. })
265. it('RFC 2047-encodes a non-ASCII filename rather than mangling it', () => {
266. const raw = buildRawMessage(reply({ attachments: [bin('diseño.pdf')] }))
267. expect(raw).toContain('filename="=?UTF-8?B?')
268. expect(raw).not.toContain('diseño.pdf')
269. })
271. it('refuses to pass through a mime type that is not one', () => {
272. expect(safeMimeType('application/pdf')).toBe('application/pdf')
273. expect(safeMimeType('text/html; charset=utf-8')).toBe('text/html')
274. expect(safeMimeType('nonsense')).toBe('application/octet-stream')
275. expect(safeMimeType('a/b\r\nX: y')).toBe('application/octet-stream')
276. expect(safeMimeType('')).toBe('application/octet-stream')
277. })
279. it('never lets a blank filename produce a nameless part', () => {
280. expect(mimeParam(' ')).toBe('attachment')
281. })
282. })
284. describe('textToHtml', () => {
285. it('escapes markup rather than letting typed text become tags', () => {
286. expect(textToHtml('<b>hi</b> & "x"')).toContain('&lt;b&gt;hi&lt;/b&gt; &amp; &quot;x&quot;')
287. })
289. it('turns newlines into breaks', () => {
290. expect(textToHtml('a\nb')).toContain('a<br>b')
291. })
292. })
294. describe('sendMessage', () => {
295. it('POSTs raw to the send endpoint and reports the ids back', async () => {
296. const calls: { url: string; body: string }[] = []
297. const res = await sendMessage('hello@meridiandisplay.example', CRED, reply(), fakeFetch(json({ id: 'm1', threadId: 't1' }), calls))
298. expect(res).toEqual({ ok: true, id: 'm1', threadId: 't1' })
299. const send = calls.find((c) => c.url.includes('/messages/send'))!
300. expect(send.url).toBe('https://gmail.googleapis.com/gmail/v1/users/me/messages/send')
301. expect(JSON.parse(send.body).raw).toBeTruthy()
302. })
304. it('includes threadId only when one was given', async () => {
305. // Gmail thread ids are PER-MAILBOX. Sending hello@'s id through accounts@'s
306. // token is rejected outright, so decideReply omits it when the sending
307. // mailbox differs, and this pins that the encoder honours the omission.
308. const a: { url: string; body: string }[] = []
309. await sendMessage('hello@meridiandisplay.example', CRED, reply(), fakeFetch(json({ id: 'm', threadId: 't' }), a))
310. expect(JSON.parse(a.find((c) => c.url.includes('send'))!.body).threadId).toBeUndefined()
312. const b: { url: string; body: string }[] = []
313. await sendMessage('hello@meridiandisplay.example', CRED, reply({ threadId: 'thr1' }), fakeFetch(json({ id: 'm', threadId: 'thr1' }), b))
314. expect(JSON.parse(b.find((c) => c.url.includes('send'))!.body).threadId).toBe('thr1')
315. })
317. it('names several candidates for a 403 and picks none of them', async () => {
318. // Rule 1. A 403 here has at least five plausible causes and the
319. // expensive one ("the token is fine, re-mint it" vs "consent screen is in
320. // Testing") is not distinguishable from the response.
321. const res = await sendMessage('hello@meridiandisplay.example', CRED, reply(), fakeFetch(json({ error: { message: 'Request had insufficient authentication scopes.' } }, 403)))
322. expect(res.ok).toBe(false)
323. if (res.ok) throw new Error('unreachable')
324. expect(res.status).toBe(403)
325. expect(res.candidates.length).toBeGreaterThanOrEqual(3)
326. expect(res.error).toContain('403')
327. // No candidate is marked as the likely one.
328. expect(res.candidates.join(' ')).not.toMatch(/most likely|probably/i)
329. })
331. it('never throws on a network failure; it returns the failure', async () => {
332. // Same contract as readMailbox, for a sharper reason: the caller has an
333. // audit row to finish writing, and a thrown error is a send whose outcome
334. // nobody recorded.
335. const f = (async () => {
336. throw new Error('connection reset')
337. }) as unknown as typeof fetch
338. const res = await sendMessage('hello@meridiandisplay.example', CRED, reply(), f)
339. expect(res.ok).toBe(false)
340. if (res.ok) throw new Error('unreachable')
341. expect(res.error).toContain('connection reset')
342. expect(res.status).toBeNull()
343. })
345. it('treats a 200 with no message id as a failure, not a success', async () => {
346. // "sent" beside a message nobody can find in Gmail is worse than an error.
347. const res = await sendMessage('hello@meridiandisplay.example', CRED, reply(), fakeFetch(json({})))
348. expect(res.ok).toBe(false)
349. if (res.ok) throw new Error('unreachable')
350. expect(res.candidates.join(' ')).toMatch(/Sent folder/i)
351. })
353. it('reports a token failure without ever reaching the send endpoint', async () => {
354. const calls: { url: string; body: string }[] = []
355. const f = (async (url: string | URL | Request) => {
356. calls.push({ url: String(url), body: '' })
357. return json({ error: 'invalid_grant' }, 400)
358. }) as unknown as typeof fetch
359. const res = await sendMessage('hello@meridiandisplay.example', CRED, reply(), f)
360. expect(res.ok).toBe(false)
361. expect(calls.some((c) => c.url.includes('/messages/send'))).toBe(false)
362. })
363. })