@shbernal/buzon 0.0.0-stage → 0.0.1

package/src/commands/mail.ts

@@ -0,0 +1,203 @@
+import { stringFlag, UsageError } from '../core/args.ts'
+import { ApiError } from '../core/api.ts'
+import { addressJwt } from '../core/credentials.ts'
+import { bestLink, localCode, serverCode } from '../core/extract.ts'
+import { deleteMail, getMail, getRawMail, listMails, type Mail } from '../core/mail.ts'
+import { parseDuration } from '../core/time.ts'
+import { type Context, type Input, resolveAddress } from './context.ts'
+
+export type MailView = Omit<Mail, 'metadata'>
+
+function view(mail: Mail): MailView {
+  const { metadata: _, ...rest } = mail
+  return rest
+}
+
+function mailId(raw: string | undefined, usage: string): number {
+  const id = Number(raw)
+  if (!raw || !Number.isSafeInteger(id) || id <= 0) throw new UsageError(usage)
+  return id
+}
+
+export function mailText(mail: MailView): string {
+  const lines = [
+    `id       ${mail.id}`,
+    `from     ${mail.from}`,
+    `subject  ${mail.subject}`,
+    `date     ${mail.date}`,
+  ]
+  if (mail.attachments.length > 0) {
+    lines.push(`files    ${mail.attachments.map((file) => file.filename).join(', ')}`)
+  }
+  return `${lines.join('\n')}\n\n${mail.text}`
+}
+
+const READ_USAGE = 'usage: buzon read <address> [--latest | --id <n> | --all] [--raw]'
+
+export type ReadResult = { mails: MailView[] } | { raw: string }
+
+export async function read(
+  { positionals, flags }: Input,
+  { config, api }: Context,
+): Promise<ReadResult> {
+  const address = resolveAddress(positionals[0], config, READ_USAGE)
+  const idFlag = stringFlag(flags, 'id')
+  const all = flags.all === true
+  if ([idFlag !== undefined, all, flags.latest === true].filter(Boolean).length > 1) {
+    throw new UsageError(READ_USAGE)
+  }
+  if (all && flags.raw === true) throw new UsageError('--raw reads one mail, not --all')
+  const jwt = addressJwt(address)
+
+  let mails: Mail[]
+  if (idFlag !== undefined) {
+    const mail = await getMail(api, jwt, mailId(idFlag, READ_USAGE))
+    if (!mail) throw new Error(`no mail ${idFlag} for ${address}`)
+    mails = [mail]
+  } else {
+    mails = await listMails(api, jwt, all ? Number.POSITIVE_INFINITY : 1)
+    if (!all && mails.length === 0) throw new Error(`no mail for ${address}`)
+  }
+
+  if (flags.raw === true) {
+    const raw = await getRawMail(api, jwt, mails[0]!.id)
+    if (raw === undefined) throw new Error(`no raw message for mail ${mails[0]!.id}`)
+    return { raw }
+  }
+  return { mails: mails.map(view) }
+}
+
+export function readText(result: ReadResult): string {
+  if ('raw' in result) return result.raw
+  return result.mails.map(mailText).join('\n\n----\n\n') || 'no mail'
+}
+
+export type Clock = { now(): number; sleep(ms: number): Promise<void> }
+
+const realClock: Clock = { now: () => Date.now(), sleep: (ms) => Bun.sleep(ms) }
+
+/** Upstream's polling etiquette: start at 3 s, back off to 10 s. */
+const FIRST_POLL = 3000
+const LAST_POLL = 10_000
+const BACKOFF = 1.5
+/** Mails looked at per poll, newest first. */
+const WINDOW = 20
+
+const WAIT_USAGE =
+  'usage: buzon wait <address> [--code | --link] [--from <regex>] [--subject <regex>] [--timeout 300] [--since now|<duration>|<date>]'
+
+export class WaitTimeout extends Error {}
+
+export type WaitResult = { id: number; code: string } | { id: number; link: string } | MailView
+
+function regexFlag(flags: Input['flags'], name: string): RegExp | undefined {
+  const raw = stringFlag(flags, name)
+  if (raw === undefined) return undefined
+  try {
+    return new RegExp(raw, 'i')
+  } catch (error) {
+    throw new UsageError(`--${name} is not a valid regular expression: ${(error as Error).message}`)
+  }
+}
+
+/** `now` waits for mail after the first poll, by id, so a skewed local clock cannot matter. */
+function sinceFlag(raw: string | undefined, now: number): number | 'now' {
+  if (raw === undefined || raw === 'now') return 'now'
+  if (/^\d+(\.\d+)?[smhd]?$/.test(raw)) return now - parseDuration(raw, 'since')
+  const date = Date.parse(raw)
+  if (Number.isNaN(date))
+    throw new UsageError('--since takes now, a duration such as 10m, or a date')
+  return date
+}
+
+/**
+ * Polls until a new mail passes the filters and yields what was asked for. A mail that
+ * passes the filters but has no code yet is looked at again on the next poll, since the
+ * instance saves its own code extraction just after the mail lands.
+ */
+export async function wait(
+  { positionals, flags }: Input,
+  { config, api }: Context,
+  clock: Clock = realClock,
+): Promise<WaitResult> {
+  const address = resolveAddress(positionals[0], config, WAIT_USAGE)
+  const code = flags.code === true
+  const link = flags.link === true
+  if (code && link) throw new UsageError('--code and --link are exclusive')
+  const from = regexFlag(flags, 'from')
+  const subject = regexFlag(flags, 'subject')
+  const timeoutFlag = stringFlag(flags, 'timeout')
+  const timeout = timeoutFlag === undefined ? 300_000 : parseDuration(timeoutFlag, 'timeout')
+  const since = sinceFlag(stringFlag(flags, 'since'), clock.now())
+  const jwt = addressJwt(address)
+
+  const deadline = clock.now() + timeout
+  /** Whole seconds, the resolution of the instance's timestamps. */
+  const cutoff = since === 'now' ? undefined : Math.floor(since / 1000) * 1000
+  let baseline: number | undefined
+  let interval = FIRST_POLL
+
+  const match = (mail: Mail): WaitResult | undefined => {
+    const fresh = cutoff === undefined ? mail.id > baseline! : Date.parse(mail.date) >= cutoff
+    if (!fresh) return undefined
+    if (from && !from.test(mail.from)) return undefined
+    if (subject && !subject.test(mail.subject)) return undefined
+    if (code) {
+      const found = serverCode(mail.metadata) ?? localCode(mail.subject, mail.text)
+      return found ? { id: mail.id, code: found } : undefined
+    }
+    if (link) {
+      const found = bestLink(mail)
+      return found ? { id: mail.id, link: found } : undefined
+    }
+    return view(mail)
+  }
+
+  for (;;) {
+    let pause = interval
+    try {
+      const mails = await listMails(api, jwt, WINDOW)
+      if (cutoff === undefined && baseline === undefined) {
+        baseline = Math.max(0, ...mails.map((mail) => mail.id))
+      } else {
+        for (const mail of mails) {
+          const result = match(mail)
+          if (result) return result
+        }
+      }
+      interval = Math.min(interval * BACKOFF, LAST_POLL)
+    } catch (error) {
+      if (!(error instanceof ApiError && error.status === 429)) throw error
+      pause = Math.max(pause, (error.retryAfter ?? 0) * 1000)
+    }
+    const remaining = deadline - clock.now()
+    if (remaining <= 0) {
+      throw new WaitTimeout(`no matching mail for ${address} within ${timeout / 1000}s`)
+    }
+    await clock.sleep(Math.min(pause, remaining))
+  }
+}
+
+export function waitText(result: WaitResult): string {
+  if ('code' in result) return result.code
+  if ('link' in result) return result.link
+  return mailText(result)
+}
+
+const DELETE_MAIL_USAGE = 'usage: buzon delete-mail <address> <id>'
+
+/** The instance answers success for an id it does not hold, so the mail is looked up first. */
+export async function removeMail(
+  { positionals }: Input,
+  { config, api }: Context,
+): Promise<{ address: string; id: number }> {
+  const address = resolveAddress(positionals[0], config, DELETE_MAIL_USAGE)
+  const id = mailId(positionals[1], DELETE_MAIL_USAGE)
+  const jwt = addressJwt(address)
+  if (!(await getMail(api, jwt, id))) throw new Error(`no mail ${id} for ${address}`)
+  if (!(await deleteMail(api, jwt, id))) throw new Error(`the instance did not delete mail ${id}`)
+  return { address, id }
+}
+
+export const removeMailText = (result: { address: string; id: number }) =>
+  `deleted mail ${result.id} of ${result.address}`

