@shbernal/buzon 0.0.0-stage → 0.0.1

package/src/commands/addresses.ts

@@ -0,0 +1,319 @@
+import { stringFlag, UsageError } from '../core/args.ts'
+import { ApiError } from '../core/api.ts'
+import {
+  findServerAddress,
+  listServerAddresses,
+  mintJwt,
+  type ServerAddress,
+} from '../core/admin.ts'
+import { normalizeDomain } from '../core/config.ts'
+import { addressJwt, readCredentials, writeCredentials } from '../core/credentials.ts'
+import { serverDate } from '../core/time.ts'
+import { generateName, parseCustomName, parseName, parseSite, parseTier } from '../core/names.ts'
+import { type Context, type Input, resolveAddress } from './context.ts'
+import { readRegistry, writeRegistry, type Registry, type RegistryEntry } from '../core/registry.ts'
+
+export type AddressView = RegistryEntry & { address: string }
+
+/** Tries at a free name before giving up: three random characters rarely collide twice. */
+const CREATE_ATTEMPTS = 5
+
+const KEPT = new Set(['lte', 'custom'])
+
+type Created = { jwt: string; address: string; address_id: number }
+
+function view(address: string, entry: RegistryEntry): AddressView {
+  return { address, ...entry }
+}
+
+function registered(address: string): { registry: Registry; entry: RegistryEntry } {
+  const registry = readRegistry()
+  const entry = registry.addresses[address]
+  if (!entry) throw new Error(`${address} is not in the registry`)
+  return { registry, entry }
+}
+
+const NEW_USAGE = 'usage: buzon new <ste|mte|lte> | buzon new custom <name>'
+
+/** A tiered name is generated and retried on collision; a custom name is taken as given. */
+async function createOnInstance(
+  api: Context['api'],
+  tier: RegistryEntry['tier'],
+  site: string | undefined,
+  custom: string | undefined,
+  domain: string,
+): Promise<Created> {
+  if (tier === 'custom') {
+    const address = `${custom}@${domain}`
+    try {
+      return await api.request<Created>('/admin/new_address', {
+        body: { name: custom, domain, enablePrefix: false },
+      })
+    } catch (error) {
+      if (error instanceof ApiError && /already exists/i.test(error.message)) {
+        throw new Error(`${address} already exists: \`buzon adopt ${address}\` adds it`, {
+          cause: error,
+        })
+      }
+      throw error
+    }
+  }
+  for (let attempt = 1; ; attempt++) {
+    const name = generateName(tier, site)
+    try {
+      return await api.request<Created>('/api/new_address', { body: { name, domain } })
+    } catch (error) {
+      const taken = error instanceof ApiError && /already exists/i.test(error.message)
+      if (!taken || attempt >= CREATE_ATTEMPTS) throw error
+    }
+  }
+}
+
+/**
+ * The credential is saved before the registry entry, so a failure leaves at worst a server
+ * address without a registry entry, and the error names it with the way to recover it.
+ */
+export async function create(
+  { positionals, flags }: Input,
+  { config, api }: Context,
+): Promise<AddressView & { token?: string }> {
+  const custom = positionals[0] === 'custom'
+  if (positionals.length !== (custom ? 2 : 1)) throw new UsageError(NEW_USAGE)
+  const tier = custom ? 'custom' : parseTier(positionals[0])
+  const name = custom ? parseCustomName(positionals[1]!) : undefined
+  const site = parseSite(tier, stringFlag(flags, 'site'))
+  const note = stringFlag(flags, 'note')
+  const domainFlag = stringFlag(flags, 'domain')
+  const domain = domainFlag ? normalizeDomain(domainFlag) : config.domain
+
+  const registry = readRegistry()
+  const credentials = readCredentials()
+  const created = await createOnInstance(api, tier, site, name, domain)
+
+  const { address, jwt } = created
+  const recover = `run \`buzon adopt ${address}\` to recover it`
+  try {
+    writeCredentials({ ...credentials, [address]: jwt })
+  } catch (error) {
+    throw new Error(`created ${address}, but its credential was not saved: ${recover}`, {
+      cause: error,
+    })
+  }
+  const entry: RegistryEntry = {
+    tier,
+    ...(site && { site }),
+    ...(note && { note }),
+    createdAt: new Date().toISOString(),
+    addressId: created.address_id,
+  }
+  try {
+    writeRegistry({ addresses: { ...registry.addresses, [address]: entry } })
+  } catch (error) {
+    throw new Error(
+      `created ${address} and saved its credential, but not its registry entry: ${recover}`,
+      {
+        cause: error,
+      },
+    )
+  }
+  return { ...view(address, entry), ...(flags['show-token'] === true && { token: jwt }) }
+}
+
+export function createText(result: AddressView & { token?: string }): string {
+  return result.token ? `${result.address}\n${result.token}` : result.address
+}
+
+export function list({ flags }: Input): AddressView[] {
+  const tierFlag = stringFlag(flags, 'tier')
+  if (tierFlag && tierFlag !== 'custom') parseTier(tierFlag)
+  const site = stringFlag(flags, 'site')?.toLowerCase()
+  return Object.entries(readRegistry().addresses)
+    .filter(([, entry]) => (!tierFlag || entry.tier === tierFlag) && (!site || entry.site === site))
+    .map(([address, entry]) => view(address, entry))
+    .toSorted((a, b) => a.createdAt.localeCompare(b.createdAt))
+}
+
+export function listText(rows: AddressView[]): string {
+  if (rows.length === 0) return 'no addresses'
+  const width = Math.max(...rows.map((row) => row.address.length))
+  return rows
+    .map((row) => {
+      const columns = [row.address.padEnd(width), row.tier.padEnd(6), row.createdAt.slice(0, 10)]
+      if (row.note) columns.push(row.note)
+      return columns.join('  ')
+    })
+    .join('\n')
+}
+
+const SHOW_USAGE = 'usage: buzon show <address>'
+
+export async function show(
+  { positionals }: Input,
+  { config, api }: Context,
+): Promise<AddressView & { mails: number }> {
+  const address = resolveAddress(positionals[0], config, SHOW_USAGE)
+  const { entry } = registered(address)
+  const jwt = addressJwt(address)
+  const { count } = await api.request<{ count: number }>('/api/mails?limit=1&offset=0', { jwt })
+  return { ...view(address, entry), mails: count }
+}
+
+export function showText(result: AddressView & { mails: number }): string {
+  const lines = [result.address, `tier     ${result.tier}`]
+  if (result.site) lines.push(`site     ${result.site}`)
+  if (result.note) lines.push(`note     ${result.note}`)
+  lines.push(`created  ${result.createdAt}`, `mails    ${result.mails}`)
+  return lines.join('\n')
+}
+
+const NOTE_USAGE = 'usage: buzon note <address> "<note>" (an empty note clears it)'
+
+export function setNote({ positionals }: Input, { config }: Pick<Context, 'config'>): AddressView {
+  const address = resolveAddress(positionals[0], config, NOTE_USAGE)
+  const text = positionals[1]
+  if (text === undefined || positionals.length > 2) throw new UsageError(NOTE_USAGE)
+  const { registry, entry } = registered(address)
+  const { note: _, ...rest } = entry
+  const updated: RegistryEntry = text.trim() ? { ...rest, note: text.trim() } : rest
+  writeRegistry({ addresses: { ...registry.addresses, [address]: updated } })
+  return view(address, updated)
+}
+
+export const setNoteText = (result: AddressView) =>
+  result.note ? `${result.address}: ${result.note}` : `${result.address}: note cleared`
+
+const DELETE_USAGE = 'usage: buzon delete <address> [--force]'
+
+export type DeleteResult = { address: string; alreadyGone: boolean }
+
+/**
+ * A deleted address answers 401 to its own JWT, and so does a JWT signed with a rotated
+ * secret. The admin list tells the two apart before anything local is removed.
+ */
+export async function remove(
+  { positionals, flags }: Input,
+  { config, api }: Context,
+): Promise<DeleteResult> {
+  const address = resolveAddress(positionals[0], config, DELETE_USAGE)
+  const { registry, entry } = registered(address)
+  if (KEPT.has(entry.tier) && flags.force !== true) {
+    throw new UsageError(`${address} is ${entry.tier}, which is kept: pass --force to delete it`)
+  }
+
+  const credentials = readCredentials()
+  const jwt = credentials[address]
+  let rejected: ApiError | undefined
+  if (jwt) {
+    try {
+      const { success } = await api.request<{ success: boolean }>('/api/delete_address', {
+        method: 'DELETE',
+        jwt,
+      })
+      if (!success) throw new Error(`the instance did not delete ${address}`)
+    } catch (error) {
+      if (!(error instanceof ApiError && error.status === 401)) throw error
+      rejected = error
+    }
+  }
+  const alreadyGone = !jwt || rejected !== undefined
+  if (alreadyGone && (await findServerAddress(api, address))) {
+    const why = jwt ? 'the instance rejects its credential' : 'no credential'
+    throw new Error(`cannot delete ${address}, ${why}: run \`buzon reissue ${address}\``, {
+      cause: rejected,
+    })
+  }
+
+  const { [address]: _entry, ...addresses } = registry.addresses
+  writeRegistry({ addresses })
+  const { [address]: _jwt, ...rest } = credentials
+  writeCredentials(rest)
+  return { address, alreadyGone }
+}
+
+export const removeText = (result: DeleteResult) =>
+  result.alreadyGone
+    ? `${result.address} was already gone from the instance, removed it locally`
+    : `deleted ${result.address}`
+
+const REISSUE_USAGE = 'usage: buzon reissue <address> | --all'
+
+export type ReissueResult = { reissued: string[]; missing: string[] }
+
+/** Fresh JWTs from the admin API, for a lost credentials file or a rotated `JWT_SECRET`. */
+export async function reissue(
+  { positionals, flags }: Input,
+  { config, api }: Context,
+): Promise<ReissueResult> {
+  const all = flags.all === true
+  if (all === positionals.length > 0) throw new UsageError(REISSUE_USAGE)
+  const registry = readRegistry()
+  const targets = all
+    ? Object.keys(registry.addresses)
+    : [resolveAddress(positionals[0], config, REISSUE_USAGE)]
+  for (const address of targets) {
+    if (!registry.addresses[address]) {
+      throw new Error(`${address} is not in the registry: \`buzon adopt ${address}\` adds it`)
+    }
+  }
+
+  const server = new Map<string, ServerAddress>()
+  if (all) {
+    for (const row of await listServerAddresses(api)) server.set(row.name, row)
+  } else {
+    const row = await findServerAddress(api, targets[0]!)
+    if (row) server.set(row.name, row)
+  }
+
+  const credentials = readCredentials()
+  const result: ReissueResult = { reissued: [], missing: [] }
+  for (const address of targets) {
+    const row = server.get(address)
+    if (!row) {
+      result.missing.push(address)
+      continue
+    }
+    credentials[address] = await mintJwt(api, row.id)
+    registry.addresses[address] = { ...registry.addresses[address]!, addressId: row.id }
+    result.reissued.push(address)
+  }
+  writeCredentials(credentials)
+  writeRegistry(registry)
+  return result
+}
+
+export function reissueText(result: ReissueResult): string {
+  const lines = result.reissued.map((address) => `reissued ${address}`)
+  for (const address of result.missing) {
+    lines.push(`${address} is not on the instance: \`buzon delete ${address} --force\` drops it`)
+  }
+  return lines.join('\n') || 'nothing to reissue'
+}
+
+const ADOPT_USAGE = 'usage: buzon adopt <address> [--note "…"]'
+
+/** An address made elsewhere, such as the admin UI. A name outside the scheme is `custom`. */
+export async function adopt(
+  { positionals, flags }: Input,
+  { config, api }: Context,
+): Promise<AddressView> {
+  const address = resolveAddress(positionals[0], config, ADOPT_USAGE)
+  const note = stringFlag(flags, 'note')
+  const registry = readRegistry()
+  if (registry.addresses[address]) throw new Error(`${address} is already in the registry`)
+  const row = await findServerAddress(api, address)
+  if (!row) throw new Error(`${address} is not on the instance`)
+  const jwt = await mintJwt(api, row.id)
+
+  const scheme = parseName(address.split('@')[0]!)
+  const entry: RegistryEntry = {
+    ...(scheme ?? { tier: 'custom' }),
+    ...(note && { note }),
+    createdAt: serverDate(row.created_at) ?? new Date().toISOString(),
+    addressId: row.id,
+  }
+  writeCredentials({ ...readCredentials(), [address]: jwt })
+  writeRegistry({ addresses: { ...registry.addresses, [address]: entry } })
+  return view(address, entry)
+}
+
+export const adoptText = (result: AddressView) => `adopted ${result.address} as ${result.tier}`

