// Emails (spec/EMAIL.md): what each side sent, and the tokens in them. The // reference's are caught in its process, as its mailer is about to send // them; the server's are read as its adapter reads them (lib/adapters/): // Monolith writes each to PDS_DEV_MAIL_DIR, which the harness reads and // empties, and sends each to the harness's SMTP server (lib/smtp.mjs), // where each is held to what the development sink recorded. import { isDeepStrictEqual } from 'node:util' import { cand, ref } from './processes.mjs' import { differ } from './report.mjs' import { HOSTNAME } from './env.mjs' import { smtp } from './server.mjs' import { addressOf, decodeWords, parseMessage, partsOf } from './smtp.mjs' /// A token's form. export const TOKEN = /^[A-Z2-7]{5}-[A-Z2-7]{5}$/ /// Each kind of email's subject (spec/EMAIL.md, "The mailer"). export const SUBJECT = { confirmEmail: 'Email Confirmation', updateEmail: 'Email Update Requested', resetPassword: 'Password Reset Requested', signInAuthFactor: 'Sign-in Confirmation', deleteAccount: 'Account Deletion Requested', plcOperation: 'PLC Update Operation Requested', } /// Each kind of email's heading in its HTML part (spec/EMAIL.md, "The message"). export const HEADING = { confirmEmail: 'Confirm your email', updateEmail: 'Change your email', resetPassword: 'Reset your password', signInAuthFactor: 'Your sign-in code', deleteAccount: 'Delete your account', plcOperation: 'Confirm a change to your account', } /// An HTML part's text, as a reader sees it: its tags dropped, its /// character references read, its white space run together. const textOfHtml = (html) => html .replace(/<(style|head)[\s\S]*?<\/\1>/gi, ' ') .replace(/<[^>]*>/g, ' ') .replace(/&(#x[0-9a-f]+|#\d+|amp|lt|gt|quot|apos|nbsp);/gi, (_, r) => r[0] === '#' ? String.fromCodePoint(r[1].toLowerCase() === 'x' ? parseInt(r.slice(2), 16) : parseInt(r.slice(1), 10)) : { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' }[r.toLowerCase()]) .replace(/\s+/g, ' ') /// How a message's body is made, as spec/EMAIL.md ("The message") holds it: /// its type and its parts', the token in each, and of its HTML part, /// whether its text names the host and the kind's heading, and the first /// thing in it that would load anything. function made(data, kind, token) { const { type, parts } = partsOf(data) const html = parts.find((p) => p.type === 'text/html')?.text return { type, parts: parts.map((p) => p.type), token: parts.map((p) => p.text.includes(token)), html: html === undefined ? null : { host: textOfHtml(html).includes(HOSTNAME), heading: textOfHtml(html).includes(HEADING[kind]), loads: /\b(?:src|href)\s*=|url\(/i.exec(html)?.[0] ?? null, }, } } const MADE = { type: 'multipart/alternative', parts: ['text/plain', 'text/html'], token: [true, true], html: { host: true, heading: true, loads: null } } /// The reference's emails not yet taken, oldest first. const caught = [] /// Catch every email the reference's `mailer` sends, as `{to, kind, /// token}`: its template's name is the kind. export function catchReferenceMail(mailer) { const send = mailer.sendTemplate.bind(mailer) mailer.sendTemplate = (kind, params, opts) => { caught.push({ to: opts.to, kind, token: params.token }) return send(kind, params, opts) } } /// The emails `side` sent since they were last taken, oldest first, each /// as the server wrote it: `{to, kind, token}` if it is right. For the /// server, what its adapter's `takeMail` answers (a promise, for some); /// what reached the SMTP server it was given, if any, is taken too, and /// let go with them. export function takeMail(side) { if (side.name === ref.name) return caught.splice(0) smtp()?.take() return cand.takeMail() } /// An email as compared: its token's form, not the token. const shape = (m) => (m && typeof m === 'object' && !Array.isArray(m) ? { ...m, ...('token' in m ? { token: typeof m.token === 'string' && TOKEN.test(m.token) ? '' : m.token } : {}) } : m) /// Take the emails both sides sent since they were last taken, and compare /// them: the same addresses and kinds, in order, each `{to, kind, token}` /// and nothing else, with a token of the form spec/EMAIL.md gives /// (spec/EMAIL.md, "Tokens", "The mailer"). Then, with the server sending /// through an SMTP server, hold what reached it to those (`checkSmtp`). /// `what` and `request` say what sent them. Answers `{reference, server}`, /// each side's emails, to use their tokens. export async function checkMail(what, request) { const sent = { reference: takeMail(ref), server: await cand.takeMail() } // After the development sink's: each email is written there before it is sent. const wire = smtp()?.take() const want = { to: '', kind: '', token: '' } for (const side of [ref, cand]) { const bad = sent[side.name].map(shape).find((m) => !m || typeof m !== 'object' || !isDeepStrictEqual(Object.keys(m).sort(), Object.keys(want).sort()) || m.token !== '' || typeof m.to !== 'string' || typeof m.kind !== 'string') if (bad) await differ(`${what}: an email the ${side.name} sent (spec/EMAIL.md)`, request, '{to, kind, token}, the token two groups of five of A-Z and 2-7, joined by -', bad, side === ref ? 'the reference fails the check it is held to' : undefined) } const [a, b] = [sent.reference.map(shape), sent.server.map(shape)] if (!isDeepStrictEqual(a, b)) await differ(`${what}: the emails sent`, request, a, b) if (wire) await checkSmtp(what, request, sent.server, wire) return sent } /// What reached the SMTP server (lib/smtp.mjs's `take()`), held to the /// emails the development sink recorded meanwhile, `recorded`, on the /// server alone, as the reference's are not sent: each recorded email /// reached it, signed in with PDS_EMAIL_SMTP_URL's user and password, sent /// to the account's email alone, from PDS_EMAIL_FROM in the envelope and /// in its `From`, with its kind's subject; a text part and an HTML part /// with the token in each, the HTML naming the host and the kind's heading /// and loading nothing (`made`); once, unless the SMTP server refused it /// (then maybe tried again); and nothing reached it that the sink did not /// record, as the sink records every email, sent through SMTP or not /// (spec/EMAIL.md, "SMTP", "The message", "The development sink"). async function checkSmtp(what, request, recorded, wire) { const sink = smtp() const fail = (want, got) => differ(`${what}: an email over SMTP`, request, want, got, 'held to spec/EMAIL.md ("SMTP", "The message") on the server alone: the reference\'s emails are not sent') const problem = wire.find((m) => m.problem) if (problem) await fail('every email sent signed in with PDS_EMAIL_SMTP_URL\'s user and password, percent-decoded', problem) const messages = wire.filter((m) => !m.problem).map((m) => { const { headers, text } = parseMessage(m.data) return { ...m, headers, text } }) const matched = new Set() for (const m of recorded) { const subject = SUBJECT[m.kind] const tries = messages.filter((x) => x.text.includes(m.token)) tries.forEach((x) => matched.add(x)) const kept = { to: m.to, kind: m.kind } if (!tries.length) await fail({ ...kept, over: 'SMTP, with the token in its body' }, 'no message with the token reached the SMTP server') for (const x of tries) { const got = { envelope: { from: x.from, to: x.to }, from: (x.headers.from ?? []).map(addressOf), to: (x.headers.to ?? []).map(addressOf), subject: (x.headers.subject ?? []).map(decodeWords), message: made(x.data, m.kind, m.token), } const want = { envelope: { from: sink.from, to: [m.to] }, from: [sink.from], to: [m.to], subject: [subject], message: MADE } if (!isDeepStrictEqual(got, want)) await fail({ ...kept, ...want }, got) } const accepted = tries.filter((x) => !x.refused).length if (accepted > 1) await fail({ ...kept, sent: 'once' }, `${accepted} messages accepted`) } const stray = messages.find((x) => !matched.has(x)) if (stray) await fail('no message but the emails the development sink recorded', { from: stray.from, to: stray.to, subject: stray.headers.subject ?? null, refused: stray.refused }) }