package/src/core/admin.ts

@@ -0,0 +1,38 @@
+import type { Api } from './api.ts'
+
+/** A row of `GET /admin/address`. `name` is the full address. */
+export type ServerAddress = { id: number; name: string; created_at: string }
+
+type Page = { results: ServerAddress[] }
+
+/** The largest page the instance serves. */
+const LIMIT = 100
+
+async function pages(api: Api, query?: string): Promise<ServerAddress[]> {
+  const out: ServerAddress[] = []
+  for (let offset = 0; ; offset += LIMIT) {
+    const params = new URLSearchParams({ limit: String(LIMIT), offset: String(offset) })
+    if (query) params.set('query', query)
+    const { results } = await api.request<Page>(`/admin/address?${params.toString()}`)
+    out.push(...results)
+    if (results.length < LIMIT) return out
+  }
+}
+
+export function listServerAddresses(api: Api): Promise<ServerAddress[]> {
+  return pages(api)
+}
+
+/** The search is a substring match, so the exact name is picked out of it. */
+export async function findServerAddress(
+  api: Api,
+  address: string,
+): Promise<ServerAddress | undefined> {
+  return (await pages(api, address)).find((row) => row.name === address)
+}
+
+/** A fresh address JWT, signed by the instance for any address id. */
+export async function mintJwt(api: Api, id: number): Promise<string> {
+  const { jwt } = await api.request<{ jwt: string }>(`/admin/show_password/${id}`)
+  return jwt
+}