package/src/commands/context.ts

@@ -0,0 +1,13 @@
+import { UsageError, type Parsed } from '../core/args.ts'
+import type { Api } from '../core/api.ts'
+import type { Config } from '../core/config.ts'
+
+export type Context = { config: Config; api: Api }
+export type Input = Pick<Parsed, 'positionals' | 'flags'>
+
+/** A bare name gets the configured domain. */
+export function resolveAddress(raw: string | undefined, config: Config, usage: string): string {
+  if (!raw) throw new UsageError(usage)
+  const address = raw.trim().toLowerCase()
+  return address.includes('@') ? address : `${address}@${config.domain}`
+}

package/src/commands/deploy.ts

@@ -0,0 +1,188 @@
+import { mkdirSync, readdirSync, rmSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { stringFlag, UsageError, type Parsed } from '../core/args.ts'
+import { normalizeTag, writeConfig, type Config } from '../core/config.ts'
+import { paths } from '../core/paths.ts'
+import { withPrompt, type Ask } from '../core/prompt.ts'
+import {
+  addedDbFiles,
+  changelogMentions,
+  checkout,
+  databaseName,
+  prepare,
+  requireTools,
+  run,
+  templateDiff,
+  wrangler,
+} from '../core/upstream.ts'
+import type { Context } from './context.ts'
+import { verify } from './init.ts'
+
+export type DeployResult = { tag: string; url: string; dryRun: boolean; version?: string }
+export type ExportResult = { file: string; pruned: string[] }
+export type UpgradeResult = {
+  from: string
+  to: string
+  backup?: string
+  applied: string[]
+  skipped: string[]
+  version: string
+}
+
+/** Backups kept by `export-db`, oldest pruned first. */
+const KEEP = 12
+
+const say = (line: string) => console.error(line)
+
+function deployedTag(config: Config): string {
+  if (!config.tag) throw new UsageError('no tag in the config: run `buzon deploy --tag vX.Y.Z`')
+  return config.tag
+}
+
+/** The new Worker can take a few seconds to answer everywhere. */
+async function awaitVersion(context: Context, tag: string): Promise<string> {
+  let version = ''
+  for (let attempt = 0; attempt < 10; attempt++) {
+    if (attempt > 0) await Bun.sleep(3000)
+    version = await verify(context.config, context.api)
+    if (version === tag) return version
+  }
+  throw new Error(`${context.config.url} still reports ${version} after deploying ${tag}`)
+}
+
+async function ship(context: Context, tag: string, dryRun: boolean): Promise<DeployResult> {
+  const dir = await prepare(tag)
+  await run(['pnpm', 'run', 'build:pages'], join(dir, 'frontend'))
+  const { url } = context.config
+  if (dryRun) {
+    await wrangler(dir, ['deploy', '--minify', '--dry-run'])
+    return { tag, url, dryRun }
+  }
+  await wrangler(dir, ['deploy', '--minify'])
+  const version = await awaitVersion(context, tag)
+  writeConfig({ ...context.config, tag })
+  return { tag, url, dryRun, version }
+}
+
+/** Secrets already live on the Worker: a deploy never sends them. */
+export function deploy({ flags }: Pick<Parsed, 'flags'>, context: Context): Promise<DeployResult> {
+  const raw = stringFlag(flags, 'tag')
+  const tag = raw ? normalizeTag(raw) : deployedTag(context.config)
+  return ship(context, tag, flags['dry-run'] === true)
+}
+
+export function deployText(result: DeployResult): string {
+  if (result.dryRun) return `${result.tag} built and checked, nothing deployed`
+  return `${result.url} runs ${result.version}`
+}
+
+const stamp = () =>
+  new Date()
+    .toISOString()
+    .replace(/\.\d+Z$/, 'Z')
+    .replaceAll(':', '-')
+
+/** The dump goes through `wrangler` in the checkout, so `dir` is made absolute first. */
+async function exportTo(out: string, tag: string): Promise<ExportResult> {
+  const dir = resolve(out)
+  mkdirSync(dir, { recursive: true })
+  const checkoutDir = await prepare(tag)
+  const file = join(dir, `${stamp()}.sql`)
+  await wrangler(checkoutDir, ['d1', 'export', databaseName(), '--remote', '--output', file])
+  const dumps = readdirSync(dir)
+    .filter((name) => /^\d{4}-\d{2}-\d{2}T[\d-]+Z\.sql$/.test(name))
+    .toSorted()
+  const pruned = dumps.slice(0, Math.max(0, dumps.length - KEEP)).map((name) => join(dir, name))
+  for (const old of pruned) rmSync(old)
+  return { file, pruned }
+}
+
+export function exportDb(
+  { flags }: Pick<Parsed, 'flags'>,
+  context: Context,
+): Promise<ExportResult> {
+  return exportTo(stringFlag(flags, 'out') ?? paths.backups, deployedTag(context.config))
+}
+
+export function exportDbText(result: ExportResult): string {
+  const pruned = result.pruned.length > 0 ? `\npruned ${result.pruned.length} older dumps` : ''
+  return `wrote ${result.file}${pruned}`
+}
+
+type Answer = 'yes' | 'skip' | 'stop'
+
+async function confirm(ask: Ask, question: string, skippable: boolean): Promise<Answer> {
+  const choices = skippable ? 'y/s/N' : 'y/N'
+  const answer = (await ask(`${question} (${choices})`)).toLowerCase()
+  if (answer === 'y' || answer === 'yes') return 'yes'
+  if (skippable && (answer === 's' || answer === 'skip')) return 'skip'
+  return 'stop'
+}
+
+function review(older: string, newer: string, patches: string[]): void {
+  const diff = templateDiff(older, newer)
+  say(diff ? `wrangler.toml.template changes:\n${diff}` : 'wrangler.toml.template is unchanged')
+  if (patches.length === 0) {
+    say('no new db/ files')
+    return
+  }
+  say('new db/ files:')
+  for (const patch of patches) {
+    const mentions = changelogMentions(newer, patch)
+    say(`  ${patch}${mentions.length === 0 ? ' (not in the changelog)' : ''}`)
+    for (const line of mentions) say(`    ${line}`)
+  }
+}
+
+/** Every step is asked for: nothing runs against the live database unreviewed. */
+export async function upgrade(
+  { flags }: Pick<Parsed, 'flags'>,
+  context: Context,
+  interactive: boolean,
+): Promise<UpgradeResult> {
+  const raw = stringFlag(flags, 'to')
+  if (!raw) throw new UsageError('usage: buzon upgrade --to vX.Y.Z')
+  const to = normalizeTag(raw)
+  const from = deployedTag(context.config)
+  if (from === to) throw new UsageError(`the instance already runs ${to}`)
+  if (!interactive)
+    throw new UsageError('buzon upgrade asks before each step: run it on a terminal')
+
+  requireTools()
+  const older = await checkout(from)
+  const newer = await checkout(to)
+  const patches = addedDbFiles(older, newer)
+  review(older, newer, patches)
+
+  return withPrompt(async (ask) => {
+    const result: UpgradeResult = { from, to, applied: [], skipped: [], version: from }
+    if ((await confirm(ask, 'Export the database first?', false)) === 'yes') {
+      result.backup = (await exportTo(paths.backups, from)).file
+      say(`wrote ${result.backup}`)
+    }
+    const dir = await prepare(to)
+    for (const patch of patches) {
+      const answer = await confirm(ask, `Run db/${patch} against the live database?`, true)
+      if (answer === 'stop') throw new Error(`upgrade stopped before db/${patch}`)
+      if (answer === 'skip') {
+        result.skipped.push(patch)
+        continue
+      }
+      await wrangler(dir, ['d1', 'execute', databaseName(), '--remote', `--file=../db/${patch}`])
+      result.applied.push(patch)
+    }
+    if ((await confirm(ask, `Deploy ${to}?`, false)) !== 'yes') {
+      throw new Error(`upgrade stopped before deploying ${to}`)
+    }
+    result.version = (await ship(context, to, false)).version ?? to
+    return result
+  })
+}
+
+export function upgradeText(result: UpgradeResult): string {
+  const lines = [`${result.from} -> ${result.version}`]
+  if (result.backup) lines.push(`backup: ${result.backup}`)
+  if (result.applied.length > 0) lines.push(`applied: ${result.applied.join(', ')}`)
+  if (result.skipped.length > 0) lines.push(`skipped: ${result.skipped.join(', ')}`)
+  return lines.join('\n')
+}

package/src/commands/init.ts

@@ -0,0 +1,81 @@
+import { stringFlag, UsageError, type Parsed } from '../core/args.ts'
+import { ApiError, createApi, type Api } from '../core/api.ts'
+import {
+  normalizeDomain,
+  normalizeUrl,
+  readConfig,
+  writeConfig,
+  type Config,
+} from '../core/config.ts'
+import { paths } from '../core/paths.ts'
+import { withPrompt } from '../core/prompt.ts'
+
+export const INIT_USAGE =
+  'usage: buzon init --url <https://mail.example.com> --domain <example.com>'
+
+export type InitResult = Config & { file: string; version: string }
+
+type OpenSettings = { version?: string; domains?: string[] }
+
+function existing(): Partial<Config> {
+  try {
+    return readConfig()
+  } catch {
+    return {}
+  }
+}
+
+/** Flags win. A missing value is asked on a terminal, and is a usage error elsewhere. */
+export async function resolveInput(flags: Parsed['flags'], interactive: boolean): Promise<Config> {
+  let url = stringFlag(flags, 'url')
+  let domain = stringFlag(flags, 'domain')
+  if ((!url || !domain) && !interactive) throw new UsageError(INIT_USAGE)
+  if (url && domain) return { url: normalizeUrl(url), domain: normalizeDomain(domain) }
+  const current = existing()
+  return withPrompt(async (ask) => {
+    const normalized = normalizeUrl(url ?? (await ask('Instance URL', current.url)))
+    const fallback = current.domain ?? new URL(normalized).hostname
+    return {
+      url: normalized,
+      domain: normalizeDomain(domain ?? (await ask('Mail domain', fallback))),
+    }
+  })
+}
+
+/**
+ * `/health_check` is shadowed by the frontend assets on a deploy that serves both, so the
+ * public settings route is the probe. A site-only route then checks the site password:
+ * `/api/settings` also wants an address JWT, so it cannot tell a wrong password apart.
+ */
+export async function verify(config: Config, api: Api = createApi(config)): Promise<string> {
+  const settings = await api.request<OpenSettings>('/open_api/settings', { anonymous: true })
+  if (typeof settings.version !== 'string') {
+    throw new Error(`${config.url} does not look like a cloudflare_temp_email instance`)
+  }
+  if (!settings.domains?.includes(config.domain)) {
+    const served = settings.domains?.join(', ') || 'none'
+    throw new Error(`${config.url} does not serve ${config.domain} (it serves: ${served})`)
+  }
+  try {
+    await api.request('/user_api/open_settings')
+  } catch (error) {
+    if (error instanceof ApiError && error.code === 'AUTH_SITE_PASSWORD_INVALID') {
+      throw new Error('the instance rejects the site password', { cause: error })
+    }
+    throw error
+  }
+  return settings.version
+}
+
+/** Nothing is written until the instance answers and accepts the site password. */
+export async function init(flags: Parsed['flags'], interactive: boolean): Promise<InitResult> {
+  const config = await resolveInput(flags, interactive)
+  const version = await verify(config)
+  const { tag } = existing()
+  writeConfig(tag ? { ...config, tag } : config)
+  return { ...config, file: paths.config, version }
+}
+
+export function initText(result: InitResult): string {
+  return `${result.url} (${result.version}), addresses on ${result.domain}\nwrote ${result.file}`
+}