Skip to content

📧✨ Beautiful email. For everyone.

16.2 KB
Raw Blame
import type { DiscoveryCandidate, DiscoveryResult, DiscoverySource, ServerSettings } from './model'
import { serverSettingsSchema, serverUrlSchema } from './schemas'

export interface SrvRecord {
  name: string
  port: number
  priority: number
  weight: number
}
export interface DiscoveryResponse {
  status: number
  /** Lowercase header names. */
  headers: Record<string, string>
  body: string
}
/** Platform adapter for discovery. It never receives credentials, cookies, or the address itself. */
export interface DiscoveryTransport {
  /** Resolves SRV records. Resolves [] when none exist (NXDOMAIN/NODATA). */
  resolveSrv(name: string): Promise<SrvRecord[]>
  /** One unauthenticated GET. Never follows redirects, never sends credentials or cookies, and stops reading after maxBytes (reject). */
  get(url: string, options: { timeoutMs: number; maxBytes: number }): Promise<DiscoveryResponse>
}
export interface DiscoveryOptions {
  /** Discovery returns whatever it found by then. */
  deadlineMs?: number
  requestTimeoutMs?: number
}

const maxBytes = 256 * 1024
const maxRedirects = 3
const dnsName = /^(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))*$/
const ipv4 = /^\d{1,3}(\.\d{1,3}){3}$/

/**
 * Finds likely server settings for an address. Only the domain leaves the device: requests are
 * unauthenticated, bounded, HTTPS-only, and the public directory is only consulted, with the
 * domain alone, when the domain publishes no settings itself.
 * Throws for a malformed address; an IP-literal domain has nothing to discover and yields no
 * candidates. Individual sources that fail, time out, or return malformed data are skipped.
 */
export async function discoverAccount(
  email: string,
  transport: DiscoveryTransport,
  options: DiscoveryOptions = {},
): Promise<DiscoveryResult> {
  const address = email.trim()
  const at = address.lastIndexOf('@')
  const local = address.slice(0, at)
  const rawDomain = address
    .slice(at + 1)
    .trim()
    .toLowerCase()
    .replace(/\.$/, '')
  if (at < 1 || !rawDomain || address.length > 320 || /\s/.test(local))
    throw new Error('Enter a valid email address.')
  if (rawDomain.startsWith('[') || ipv4.test(rawDomain))
    return { email: address, domain: rawDomain, candidates: [] }
  const domain = asciiDomain(rawDomain)
  if (!domain) throw new Error('Enter a valid email address.')
  if (ipv4.test(domain)) return { email: address, domain, candidates: [] }

  const timeoutMs = options.requestTimeoutMs ?? 6000
  const context: Context = { transport, timeoutMs, email: address }
  const autoconfigUrls = [
    `https://autoconfig.${domain}/mail/config-v1.1.xml`,
    `https://${domain}/.well-known/autoconfig/mail/config-v1.1.xml`,
  ]
  // Listed in order of preference; they run concurrently and are ordered afterwards.
  const sources: (() => Promise<DiscoveryCandidate[]>)[] = [
    () => jmapSrv(context, domain),
    () => jmapWellKnown(context, domain),
    ...autoconfigUrls.map((url) => () => autoconfig(context, url, 'autoconfig')),
    () => imapSrv(context, domain),
  ]
  const deadline = Date.now() + (options.deadlineMs ?? 15000)
  const run = async (list: (() => Promise<DiscoveryCandidate[]>)[]) => {
    const found: (DiscoveryCandidate[] | undefined)[] = list.map(() => undefined)
    const all = Promise.allSettled(
      list.map(async (source, index) => {
        found[index] = await source()
      }),
    )
    let timer: ReturnType<typeof setTimeout> | undefined
    await Promise.race([
      all,
      new Promise<void>(
        (resolve) => (timer = setTimeout(resolve, Math.max(0, deadline - Date.now()))),
      ),
    ])
    clearTimeout(timer)
    return found.flatMap((c) => c || [])
  }
  let found = await run(sources)
  // The public directory learns which domain is being set up, so it is only asked when the
  // domain itself publishes nothing. Self-hosted domains are never disclosed to it.
  if (!found.length && Date.now() < deadline)
    found = await run([
      () =>
        autoconfig(
          context,
          `https://autoconfig.thunderbird.net/v1.1/${encodeURIComponent(domain)}`,
          'directory',
        ),
    ])
  const seen = new Set<string>()
  const candidates = found.filter((c) => {
    const key = candidateKey(c)
    if (seen.has(key)) return false
    seen.add(key)
    return true
  })
  return {
    email: address,
    domain,
    candidates: [
      ...candidates.filter((c) => c.protocol === 'jmap'),
      ...candidates.filter((c) => c.protocol === 'imap'),
    ],
  }
}