package/src/core/api.ts

@@ -0,0 +1,101 @@
+import type { Config } from './config.ts'
+import { secret as keyringSecret, type SecretKey } from './secrets.ts'
+
+export class ApiError extends Error {
+  constructor(
+    readonly status: number,
+    readonly path: string,
+    message: string,
+    /** Upstream error code, when the body was `{ code, message }` JSON instead of text. */
+    readonly code?: string,
+    /** Seconds from a `Retry-After` header, on a 429. */
+    readonly retryAfter?: number,
+  ) {
+    super(`${path}: ${status} ${message}`)
+  }
+}
+
+export type RequestOptions = {
+  method?: string
+  body?: unknown
+  /** Address JWT, sent as a bearer token. `/api/*` routes need one, except a few public ones. */
+  jwt?: string
+  /** Leave the site password out, for a probe that must not depend on it. */
+  anonymous?: boolean
+}
+
+export type Api = {
+  request<T>(path: string, options?: RequestOptions): Promise<T>
+}
+
+/**
+ * Upstream answers errors as plain text, or as `{ code, message }` JSON for auth failures.
+ * Both become an `ApiError` with the status kept.
+ */
+async function failure(response: Response, path: string): Promise<ApiError> {
+  const text = (await response.text()).trim()
+  const retry = Number(response.headers.get('retry-after') ?? Number.NaN)
+  const retryAfter = Number.isFinite(retry) && retry >= 0 ? retry : undefined
+  try {
+    const body = JSON.parse(text) as { code?: unknown; message?: unknown }
+    if (typeof body.message === 'string') {
+      return new ApiError(
+        response.status,
+        path,
+        body.message,
+        typeof body.code === 'string' ? body.code : undefined,
+        retryAfter,
+      )
+    }
+  } catch {}
+  return new ApiError(response.status, path, text || response.statusText, undefined, retryAfter)
+}
+
+/** Secrets are read on first use, so a command that never calls `/admin/*` never needs one. */
+export function createApi(
+  config: Pick<Config, 'url'>,
+  secret: (key: SecretKey) => string = keyringSecret,
+  fetcher: typeof fetch = fetch,
+): Api {
+  const cached = new Map<SecretKey, string>()
+  const get = (key: SecretKey) => {
+    let value = cached.get(key)
+    if (value === undefined) {
+      value = secret(key)
+      cached.set(key, value)
+    }
+    return value
+  }
+
+  return {
+    async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+      const headers = new Headers({ accept: 'application/json' })
+      if (!options.anonymous) headers.set('x-custom-auth', get('site-password'))
+      if (options.jwt) headers.set('authorization', `Bearer ${options.jwt}`)
+      if (path.startsWith('/admin/')) headers.set('x-admin-auth', get('admin-password'))
+      let body: string | undefined
+      if (options.body !== undefined) {
+        headers.set('content-type', 'application/json')
+        body = JSON.stringify(options.body)
+      }
+
+      let response: Response
+      try {
+        response = await fetcher(`${config.url}${path}`, {
+          method: options.method ?? (body === undefined ? 'GET' : 'POST'),
+          headers,
+          body,
+        })
+      } catch (error) {
+        throw new Error(`${config.url}${path}: request failed`, { cause: error })
+      }
+      if (!response.ok) throw await failure(response, path)
+
+      const text = await response.text()
+      if (!response.headers.get('content-type')?.includes('application/json')) {
+        throw new ApiError(response.status, path, 'expected JSON, got something else')
+      }
+      return JSON.parse(text) as T
+    },
+  }
+}

