chadtmiller.com/monolith
An atproto PDS
0
0
// 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) ? '<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: '<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 !== '<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 })
}