SPB Git

Repository Public

addresses.ts 23.5 KB 305 lines typescript

1// /api/v1 — adresses et alias de première classe, automatisation (règles, réponse automatique, réexpédition).2import { z } from "zod"3import {4  ADDRESS_KINDS, addressByEmail, addressById, assertNotProtected, ensureIdentity, getAutomation, initMailboxSync, isPhysical, presentAddress, putAutomation, reconcileMailbox,5  canSendNow, type AddressKind, type AddressRow,6} from "../addresses.js"7import { sql } from "../db.js"8import { hasScope, requireScope, type Principal } from "../keys.js"9import { mailboxById } from "../mailjmap.js"10import { requireReauth } from "../reauth.js"11import { zRule, zVacation } from "../sieve.js"12import { createAccount, destroyAccount, destroyList, domainNameById, getAll, hostedDomains, seal } from "../stalwart.js"13import { emitEvent } from "../webhooks.js"14import { audit, bad } from "../util.js"15import { accessMap } from "./context.js"16import { zEmail } from "./headers.js"17import { zOk } from "./messages.js"18import { route } from "./registry.js"19import type { FastifyRequest } from "fastify"2021export const zAddress = z.object({22  id: z.string(), address: z.string(), kind: z.enum(ADDRESS_KINDS), mailbox: z.string().nullable().describe("Primary address of the physical mailbox that stores and sends for this address"),23  mailbox_id: z.string(), display_name: z.string(), signature_text: z.string(), signature_html: z.string(), avatar: z.string().nullable(),24  can_send: z.boolean(), can_receive: z.boolean(), status: z.enum(["active", "suspended"]), suspended_reason: z.string().nullable(), expired: z.boolean(),25  expires_at: z.string().nullable(), retention_days: z.number().nullable(), retention_trash_days: z.number().nullable(), retention_junk_days: z.number().nullable(),26  quota_bytes: z.number().nullable(), reply_policy: z.enum(["reject", "accept", "discard"]), protected: z.boolean(), extra_destinations: z.array(z.string()),27  inbound: z.enum(["accept", "reject", "discard"]).describe("What the mail server currently does with mail for this address"), created_at: z.string(), updated_at: z.string(),28})29const zName = z.string().trim().max(80).refine((s) => !/[\u0000-\u001f]/.test(s), "control characters are not allowed")30const zAvatar = z.string().max(90000).regex(/^data:image\/(png|jpeg|webp);base64,[A-Za-z0-9+/=]+$/, "avatar must be a PNG, JPEG or WebP data URL of at most 90 kB")31const zDays = z.number().int().min(1).max(36500)32const zMutable = z.object({33  display_name: zName, signature_text: z.string().max(4000), signature_html: z.string().max(20000), avatar: zAvatar.nullable(),34  can_send: z.boolean(), can_receive: z.boolean(), status: z.enum(["active", "suspended"]),35  expires_at: z.string().refine((s) => !Number.isNaN(Date.parse(s)), "invalid date").nullable(),36  retention_days: zDays.nullable(), retention_trash_days: zDays.nullable(), retention_junk_days: zDays.nullable(),37  quota_bytes: z.number().int().min(1_000_000).max(1_000_000_000_000).nullable(), reply_policy: z.enum(["reject", "accept", "discard"]),38  extra_destinations: z.array(zEmail).max(20), kind: z.enum(ADDRESS_KINDS), protected: z.boolean(),39})40const zCreate = zMutable.partial().extend({41  address: zEmail, kind: z.enum(ADDRESS_KINDS).default("alias"),42  mailbox: z.string().max(254).optional().describe("Alias kinds: primary address (or address id) of the mailbox that will store/send for it"),43  user_id: z.string().uuid().optional().describe("Mailbox kinds: owner user (defaults to the admin who owns the key or session)"),44}).strict()45type CreateInput = z.infer<typeof zCreate>46type PatchInput = Partial<z.infer<typeof zMutable>>4748async function boxAddress(a: AddressRow) { return (await mailboxById(a.mailbox_id))?.address }49async function present(a: AddressRow) { return presentAddress(a, await boxAddress(a)) }50const isAdmin = (p: Principal) => hasScope(p, "mail.admin")5152/** Une clé gère les alias des boîtes dont l'adresse principale est dans sa liste ; un administrateur gère tout. */53async function assertMayManage(p: Principal, mailboxId: string, physical: boolean) {54  if (isAdmin(p)) return55  if (p.type === "user" || physical) throw bad("admin_required", 403, "This operation requires the mail.admin scope (or an administrator session)")56  requireScope(p, "mail.addresses.manage", "mail.aliases.manage")57  if ((await accessMap(p)).get(mailboxId)?.read !== "full") throw bad("address_not_allowed", 403, "This key may only manage aliases of mailboxes whose primary address is in its allowlist")58}59async function sessionReauth(p: Principal) { if (p.type === "user") await requireReauth(p.auth) }6061async function takenOnServer(address: string): Promise<boolean> {62  const [accts, lists] = await Promise.all([getAll("Account", ["emailAddress", "aliases"]), getAll("MailingList").catch(() => [])])63  for (const a of accts) {64    if (String(a.emailAddress ?? "").toLowerCase() === address) return true65    for (const al of Object.values<any>(a.aliases ?? {})) if (`${al.name}@${await domainNameById(al.domainId)}`.toLowerCase() === address) return true66  }67  return lists.some((l) => String(l.emailAddress ?? "").toLowerCase() === address)68}6970/** Règles de cohérence par nature d'adresse ; rend les colonnes à écrire. */71function normalise(kind: AddressKind, cur: Partial<AddressRow>, patch: PatchInput): PatchInput {72  const out: PatchInput = { ...patch }73  if (kind === "send_only") { out.can_send = true; out.can_receive = false }74  if (kind === "receive_only") { out.can_send = false; out.can_receive = true }75  const expires = out.expires_at !== undefined ? out.expires_at : cur.expires_at ? new Date(cur.expires_at).toISOString() : null76  if (kind === "temporary" && !expires) throw bad("expires_at_required", 400, "Temporary addresses need expires_at")77  const physical = isPhysical(kind)78  if (!physical && (out.retention_days || out.retention_trash_days || out.retention_junk_days)) throw bad("retention_mailbox_only", 400, "Retention applies to a physical mailbox: set it on the mailbox's primary address")79  if (!physical && out.quota_bytes) throw bad("quota_mailbox_only", 400, "Quota applies to a physical mailbox: set it on the mailbox's primary address")80  if (physical && out.extra_destinations?.length) throw bad("extra_destinations_alias_only", 400, "extra_destinations is only available on alias-type addresses")81  return out82}83async function checkDestinations(self: string, mailboxAddress: string, list: string[] | undefined, receives: boolean) {84  if (!list?.length) return85  if (!receives) throw bad("extra_destinations_need_receive", 400, "extra_destinations requires an address that receives mail")86  for (const d of list) {87    if (d === self || d === mailboxAddress) throw bad("invalid_destination", 400, "extra_destinations must not contain the address itself or its own mailbox")88    const a = await addressByEmail(d)89    if (!a) throw bad("invalid_destination", 400, `Destination ${d} is not a known local address (destinations are limited to addresses managed by SP Mail)`)90  }91}9293export async function createAddress(p: Principal, input: CreateInput, req: FastifyRequest | null): Promise<AddressRow> {94  const address = input.address95  const domain = address.split("@")[1]96  if (!(await hostedDomains(true)).some((d) => d.name === domain)) throw bad("unknown_domain", 400, `Domain ${domain} is not hosted here`)97  if (input.protected !== undefined && !isAdmin(p)) throw bad("admin_required", 403, "Only an administrator can set `protected`")98  const physical = isPhysical(input.kind)99  const { address: _a, kind, mailbox, user_id, ...rest } = input100  const fields = normalise(kind, {}, rest)101  const actor = p.type === "user" ? p.userId : p.createdBy102  let row: AddressRow103104  if (physical) {105    await assertMayManage(p, "", true)106    if (await addressByEmail(address)) throw bad("address_taken", 409, "This address already exists")107    let owner = user_id ?? actor108    if (!owner) owner = (await sql`select id from users where role = 'admin' and status = 'active' order by created_at limit 1`)[0]?.id109    const [u] = owner ? await sql`select id from users where id = ${owner}` : []110    if (!u) throw bad("unknown_user", 400, "Unknown owner user")111    const acct = await createAccount(address, fields.display_name || address) // 409 address_taken si le serveur de courrier la connaît déjà112    try {113      row = await sql.begin(async (tx) => {114        const [{ n }] = await tx`select count(*)::int as n from mailboxes where user_id = ${u.id}`115        const [mb] = await tx`insert into mailboxes (user_id, address, display_name, stalwart_id, secret_enc, position)116          values (${u.id}, ${address}, ${fields.display_name ?? ""}, ${acct.id}, ${seal(acct.secret)}, ${n}) returning id`117        const [a] = await tx`insert into addresses ${tx({ address, kind, mailbox_id: mb.id, ...columns(fields) } as never)} returning *`118        return a as unknown as AddressRow119      })120    } catch (e) {121      await destroyAccount(acct.id).catch(() => {})122      throw e123    }124  } else {125    if (!mailbox) throw bad("mailbox_required", 400, "`mailbox` (primary address of the target mailbox) is required for alias-type addresses")126    const target = mailbox.includes("@") ? await addressByEmail(mailbox) : await addressById(mailbox)127    const mb = target ? await mailboxById(target.mailbox_id) : null128    if (!target || !mb || target.address !== mb.address) throw bad("unknown_mailbox", 400, "`mailbox` must be the primary address of an existing mailbox")129    await assertMayManage(p, mb.id, false)130    if ((await addressByEmail(address)) || (await takenOnServer(address))) throw bad("address_taken", 409, "This address already exists")131    const receives = fields.can_receive !== false && kind !== "send_only"132    await checkDestinations(address, mb.address, fields.extra_destinations, receives)133    const cols = { reply_policy: "reject", ...columns(fields) }134    ;[row] = (await sql`insert into addresses ${sql({ address, kind, mailbox_id: mb.id, ...cols } as never)} returning *`) as unknown as AddressRow[]135  }136  try {137    await reconcileMailbox(row.mailbox_id)138  } catch (e) {139    if (!physical) await sql`delete from addresses where id = ${row.id}`140    throw e141  }142  if (physical) await initMailboxSync(row.mailbox_id).catch(() => {})143  row = (await addressById(row.id))!144  await emitEvent({ type: "address.created", addressId: row.id, address: row.address, mailboxId: row.mailbox_id, data: { address_id: row.id, address: row.address, kind: row.kind } })145  await audit(req, actor, "address.create", row.address, { kind: row.kind, by: p.type === "key" ? `key:${p.keyId}` : "session" })146  return row147}148function columns(f: PatchInput): Record<string, unknown> {149  const out: Record<string, unknown> = {}150  for (const k of ["display_name", "signature_text", "signature_html", "avatar", "can_send", "can_receive", "status", "retention_days", "retention_trash_days", "retention_junk_days", "quota_bytes", "reply_policy", "extra_destinations", "protected", "kind"] as const)151    if (f[k] !== undefined) out[k] = f[k]152  if (f.expires_at !== undefined) out.expires_at = f.expires_at ? new Date(f.expires_at) : null153  return out154}155156export async function updateAddress(p: Principal, a: AddressRow, patch: PatchInput, req: FastifyRequest | null): Promise<AddressRow> {157  const physical = isPhysical(a.kind)158  await assertMayManage(p, a.mailbox_id, physical)159  const kind = patch.kind ?? a.kind160  if (patch.kind && isPhysical(patch.kind) !== physical) throw bad("kind_change_unsupported", 400, "An alias cannot become a mailbox (or the reverse)")161  if (patch.protected !== undefined) {162    if (!isAdmin(p)) throw bad("admin_required", 403, "Only an administrator can set `protected`")163    if (a.protected && patch.protected === false) throw bad("protected_address", 403, "Protection cannot be removed through the API")164  }165  if (a.protected) {166    // Seuls les réglages non destructifs restent modifiables sur une adresse protégée.167    const destructive = ["status", "kind", "can_receive", "expires_at", "retention_days", "retention_trash_days", "retention_junk_days", "reply_policy", "extra_destinations"] as const168    for (const k of destructive) if (patch[k] !== undefined && JSON.stringify(patch[k]) !== JSON.stringify(k === "expires_at" ? (a.expires_at ? new Date(a.expires_at).toISOString() : null) : a[k])) assertNotProtected(a)169  }170  const fields = normalise(kind, a, patch)171  const mb = (await mailboxById(a.mailbox_id))!172  const receives = (fields.can_receive ?? a.can_receive) && kind !== "send_only"173  await checkDestinations(a.address, mb.address, fields.extra_destinations ?? (patch.can_receive === false || patch.kind === "send_only" ? a.extra_destinations : undefined), receives)174  const cols = columns(fields)175  if (cols.status === "active") cols.suspended_reason = null176  if (cols.status === "suspended") cols.suspended_reason = "suspended through the API"177  if (!Object.keys(cols).length) return a178  const [before] = [a]179  let [row] = (await sql`update addresses set ${sql({ ...cols, updated_at: new Date() } as never)} where id = ${a.id} returning *`) as unknown as AddressRow[]180  try {181    await reconcileMailbox(row.mailbox_id)182  } catch (e) {183    // retour à l'état précédent si le serveur de courrier refuse : la table ne doit jamais mentir sur l'état appliqué184    const { id: _i, created_at: _c, ...old } = before185    await sql`update addresses set ${sql(old as never)} where id = ${a.id}`186    await reconcileMailbox(a.mailbox_id).catch(() => {})187    throw e188  }189  row = (await addressById(a.id))!190  if ((patch.display_name !== undefined || patch.signature_text !== undefined || patch.signature_html !== undefined) && canSendNow(row)) await ensureIdentity(mb, row, true).catch(() => {})191  if (before.status === "active" && row.status === "suspended")192    await emitEvent({ type: "address.suspended", addressId: row.id, address: row.address, mailboxId: row.mailbox_id, data: { address_id: row.id, address: row.address, reason: "suspended" } })193  await audit(req, p.type === "user" ? p.userId : p.createdBy, "address.update", row.address, { fields: Object.keys(cols), by: p.type === "key" ? `key:${p.keyId}` : "session" })194  return row195}196197export async function deleteAddress(p: Principal, a: AddressRow, opts: { purge: boolean; confirm?: string }, req: FastifyRequest | null): Promise<{ purged: boolean }> {198  const physical = isPhysical(a.kind)199  await assertMayManage(p, a.mailbox_id, physical)200  assertNotProtected(a)201  await sessionReauth(p)202  const actor = p.type === "user" ? p.userId : p.createdBy203  if (!physical) {204    await sql`delete from addresses where id = ${a.id}`205    await reconcileMailbox(a.mailbox_id, [a])206    await audit(req, actor, "address.delete", a.address, { kind: a.kind })207    return { purged: false }208  }209  const [prot] = await sql`select address from addresses where mailbox_id = ${a.mailbox_id} and protected limit 1`210  if (prot) throw bad("protected_address", 403, `This mailbox carries the protected address ${prot.address} and cannot be deleted`)211  const mb = (await mailboxById(a.mailbox_id))!212  if (opts.purge) {213    if (opts.confirm !== "delete-all-mail") throw bad("confirmation_required", 400, 'Purging a mailbox requires the body {"confirm":"delete-all-mail"}')214    const lists = await sql`select stalwart_list_id from addresses where mailbox_id = ${mb.id} and stalwart_list_id is not null`215    await destroyAccount(mb.stalwart_id) // avant le détachement : si le serveur est injoignable, rien n'est perdu de vue216    for (const l of lists) await destroyList(l.stalwart_list_id).catch(() => {})217  }218  await sql`delete from mailboxes where id = ${mb.id}`219  await audit(req, actor, opts.purge ? "mailbox.purge" : "mailbox.detach", a.address, { via: "api/v1" })220  return { purged: opts.purge }221}222223// ------------------------------------------------------------------ routes224async function visible(p: Principal): Promise<AddressRow[]> {225  if (p.type === "user" && p.role === "admin") return (await sql`select * from addresses order by address`) as unknown as AddressRow[]226  return [...(await accessMap(p)).values()].flatMap((x) => x.addresses).sort((x, y) => x.address.localeCompare(y.address))227}228async function one(p: Principal, id: string): Promise<AddressRow> {229  const a = (await visible(p)).find((x) => x.id === id.toLowerCase() || x.address === id.toLowerCase())230  if (!a) throw bad("not_found", 404, "Unknown address")231  return a232}233const ALIAS_KINDS = ADDRESS_KINDS.filter((k) => !isPhysical(k))234const zListQ = z.object({ kind: z.enum(ADDRESS_KINDS).optional(), mailbox: z.string().max(254).optional(), status: z.enum(["active", "suspended"]).optional() })235async function list(p: Principal, q: z.infer<typeof zListQ>, aliasesOnly: boolean) {236  const boxes = new Map((await sql`select id, address from mailboxes`).map((m) => [m.id as string, m.address as string]))237  const rows = (await visible(p)).filter((a) => (!aliasesOnly || !isPhysical(a.kind)) && (!q.kind || a.kind === q.kind) && (!q.status || a.status === q.status) && (!q.mailbox || boxes.get(a.mailbox_id) === q.mailbox.toLowerCase()))238  return { data: rows.map((a) => presentAddress(a, boxes.get(a.mailbox_id))) }239}240const zIdP = z.object({ id: z.string().max(254).describe("Address id (uuid) or the address itself") })241const zDeleteQ = z.object({ purge: z.literal("delete-all-mail").optional() })242const zDeleteB = z.object({ confirm: z.string().max(40).optional() })243const zDeleted = z.object({ ok: z.literal(true), purged: z.boolean() })244245route({ method: "GET", path: "/addresses", tag: "Addresses", summary: "Addresses visible to the caller", scopes: ["mail.addresses.read"], query: zListQ, response: z.object({ data: z.array(zAddress) }), handler: async ({ principal, query }) => list(principal, query, false) })246route({247  method: "POST", path: "/addresses", tag: "Addresses", summary: "Create an address (alias kinds, or a new physical mailbox)", scopes: ["mail.addresses.manage", "mail.aliases.manage"], idempotent: true, status: 201,248  description: "Alias kinds (alias, notification, send_only, receive_only, temporary) attach to an existing mailbox. `mailbox` / `shared` create a mail account and require `mail.admin`. A new address is never added implicitly to any key's allowlist.",249  body: zCreate, response: zAddress, handler: async ({ principal, body, req }) => present(await createAddress(principal, body, req)),250})251route({ method: "GET", path: "/addresses/{id}", tag: "Addresses", summary: "Read one address", scopes: ["mail.addresses.read"], params: zIdP, response: zAddress, handler: async ({ principal, params }) => present(await one(principal, params.id)) })252route({253  method: "PATCH", path: "/addresses/{id}", tag: "Addresses", summary: "Update an address (display, signatures, send/receive, suspension, expiry, quota, retention…)", scopes: ["mail.addresses.manage", "mail.aliases.manage"],254  description: "State changes are applied on the mail server before the call returns. Protected addresses refuse destructive changes with 403 `protected_address`.",255  params: zIdP, body: zMutable.partial().strict(), response: zAddress, handler: async ({ principal, params, body, req }) => present(await updateAddress(principal, await one(principal, params.id), body, req)),256})257route({258  method: "DELETE", path: "/addresses/{id}", tag: "Addresses", summary: "Delete an alias, or detach / purge a mailbox", scopes: ["mail.addresses.manage", "mail.aliases.manage"],259  description: "Alias kinds: removed from the mail server. Mailbox kinds (`mail.admin`): detached by default (the mail account and its mail are kept); `?purge=delete-all-mail` with body `{\"confirm\":\"delete-all-mail\"}` destroys the account and all its mail. Sessions need a recent re-authentication.",260  params: zIdP, query: zDeleteQ, body: zDeleteB, response: zDeleted,261  handler: async ({ principal, params, query, body, req }) => ({ ok: true as const, ...(await deleteAddress(principal, await one(principal, params.id), { purge: !!query.purge, confirm: body?.confirm }, req)) }),262})263264route({ method: "GET", path: "/aliases", tag: "Aliases", summary: "Alias-type addresses visible to the caller", scopes: ["mail.addresses.read"], query: zListQ, response: z.object({ data: z.array(zAddress) }), handler: async ({ principal, query }) => list(principal, query, true) })265route({266  method: "POST", path: "/aliases", tag: "Aliases", summary: "Create an alias on a mailbox", scopes: ["mail.aliases.manage", "mail.addresses.manage"], idempotent: true, status: 201,267  body: zCreate.extend({ kind: z.enum(ALIAS_KINDS as [AddressKind, ...AddressKind[]]).default("alias") }).strict(), response: zAddress,268  handler: async ({ principal, body, req }) => present(await createAddress(principal, body as CreateInput, req)),269})270async function alias(p: Principal, id: string) { const a = await one(p, id); if (isPhysical(a.kind)) throw bad("not_found", 404, "Unknown alias"); return a }271route({ method: "PATCH", path: "/aliases/{id}", tag: "Aliases", summary: "Update an alias (destinations, signature, sendable, disable, expiry)", scopes: ["mail.aliases.manage", "mail.addresses.manage"], params: zIdP, body: zMutable.partial().strict(), response: zAddress, handler: async ({ principal, params, body, req }) => present(await updateAddress(principal, await alias(principal, params.id), body, req)) })272route({ method: "DELETE", path: "/aliases/{id}", tag: "Aliases", summary: "Delete an alias", scopes: ["mail.aliases.manage", "mail.addresses.manage"], params: zIdP, response: zDeleted, handler: async ({ principal, params, req }) => ({ ok: true as const, ...(await deleteAddress(principal, await alias(principal, params.id), { purge: false }, req)) }) })273274// ---- automatisation par boîte (script Sieve unique « spmail », compatible avec le webmail)275const zForward = z.object({ to: zEmail, keep_copy: z.boolean().default(true) })276const zAutomation = z.object({ managed: z.boolean(), active: z.boolean(), rules: z.array(z.any()), vacation: z.any(), forward: zForward.nullable(), raw_sieve: z.string().optional() })277async function automationBox(p: Principal, id: string) {278  const a = await one(p, id)279  const mb = (await mailboxById(a.mailbox_id))!280  if (a.address !== mb.address) throw bad("not_a_mailbox", 409, "Automation belongs to a physical mailbox: use its primary address")281  if (!isAdmin(p) && (await accessMap(p)).get(mb.id)?.read !== "full") throw bad("address_not_allowed", 403, "Not allowed for this mailbox")282  return mb283}284route({285  method: "GET", path: "/addresses/{id}/automation", tag: "Addresses", summary: "Filters, auto-reply and forwarding of a mailbox", scopes: ["mail.addresses.read"], params: zIdP, response: zAutomation,286  description: "`raw_sieve` (the stored script) is returned to administrators only.",287  handler: async ({ principal, params }) => getAutomation(await automationBox(principal, params.id), isAdmin(principal)),288})289route({290  method: "PUT", path: "/addresses/{id}/automation", tag: "Addresses", summary: "Replace filters / auto-reply / forwarding of a mailbox", scopes: ["mail.addresses.manage"],291  description: "`rules` and `vacation` generate ONE managed Sieve script named `spmail` (same format as the webmail). `forward` is limited to addresses on hosted domains (one destination). `raw_sieve` replaces the script with a hand-written one and requires `mail.admin`.",292  params: zIdP, body: z.object({ rules: z.array(zRule).max(100).optional(), vacation: zVacation.optional(), forward: zForward.nullable().optional(), raw_sieve: z.string().max(100_000).optional() }).strict(), response: zAutomation,293  handler: async ({ principal, params, body, req }) => {294    const mb = await automationBox(principal, params.id)295    if (body.raw_sieve !== undefined) {296      requireScope(principal, "mail.admin")297      if (body.rules || body.vacation) throw bad("invalid_request", 400, "raw_sieve cannot be combined with rules or vacation")298    }299    await putAutomation(mb, body)300    await audit(req, principal.type === "user" ? principal.userId : principal.createdBy, "automation.update", mb.address, { fields: Object.keys(body) })301    return getAutomation(mb, isAdmin(principal))302  },303})304export { zOk }305
Files main
Menu

Theme