package/src/core/args.ts

@@ -0,0 +1,57 @@
+export class UsageError extends Error {}
+
+export type Parsed = {
+  command: string
+  positionals: string[]
+  flags: Record<string, string | boolean>
+}
+
+const VALUE_FLAGS = new Set([
+  'url',
+  'domain',
+  'site',
+  'note',
+  'tier',
+  'id',
+  'from',
+  'subject',
+  'timeout',
+  'since',
+  'tag',
+  'to',
+  'out',
+])
+
+export function parseArgv(argv: string[]): Parsed {
+  const positionals: string[] = []
+  const flags: Record<string, string | boolean> = {}
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!
+    if (!arg.startsWith('-')) {
+      positionals.push(arg)
+      continue
+    }
+    const flag = arg.replace(/^--?/, '')
+    const eq = flag.indexOf('=')
+    const name = eq < 0 ? flag : flag.slice(0, eq)
+    const inline = eq < 0 ? undefined : flag.slice(eq + 1)
+    if (VALUE_FLAGS.has(name)) {
+      const value = inline ?? argv[++i]
+      if (value === undefined) throw new UsageError(`--${name} needs a value`)
+      flags[name] = value
+    } else {
+      flags[name] = inline ?? true
+    }
+  }
+
+  return { command: positionals.shift() ?? '', positionals, flags }
+}
+
+/** A flag that must carry a value, or nothing: `--url` alone is a usage error, not `true`. */
+export function stringFlag(flags: Parsed['flags'], name: string): string | undefined {
+  const value = flags[name]
+  if (value === undefined) return undefined
+  if (typeof value !== 'string' || value === '') throw new UsageError(`--${name} needs a value`)
+  return value
+}

package/src/core/config.ts