interface Context {
  transport: DiscoveryTransport
  timeoutMs: number
  email: string
}

function asciiDomain(value: string): string | undefined {
  if (/[/?#@:\\%\s]/.test(value)) return undefined
  try {
    // URL applies IDNA, so internationalised domains are looked up in their ASCII form.
    const host = new URL(`https://${value}/`).hostname
    return dnsName.test(host) ? host : undefined
  } catch {
    return undefined
  }
}
function candidateKey(c: DiscoveryCandidate): string {
  const server = (s: ServerSettings) => [s.host, s.port, s.security, s.username]
  return JSON.stringify(
    c.protocol === 'jmap'
      ? ['jmap', c.serverUrl, c.username]
      : ['imap', server(c.incoming), server(c.outgoing)],
  )
}
/** Guards against transports that ignore their own timeout. */
function bounded<T>(promise: Promise<T>, ms: number): Promise<T> {
  let timer: ReturnType<typeof setTimeout> | undefined
  return Promise.race([
    promise,
    new Promise<never>(
      (_, reject) => (timer = setTimeout(() => reject(new Error('Request timed out.')), ms)),
    ),
  ]).finally(() => clearTimeout(timer))
}
async function srv(context: Context, name: string): Promise<SrvRecord | undefined> {
  const records = await bounded(context.transport.resolveSrv(name), context.timeoutMs)
  // RFC 2782: a lone "." target means the service is deliberately not offered.
  return records
    .map((r) => ({ ...r, name: r.name.toLowerCase().replace(/\.$/, '') }))
    .filter((r) => dnsName.test(r.name) && Number.isInteger(r.port) && r.port > 0 && r.port < 65536)
    .sort((a, b) => a.priority - b.priority || b.weight - a.weight)[0]
}
/** Follows up to three HTTPS redirects itself, so every hop is checked before it is requested. */
async function fetchFollowing(
  context: Context,
  start: string,
): Promise<{ url: URL; response: DiscoveryResponse }> {
  let url = new URL(start)
  for (let hop = 0; ; hop++) {
    if (url.protocol !== 'https:' || url.username || url.password)
      throw new Error('Discovery only follows HTTPS addresses.')
    url.hash = ''
    const response = await bounded(
      context.transport.get(url.toString(), { timeoutMs: context.timeoutMs, maxBytes }),
      context.timeoutMs,
    )
    if (response.body.length > maxBytes) throw new Error('Discovery response is too large.')
    const location = response.headers.location
    if (![301, 302, 303, 307, 308].includes(response.status) || !location) return { url, response }
    if (hop >= maxRedirects) throw new Error('Too many redirects.')
    url = new URL(location, url)
  }
}
async function jmapSrv(context: Context, domain: string): Promise<DiscoveryCandidate[]> {
  const record = await srv(context, `_jmap._tcp.${domain}`)
  if (!record) return []
  const serverUrl = `https://${record.name}${record.port === 443 ? '' : `:${record.port}`}`
  return [{ protocol: 'jmap', source: 'jmap-srv', serverUrl, username: context.email }]
}
async function jmapWellKnown(context: Context, domain: string): Promise<DiscoveryCandidate[]> {
  const { url, response } = await fetchFollowing(context, `https://${domain}/.well-known/jmap`)
  const evidence =
    // RFC 8620 requires authentication here. A 403 is too often a blanket firewall answer.
    response.status === 401 || (response.status === 200 && hasCapabilities(response.body))
  if (!evidence) return []
  // The provider only authenticates to the configured origin, so show where the redirects ended.
  const serverUrl = url.pathname === '/.well-known/jmap' ? url.origin : url.toString()
  if (!serverUrlSchema.safeParse(serverUrl).success) return []
  return [{ protocol: 'jmap', source: 'jmap-well-known', serverUrl, username: context.email }]
}
function hasCapabilities(body: string): boolean {
  try {
    const session: unknown = JSON.parse(body)
    return (
      typeof session === 'object' &&
      session !== null &&
      typeof (session as { capabilities?: unknown }).capabilities === 'object' &&
      (session as { capabilities?: unknown }).capabilities !== null
    )
  } catch {
    return false
  }
}
async function autoconfig(
  context: Context,
  url: string,
  source: DiscoverySource,
): Promise<DiscoveryCandidate[]> {
  const { response } = await fetchFollowing(context, url)
  if (response.status !== 200) return []
  const config = parseAutoconfig(response.body, context.email)
  const incoming = preferTls(config.incoming)
  const outgoing = preferTls(config.outgoing)
  if (!incoming || !outgoing) return []
  return [
    {
      protocol: 'imap',
      source,
      incoming,
      outgoing,
      ...(config.provider ? { provider: config.provider } : {}),
    },
  ]
}
const preferTls = (servers: ServerSettings[]) =>
  servers.find((s) => s.security === 'tls') || servers[0]
async function imapSrv(context: Context, domain: string): Promise<DiscoveryCandidate[]> {
  const lookup = async (service: string, security: ServerSettings['security']) => {
    const record = await srv(context, `_${service}._tcp.${domain}`).catch(() => undefined)
    if (!record) return undefined
    const settings = { host: record.name, port: record.port, security, username: context.email }
    return serverSettingsSchema.safeParse(settings).success ? settings : undefined
  }
  // RFC 8314 prefers implicit TLS over STARTTLS when both are published.
  const [imaps, imap, submissions, submission] = await Promise.all([
    lookup('imaps', 'tls'),
    lookup('imap', 'starttls'),
    lookup('submissions', 'tls'),
    lookup('submission', 'starttls'),
  ])
  const incoming = imaps || imap
  const outgoing = submissions || submission
  return incoming && outgoing ? [{ protocol: 'imap', source: 'imap-srv', incoming, outgoing }] : []
}

const passwordAuth = new Set([
  'password-cleartext',
  'password-encrypted',
  // Older configuration files use these names for the same methods.
  'plain',
  'secure',
])
/**
 * Reads the IMAP and SMTP servers from a Thunderbird autoconfig file. Plaintext connections and
 * servers that only offer OAuth, Kerberos, NTLM, client certificates, or no authentication are
 * left out. Throws when the XML is malformed or uses constructs outside the tiny safe subset.
 */
export function parseAutoconfig(
  xml: string,
  email: string,
): { provider?: string; incoming: ServerSettings[]; outgoing: ServerSettings[] } {
  const root = parseXml(xml)
  if (root.name !== 'clientConfig') throw new Error('Not an autoconfig file.')
  const provider = root.children.find((c) => c.name === 'emailProvider')
  if (!provider) return { incoming: [], outgoing: [] }
  const at = email.lastIndexOf('@')
  const substitute = (value: string) =>
    value
      .replace(/%EMAILADDRESS%/g, email)
      .replace(/%EMAILLOCALPART%/g, email.slice(0, at))
      .replace(/%EMAILDOMAIN%/g, email.slice(at + 1).toLowerCase())
  const servers = (tag: string, type: string) =>
    provider.children
      .filter((c) => c.name === tag && c.attributes.type?.toLowerCase() === type)
      .flatMap((server): ServerSettings[] => {
        const text = (name: string) =>
          server.children.find((c) => c.name === name)?.text.trim() || ''
        const socket = text('socketType').toUpperCase()
        const security = socket === 'SSL' ? 'tls' : socket === 'STARTTLS' ? 'starttls' : undefined
        const auth = server.children
          .filter((c) => c.name === 'authentication')
          .map((c) => c.text.trim().toLowerCase())
        if (!security || (auth.length && !auth.some((a) => passwordAuth.has(a)))) return []
        const port = text('port')
        const settings = {
          host: substitute(text('hostname')).toLowerCase().replace(/\.$/, ''),
          port: /^\d{1,5}$/.test(port) ? Number(port) : 0,
          security,
          username: substitute(text('username')) || email,
        }
        const parsed = serverSettingsSchema.safeParse(settings)
        return parsed.success ? [parsed.data] : []
      })
  const name = ['displayName', 'displayShortName']
    .map((n) =>
      provider.children
        .find((c) => c.name === n)
        ?.text.replace(/\s+/g, ' ')
        .trim(),
    )
    .find(Boolean)
  return {
    ...(name ? { provider: name.slice(0, 100) } : {}),
    incoming: servers('incomingServer', 'imap'),
    outgoing: servers('outgoingServer', 'smtp'),
  }
}

interface XmlElement {
  name: string
  attributes: Record<string, string>
  children: XmlElement[]
  text: string
}
const xmlName = /^[A-Za-z_][\w.-]*(:[A-Za-z_][\w.-]*)?$/
const entities: Record<string, string> = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'" }
function invalid(): never {
  throw new Error('The configuration file is not valid.')
}
/**
 * A deliberately small XML reader for configuration files: no DTDs, no custom entities, no
 * processing instructions, bounded size, depth, and element count. Anything else is rejected.
 */
function parseXml(input: string): XmlElement {
  if (input.length > maxBytes) throw new Error('The configuration file is too large.')
  let xml = input.replace(/^\uFEFF/, '')
  const declaration = /^\s*<\?xml\s[^<>?]*\?>/.exec(xml)
  if (declaration) xml = xml.slice(declaration[0].length)
  const stack: XmlElement[] = []
  let root: XmlElement | undefined
  let count = 0
  let i = 0
  const addText = (value: string) => {
    const parent = stack[stack.length - 1]
    if (parent) parent.text += value
    else if (value.trim()) invalid()
  }
  while (i < xml.length) {
    const lt = xml.indexOf('<', i)
    if (lt === -1) {
      addText(decode(xml.slice(i)))
      break
    }
    if (lt > i) addText(decode(xml.slice(i, lt)))
    if (xml.startsWith('<!--', lt)) {
      const end = xml.indexOf('-->', lt + 4)
      if (end === -1) invalid()
      i = end + 3
    } else if (xml.startsWith('<![CDATA[', lt)) {
      const end = xml.indexOf(']]>', lt + 9)
      if (end === -1 || !stack.length) invalid()
      addText(xml.slice(lt + 9, end))
      i = end + 3
    } else if (xml[lt + 1] === '!' || xml[lt + 1] === '?') {
      // DOCTYPE, ENTITY, and processing instructions are where XML parsers get into trouble.
      invalid()
    } else {
      const end = xml.indexOf('>', lt)
      if (end === -1) invalid()
      i = end + 1
      if (xml[lt + 1] === '/') {
        if (stack.pop()?.name !== xml.slice(lt + 2, end).trim()) invalid()
        continue
      }
      let tag = xml.slice(lt + 1, end)
      const selfClosing = tag.endsWith('/')
      if (selfClosing) tag = tag.slice(0, -1)
      const name = /^\S*/.exec(tag)![0]
      if (!xmlName.test(name) || (root && !stack.length)) invalid()
      if (++count > 4096 || stack.length >= 32) invalid()
      const element: XmlElement = {
        name,
        attributes: parseAttributes(tag.slice(name.length)),
        children: [],
        text: '',
      }
      if (stack.length) stack[stack.length - 1].children.push(element)
      else root = element
      if (!selfClosing) stack.push(element)
    }
  }
  if (!root || stack.length) invalid()
  return root
}
function parseAttributes(source: string): Record<string, string> {
  const attributes: Record<string, string> = Object.create(null)
  const pattern = /\s+([A-Za-z_][\w.:-]*)\s*=\s*(?:"([^"<]*)"|'([^'<]*)')/y
  let index = 0
  while (source.slice(index).trim()) {
    pattern.lastIndex = index
    const match = pattern.exec(source)
    if (!match || match[1] in attributes) invalid()
    attributes[match[1]] = decode(match[2] ?? match[3])
    index = pattern.lastIndex
  }
  return attributes
}
/** Only the five predefined entities and numeric character references exist here. */
function decode(value: string): string {
  return value.replace(/&([^;&\s]{0,10});?/g, (reference, body: string) => {
    if (!reference.endsWith(';')) invalid()
    if (Object.hasOwn(entities, body)) return entities[body]
    const numeric = /^#(?:x([0-9a-fA-F]{1,6})|(\d{1,7}))$/.exec(body)
    const code = numeric ? parseInt(numeric[1] ?? numeric[2], numeric[1] ? 16 : 10) : NaN
    if (!(code > 0 && code <= 0x10ffff) || (code >= 0xd800 && code <= 0xdfff)) invalid()
    return String.fromCodePoint(code)
  })
}