@@ -0,0 +1,84 @@
+import { readFileSync } from 'node:fs'
+import { paths } from './paths.ts'
+import { writeAtomic } from './files.ts'
+
+export type Config = {
+  /** Origin of the instance, without a trailing slash: `https://mail.example.com`. */
+  url: string
+  /** Domain the addresses are created on: `example.com`. */
+  domain: string
+  /** Upstream release the instance runs, as `buzon deploy` last shipped it: `v1.13.0`. */
+  tag?: string
+}
+
+export class ConfigMissingError extends Error {
+  constructor(file: string) {
+    super(`no config at ${file}. Run \`buzon init\` first.`)
+  }
+}
+
+export function normalizeUrl(raw: string): string {
+  let url: URL
+  try {
+    url = new URL(raw)
+  } catch {
+    throw new Error(`"${raw}" is not a URL`)
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new Error(`"${raw}" is not an http(s) URL`)
+  }
+  return url.origin
+}
+
+export function normalizeDomain(raw: string): string {
+  const domain = raw.trim().toLowerCase()
+  if (!/^[a-z0-9-]+(\.[a-z0-9-]+)+$/.test(domain)) throw new Error(`"${raw}" is not a domain`)
+  return domain
+}
+
+export function normalizeTag(raw: string): string {
+  const tag = raw.trim()
+  if (!/^v\d+\.\d+\.\d+$/.test(tag))
+    throw new Error(`"${raw}" is not a release tag such as v1.13.0`)
+  return tag
+}
+
+export function parseConfig(text: string, file = paths.config): Config {
+  let raw: Record<string, unknown>
+  try {
+    raw = Bun.TOML.parse(text) as Record<string, unknown>
+  } catch (error) {
+    throw new Error(`${file} is not valid TOML`, { cause: error })
+  }
+  const { url, domain, tag } = raw
+  if (typeof url !== 'string') throw new Error(`${file}: \`url\` is missing`)
+  if (typeof domain !== 'string') throw new Error(`${file}: \`domain\` is missing`)
+  const config: Config = { url: normalizeUrl(url), domain: normalizeDomain(domain) }
+  if (tag !== undefined) {
+    if (typeof tag !== 'string') throw new Error(`${file}: \`tag\` must be a string`)
+    config.tag = normalizeTag(tag)
+  }
+  return config
+}
+
+export function readConfig(file = paths.config): Config {
+  let text: string
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') throw new ConfigMissingError(file)
+    throw error
+  }
+  return parseConfig(text, file)
+}
+
+/** JSON string escapes are valid TOML basic-string escapes, so `JSON.stringify` quotes safely. */
+export function serializeConfig(config: Config): string {
+  const lines = [`url = ${JSON.stringify(config.url)}`, `domain = ${JSON.stringify(config.domain)}`]
+  if (config.tag) lines.push(`tag = ${JSON.stringify(config.tag)}`)
+  return `${lines.join('\n')}\n`
+}
+
+export function writeConfig(config: Config, file = paths.config): void {
+  writeAtomic(file, serializeConfig(config))
+}

package/src/core/credentials.ts

@@ -0,0 +1,19 @@
+import { paths } from './paths.ts'
+import { readJson, writeJson } from './files.ts'
+
+/** Address JWTs by address. Owner-only, and outside the tracked data directory. */
+export type Credentials = Record<string, string>
+
+export function readCredentials(file = paths.credentials): Credentials {
+  return (readJson(file) as Credentials | undefined) ?? {}
+}
+
+export function writeCredentials(credentials: Credentials, file = paths.credentials): void {
+  writeJson(file, credentials, 0o600)
+}
+
+export function addressJwt(address: string, file = paths.credentials): string {
+  const jwt = readCredentials(file)[address]
+  if (!jwt) throw new Error(`no credential for ${address}: run \`buzon reissue ${address}\``)
+  return jwt
+}

package/src/core/errors.ts

@@ -0,0 +1,19 @@
+/** How many causes deep an error is followed. A wrapper and what it wraps is the usual case. */
+const DEPTH = 3
+
+function text(error: unknown): string {
+  if (!(error instanceof Error)) return String(error)
+  const code = (error as NodeJS.ErrnoException).code
+  return code && !error.message.includes(code) ? `${error.message} (${code})` : error.message
+}
+
+/** The message followed by its `cause` chain, so "fetch failed" can say DNS from TLS. */
+export function causeChain(error: unknown): string[] {
+  const out = [text(error)]
+  let at = error instanceof Error ? error.cause : undefined
+  while (at !== undefined && out.length < DEPTH) {
+    out.push(text(at))
+    at = at instanceof Error ? at.cause : undefined
+  }
+  return out
+}