@bugmole/cli 0.4.0

package/src/registry-worker/domains/domains.test.ts

@@ -0,0 +1,210 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { Env } from "../core.js";
+import { call, createTestEnv, seedPlan, seedProject } from "../testing/harness.js";
+import {
+  domainProvesToken,
+  hostMatchesVerifiedDomain,
+  needsDomainVerification,
+  normalizeDomain,
+  targetHost,
+} from "../domains.js";
+
+// --- Pure helpers -----------------------------------------------------------------------------
+
+test("normalizeDomain strips scheme, path, port and trailing dot; rejects the rest", () => {
+  assert.equal(normalizeDomain("https://Example.com/checkout?x=1"), "example.com");
+  assert.equal(normalizeDomain("example.com:8443"), "example.com");
+  assert.equal(normalizeDomain("staging.example.com."), "staging.example.com");
+  for (const bad of ["not a domain", "192.168.1.1", "::1", "http://", "a".repeat(260) + ".com"]) {
+    assert.throws(() => normalizeDomain(bad), Error, bad);
+  }
+});
+
+test("targetHost only accepts http(s) URLs", () => {
+  assert.equal(targetHost("https://shop.example.com/cart"), "shop.example.com");
+  assert.equal(targetHost("HTTP://Shop.Example.com"), "shop.example.com");
+  assert.equal(targetHost("ftp://example.com"), null);
+  assert.equal(targetHost("not a url"), null);
+});
+
+test("private and loopback hosts need no verification; Bugmole Cloud can't reach them anyway", () => {
+  for (const host of ["localhost", "127.0.0.1", "10.0.0.5", "192.168.1.1", "172.16.0.1", "172.31.255.255", "169.254.1.1", "[::1]", "::1"]) {
+    assert.equal(needsDomainVerification(host), false, host);
+  }
+  for (const host of ["example.com", "172.32.0.1", "172.15.0.1", "8.8.8.8"]) {
+    assert.equal(needsDomainVerification(host), true, host);
+  }
+});
+
+test("a verified domain covers itself and its subdomains, not lookalikes", () => {
+  assert.equal(hostMatchesVerifiedDomain("example.com", "example.com"), true);
+  assert.equal(hostMatchesVerifiedDomain("staging.example.com", "example.com"), true);
+  assert.equal(hostMatchesVerifiedDomain("example.com", "staging.example.com"), false);
+  assert.equal(hostMatchesVerifiedDomain("notexample.com", "example.com"), false);
+  assert.equal(hostMatchesVerifiedDomain("example.com.evil.example", "example.com"), false);
+});
+
+test("domainProvesToken only accepts the exact token at the exact record name", async () => {
+  const calls: string[] = [];
+  const lookup = async (name: string) => {
+    calls.push(name);
+    return name === "_bugmole-verify.example.com" ? ["something-else", "bugmole-domain-verify=abc123"] : [];
+  };
+  assert.equal(await domainProvesToken("example.com", "bugmole-domain-verify=abc123", lookup), true);
+  assert.equal(await domainProvesToken("other.com", "bugmole-domain-verify=abc123", lookup), false);
+  assert.deepEqual(calls, ["_bugmole-verify.example.com", "_bugmole-verify.other.com"]);
+});
+
+// --- Routes and enforcement --------------------------------------------------------------------
+
+/** A fake DoH resolver that answers real (name -> token) pairs, like a real zone would. */
+function dnsWithRecords(records: Map<string, string>) {
+  return (async (input: RequestInfo | URL) => {
+    const url = new URL(String(input));
+    const name = url.searchParams.get("name") ?? "";
+    const value = records.get(name);
+    return Response.json({ Answer: value ? [{ data: `"${value}"` }] : [] });
+  }) as unknown as typeof fetch;
+}
+
+async function workspace(overrides: Partial<Env> = {}) {
+  const setup = createTestEnv({ FEATURE_CLOUD_RUNNERS: "on", REGISTRY_PUBLIC_URL: "https://registry.test", ...overrides } as Partial<Env>);
+  const project = await seedProject(setup.env, { storageProvider: "bugmole" });
+  await seedPlan(setup.env, project.projectId, project.owner);
+  return { ...setup, ...project };
+}
+
+test("adding a domain returns a pending TXT record; only owners/admins may manage it", async () => {
+  const { env, workspaceId, owner } = await workspace();
+  const denied = await call(env, "POST", `/api/workspaces/${workspaceId}/domains`, { as: "user_stranger", body: { domain: "example.com" } });
+  assert.equal(denied.status, 403);
+  const added = await call(env, "POST", `/api/workspaces/${workspaceId}/domains`, { as: owner, body: { domain: "https://Example.com/" } });
+  assert.equal(added.status, 201, JSON.stringify(added.json));
+  assert.equal(added.json.domain.domain, "example.com");
+  assert.equal(added.json.domain.status, "pending");
+  assert.equal(added.json.domain.txtRecord.name, "_bugmole-verify.example.com");
+  assert.match(added.json.domain.txtRecord.value, /^bugmole-domain-verify=/);
+
+  const invalid = await call(env, "POST", `/api/workspaces/${workspaceId}/domains`, { as: owner, body: { domain: "not a domain" } });
+  assert.equal(invalid.status, 422);
+
+  // Re-adding the same domain is idempotent, not a duplicate.
+  const again = await call(env, "POST", `/api/workspaces/${workspaceId}/domains`, { as: owner, body: { domain: "example.com" } });
+  assert.equal(again.json.domain.id, added.json.domain.id);
+
+  const listed = await call(env, "GET", `/api/workspaces/${workspaceId}/domains`, { as: owner });
+  assert.equal(listed.json.domains.length, 1);
+  assert.equal(listed.json.canManage, true);
+  const memberView = await call(env, "GET", `/api/workspaces/${workspaceId}/domains`, { as: "user_stranger" });
+  assert.equal(memberView.status, 403);
+});
+
+test("verification checks the real TXT record and rejects a stranger's guess", async () => {
+  const records = new Map<string, string>();
+  const { env, workspaceId, owner } = await workspace({ DOMAIN_VERIFY_FETCH: dnsWithRecords(records) } as Partial<Env>);
+  const added = await call(env, "POST", `/api/workspaces/${workspaceId}/domains`, { as: owner, body: { domain: "example.com" } });
+  const id = added.json.domain.id;
+
+  const tooSoon = await call(env, "POST", `/api/workspaces/${workspaceId}/domains/${id}/verify`, { as: owner });
+  assert.equal(tooSoon.status, 400);
+  assert.equal(tooSoon.json.error, "dns_verification_failed");
+
+  const wrongValue = await call(env, "POST", `/api/workspaces/${workspaceId}/domains/${id}/verify`, { as: "user_stranger" });
+  assert.equal(wrongValue.status, 403, "verifying is also owner/admin-only");
+
+  records.set("_bugmole-verify.example.com", added.json.domain.txtRecord.value);
+  const verified = await call(env, "POST", `/api/workspaces/${workspaceId}/domains/${id}/verify`, { as: owner });
+  assert.equal(verified.status, 200);
+  assert.equal(verified.json.verified, true);
+
+  const listed = await call(env, "GET", `/api/workspaces/${workspaceId}/domains`, { as: owner });
+  assert.equal(listed.json.domains[0].status, "verified");
+
+  const removed = await call(env, "DELETE", `/api/workspaces/${workspaceId}/domains/${id}`, { as: owner });
+  assert.equal(removed.status, 200);
+  assert.equal((await call(env, "GET", `/api/workspaces/${workspaceId}/domains`, { as: owner })).json.domains.length, 0);
+});
+
+test("a cloud run against an unverified domain is refused, then allowed once verified", async () => {
+  const records = new Map<string, string>();
+  const { env, workspaceId, owner, projectId } = await workspace({ DOMAIN_VERIFY_FETCH: dnsWithRecords(records) } as Partial<Env>);
+  await call(env, "POST", `/api/projects/${projectId}/environments`, { as: owner, body: { id: "prod", name: "Prod", baseUrl: "https://shop.example.com/" } });
+
+  const blocked = await call(env, "POST", `/api/projects/${projectId}/runs`, {
+    as: owner,
+    body: { planId: "checkout", idempotencyKey: "k1", executionMode: "cloud", environmentId: "prod" },
+  });
+  assert.equal(blocked.status, 403, JSON.stringify(blocked.json));
+  assert.equal(blocked.json.code, "domain_not_verified");
+  assert.equal(blocked.json.domain, "shop.example.com");
+
+  const added = await call(env, "POST", `/api/workspaces/${workspaceId}/domains`, { as: owner, body: { domain: "example.com" } });
+  records.set("_bugmole-verify.example.com", added.json.domain.txtRecord.value);
+  await call(env, "POST", `/api/workspaces/${workspaceId}/domains/${added.json.domain.id}/verify`, { as: owner });
+
+  const allowed = await call(env, "POST", `/api/projects/${projectId}/runs`, {
+    as: owner,
+    body: { planId: "checkout", idempotencyKey: "k2", executionMode: "cloud", environmentId: "prod" },
+  });
+  assert.equal(allowed.status, 201, JSON.stringify(allowed.json));
+
+  // Self-hosted runs never touch Bugmole's infrastructure, so the same
+  // unverified environment is untouched for them.
+  const selfHosted = await call(env, "POST", `/api/projects/${projectId}/runs`, {
+    as: owner,
+    body: { planId: "checkout", idempotencyKey: "k3", executionMode: "self", environmentId: "prod" },
+  });
+  assert.equal(selfHosted.status, 201);
+});
+
+test("a cloud run against a private address needs no verification", async () => {
+  const { env, owner, projectId } = await workspace();
+  await call(env, "POST", `/api/projects/${projectId}/environments`, { as: owner, body: { id: "local", name: "Local", baseUrl: "http://localhost:3000" } });
+  const result = await call(env, "POST", `/api/projects/${projectId}/runs`, {
+    as: owner,
+    body: { planId: "checkout", idempotencyKey: "k4", executionMode: "cloud", environmentId: "local" },
+  });
+  assert.equal(result.status, 201, JSON.stringify(result.json));
+});
+
+test("cloud exploration of an unverified domain is refused the same way", async () => {
+  const { env, owner, projectId } = await workspace();
+  const result = await call(env, "POST", `/api/projects/${projectId}/tasks`, {
+    as: owner,
+    body: {
+      title: "Explore",
+      description: "https://shop.example.com/",
+      taskType: "discovery",
+      idempotencyKey: "t1",
+      executionMode: "cloud",
+    },
+  });
+  assert.equal(result.status, 403, JSON.stringify(result.json));
+  assert.equal(result.json.code, "domain_not_verified");
+});
+
+test("a self-hosted discovery task is never gated by domain verification", async () => {
+  const { env, owner, projectId } = await workspace();
+  const result = await call(env, "POST", `/api/projects/${projectId}/tasks`, {
+    as: owner,
+    body: {
+      title: "Explore",
+      description: "https://shop.example.com/",
+      taskType: "discovery",
+      idempotencyKey: "t2",
+      executionMode: "self",
+    },
+  });
+  assert.equal(result.status, 201, JSON.stringify(result.json));
+});
+
+test("adding a domain is limited so a workspace can't grow this table without bound", async () => {
+  const { env, workspaceId, owner } = await workspace();
+  for (let i = 0; i < 25; i += 1) {
+    const added = await call(env, "POST", `/api/workspaces/${workspaceId}/domains`, { as: owner, body: { domain: `site-${i}.example.com` } });
+    assert.equal(added.status, 201, `domain ${i}`);
+  }
+  const overLimit = await call(env, "POST", `/api/workspaces/${workspaceId}/domains`, { as: owner, body: { domain: "one-too-many.example.com" } });
+  assert.equal(overLimit.status, 422);
+});

package/src/registry-worker/domains/routes.ts

@@ -0,0 +1,139 @@
+// Workspace domain verification: prove control of a domain by DNS TXT record
+// before Bugmole Cloud will explore or run against a host on it. See
+// ../domains.ts for why, and the normalization/matching/DNS-lookup helpers.
+import {
+  domainProvesToken,
+  dohTxtLookupWith,
+  DOMAIN_VERIFY_PREFIX,
+  hostMatchesVerifiedDomain,
+  needsDomainVerification,
+  newVerificationToken,
+  normalizeDomain,
+  targetHost,
+  type TxtLookup,
+} from "../domains.js";
+import type { AuthedRouteContext } from "../routes/index.js";
+import { matchPath, registerRoutes } from "../routes/index.js";
+import type { Env } from "../core.js";
+import { memberOfWorkspace, newId, requestJson, response } from "../core.js";
+import { actorOf, recordAudit } from "../org/audit.js";
+
+const MAX_DOMAINS_PER_WORKSPACE = 25;
+
+function lookupFor(env: Env): TxtLookup {
+  return dohTxtLookupWith((env as Env & { DOMAIN_VERIFY_FETCH?: typeof fetch }).DOMAIN_VERIFY_FETCH ?? fetch);
+}
+
+type DomainRow = {
+  id: string;
+  domain: string;
+  status: "pending" | "verified";
+  createdAt: string;
+  verifiedAt: string | null;
+  lastCheckError: string | null;
+};
+
+function withRecord(row: DomainRow, token: string) {
+  return { ...row, txtRecord: { name: `${DOMAIN_VERIFY_PREFIX}.${row.domain}`, value: token } };
+}
+
+async function listDomains({ env, principal }: AuthedRouteContext, workspaceId: string): Promise<Response> {
+  if (!(await memberOfWorkspace(env, principal, workspaceId))) return response({ error: "Workspace scope is not allowed" }, 403);
+  const rows = await env.DB.prepare(`
+    SELECT id, domain, verification_token AS verificationToken, status, created_at AS createdAt, verified_at AS verifiedAt, last_check_error AS lastCheckError
+    FROM workspace_domains WHERE workspace_id = ? ORDER BY created_at ASC
+  `).bind(workspaceId).all<DomainRow & { verificationToken: string }>();
+  return response({
+    canManage: await memberOfWorkspace(env, principal, workspaceId, "workspace.manage"),
+    domains: rows.results.map(({ verificationToken, ...row }) => withRecord(row, verificationToken)),
+  });
+}
+
+async function addDomain({ env, principal, request }: AuthedRouteContext, workspaceId: string): Promise<Response> {
+  if (!(await memberOfWorkspace(env, principal, workspaceId, "workspace.manage"))) {
+    return response({ error: "Only owners and admins can add a domain" }, 403);
+  }
+  const body = await requestJson(request);
+  let domain: string;
+  try {
+    domain = normalizeDomain(typeof body?.domain === "string" ? body.domain : "");
+  } catch (error) {
+    return response({ error: error instanceof Error ? error.message : "Enter a domain such as example.com" }, 422);
+  }
+  const count = await env.DB.prepare("SELECT COUNT(*) AS count FROM workspace_domains WHERE workspace_id = ?").bind(workspaceId).first<{ count: number }>();
+  if ((count?.count ?? 0) >= MAX_DOMAINS_PER_WORKSPACE) return response({ error: `A workspace can add at most ${MAX_DOMAINS_PER_WORKSPACE} domains.` }, 422);
+  const existing = await env.DB.prepare("SELECT id, verification_token AS verificationToken, status, created_at AS createdAt, verified_at AS verifiedAt, last_check_error AS lastCheckError FROM workspace_domains WHERE workspace_id = ? AND domain = ?")
+    .bind(workspaceId, domain).first<DomainRow & { verificationToken: string }>();
+  if (existing) return response({ domain: withRecord({ ...existing, domain }, existing.verificationToken) }, 200);
+  const id = newId("dom");
+  const token = newVerificationToken();
+  await env.DB.prepare(`
+    INSERT INTO workspace_domains (id, workspace_id, domain, verification_token, created_by)
+    VALUES (?, ?, ?, ?, ?)
+  `).bind(id, workspaceId, domain, token, principal.aegisId).run();
+  await recordAudit(env, actorOf(principal), { workspaceId, action: "domain.added", targetType: "domain", targetId: id, data: { domain } }, request);
+  return response({ domain: withRecord({ id, domain, status: "pending", createdAt: new Date().toISOString(), verifiedAt: null, lastCheckError: null }, token) }, 201);
+}
+
+async function verifyDomain({ env, principal, request }: AuthedRouteContext, workspaceId: string, id: string): Promise<Response> {
+  if (!(await memberOfWorkspace(env, principal, workspaceId, "workspace.manage"))) {
+    return response({ error: "Only owners and admins can verify a domain" }, 403);
+  }
+  const row = await env.DB.prepare("SELECT domain, verification_token AS verificationToken, status FROM workspace_domains WHERE id = ? AND workspace_id = ?")
+    .bind(id, workspaceId).first<{ domain: string; verificationToken: string; status: string }>();
+  if (!row) return response({ error: "Not found" }, 404);
+  if (row.status === "verified") return response({ verified: true });
+  const proved = await domainProvesToken(row.domain, row.verificationToken, lookupFor(env));
+  if (!proved) {
+    const message = "We couldn't find that TXT record yet. DNS changes can take a while to propagate — try again shortly.";
+    await env.DB.prepare("UPDATE workspace_domains SET last_check_error = ? WHERE id = ?").bind(message, id).run();
+    return response({ error: "dns_verification_failed", message }, 400);
+  }
+  await env.DB.prepare("UPDATE workspace_domains SET status = 'verified', verified_at = ?, last_check_error = NULL WHERE id = ?")
+    .bind(new Date().toISOString(), id).run();
+  await recordAudit(env, actorOf(principal), { workspaceId, action: "domain.verified", targetType: "domain", targetId: id, data: { domain: row.domain } }, request);
+  return response({ verified: true });
+}
+
+async function removeDomain({ env, principal, request }: AuthedRouteContext, workspaceId: string, id: string): Promise<Response> {
+  if (!(await memberOfWorkspace(env, principal, workspaceId, "workspace.manage"))) {
+    return response({ error: "Only owners and admins can remove a domain" }, 403);
+  }
+  const removed = await env.DB.prepare("DELETE FROM workspace_domains WHERE id = ? AND workspace_id = ?").bind(id, workspaceId).run();
+  if ((removed.meta?.changes ?? 0) === 0) return response({ error: "Not found" }, 404);
+  await recordAudit(env, actorOf(principal), { workspaceId, action: "domain.removed", targetType: "domain", targetId: id }, request);
+  return response({ removed: true });
+}
+
+/**
+ * Gate for cloud discovery/runs: null when the target needs no verification
+ * (not a usable URL, or a private/loopback address Bugmole Cloud could
+ * never reach anyway) or the workspace has already proven the host's
+ * domain; otherwise the 403 to return, naming the domain and its TXT record
+ * so the dashboard can walk the person straight to Manage → Domains.
+ */
+export async function requireVerifiedDomainForCloud(env: Env, workspaceId: string, url: string): Promise<Response | null> {
+  const host = targetHost(url);
+  if (!host || !needsDomainVerification(host)) return null;
+  const rows = await env.DB.prepare("SELECT domain FROM workspace_domains WHERE workspace_id = ? AND status = 'verified'")
+    .bind(workspaceId).all<{ domain: string }>();
+  if (rows.results.some((row) => hostMatchesVerifiedDomain(host, row.domain))) return null;
+  return response({
+    error: `Verify that this workspace owns ${host} before running it on Bugmole Cloud.`,
+    code: "domain_not_verified",
+    domain: host,
+    manageUrl: "/manage/domains",
+  }, 403);
+}
+
+registerRoutes(async (context) => {
+  const { request, url } = context;
+  let params = matchPath(url.pathname, "/api/workspaces/:workspaceId/domains");
+  if (params && request.method === "GET") return listDomains(context, params.workspaceId);
+  if (params && request.method === "POST") return addDomain(context, params.workspaceId);
+  params = matchPath(url.pathname, "/api/workspaces/:workspaceId/domains/:domainId/verify");
+  if (params && request.method === "POST") return verifyDomain(context, params.workspaceId, params.domainId);
+  params = matchPath(url.pathname, "/api/workspaces/:workspaceId/domains/:domainId");
+  if (params && request.method === "DELETE") return removeDomain(context, params.workspaceId, params.domainId);
+  return null;
+});

package/src/registry-worker/domains.ts

@@ -0,0 +1,88 @@
+// Domain ownership: a workspace must prove it controls a domain, by DNS TXT
+// record, before Bugmole Cloud will explore or run against a host on it.
+// Without this, a workspace's cloud minutes could point Bugmole's own IPs
+// at any third-party site — using Bugmole as an anonymous crawler against a
+// domain nobody in the workspace actually owns. Self-hosted runs and
+// explorations are unaffected: those execute on the customer's own machine
+// or CI, never Bugmole's infrastructure, so there is nothing to abuse.
+import { randomToken } from "./core.js";
+
+export const DOMAIN_VERIFY_PREFIX = "_bugmole-verify";
+
+export function newVerificationToken(): string {
+  return `bugmole-domain-verify=${randomToken(20)}`;
+}
+
+/** A domain is a plain public hostname: no scheme, port, path, credentials or IP literal. */
+export function normalizeDomain(value: string): string {
+  const domain = value
+    .trim()
+    .toLowerCase()
+    .replace(/^[a-z][a-z0-9+.-]*:\/\//, "")
+    .replace(/\/.*$/, "")
+    .replace(/:\d+$/, "")
+    .replace(/\.$/, "");
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(domain) || domain.includes(":")) {
+    throw new Error("Enter a domain name, not an IP address");
+  }
+  if (!/^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(domain)) {
+    throw new Error("Enter a domain such as example.com");
+  }
+  return domain;
+}
+
+/** The host a target URL would be reached at, or null when it isn't a usable http(s) URL. */
+export function targetHost(value: string): string | null {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    return url.hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+const PRIVATE_HOSTS = /^(localhost|127\.|10\.|192\.168\.|169\.254\.|0\.0\.0\.0|::1)/;
+function isPrivateHost(rawHost: string): boolean {
+  // A URL's IPv6 hostname keeps its brackets (new URL("http://[::1]/").hostname === "[::1]").
+  const host = rawHost.replace(/^\[|\]$/g, "");
+  if (PRIVATE_HOSTS.test(host)) return true;
+  const octets = /^172\.(\d{1,3})\./.exec(host);
+  return Boolean(octets && Number(octets[1]) >= 16 && Number(octets[1]) <= 31);
+}
+
+/**
+ * A cloud run or exploration never actually reaches a private/loopback
+ * address (Bugmole Cloud has no route to a customer's own network), so
+ * there is nothing there to verify ownership of — the run simply fails to
+ * connect, exactly as it would from anywhere else on the public internet.
+ */
+export function needsDomainVerification(host: string): boolean {
+  return !isPrivateHost(host);
+}
+
+export function hostMatchesVerifiedDomain(host: string, domain: string): boolean {
+  const h = host.toLowerCase();
+  const d = domain.toLowerCase();
+  return h === d || h.endsWith(`.${d}`);
+}
+
+export type TxtLookup = (name: string) => Promise<string[]>;
+
+/** DNS-over-HTTPS TXT lookup — Workers have no native resolver. `doFetch` is overridable in tests. */
+export function dohTxtLookupWith(doFetch: typeof fetch = fetch): TxtLookup {
+  return async (name) => {
+    const url = `https://cloudflare-dns.com/dns-query?name=${encodeURIComponent(name)}&type=TXT`;
+    const res = await doFetch(url, { headers: { accept: "application/dns-json" } });
+    if (!res.ok) return [];
+    const body = await res.json() as { Answer?: Array<{ data?: string }> };
+    return (body.Answer ?? []).map((answer) => (answer.data ?? "").replace(/^"|"$/g, ""));
+  };
+}
+
+export const dohTxtLookup: TxtLookup = dohTxtLookupWith();
+
+export async function domainProvesToken(domain: string, token: string, lookup: TxtLookup = dohTxtLookup): Promise<boolean> {
+  const records = await lookup(`${DOMAIN_VERIFY_PREFIX}.${domain}`).catch(() => [] as string[]);
+  return records.includes(token);
+}

package/src/registry-worker/email/sender.ts

@@ -0,0 +1,75 @@
+// Transactional email for the registry: invitations, usage alerts, billing.
+// Brevo is the default because Aegis already sends from a verified domain
+// there; anything implementing EmailSender can replace it (tests use a
+// recording sender).
+
+export type EmailMessage = {
+  to: Array<{ email: string; name?: string }>;
+  subject: string;
+  html: string;
+  text: string;
+  /** Groups related messages in the provider's logs, e.g. "usage-alert". */
+  tag?: string;
+};
+
+export interface EmailSender {
+  send(message: EmailMessage): Promise<void>;
+}
+
+export type EmailEnv = {
+  EMAIL_SENDER?: EmailSender;
+  BREVO_API_KEY?: string;
+  EMAIL_FROM?: string;
+  EMAIL_FROM_NAME?: string;
+};
+
+export class BrevoHttpSender implements EmailSender {
+  constructor(
+    private readonly apiKey: string,
+    private readonly from: { email: string; name: string },
+    private readonly fetchImpl: typeof fetch = fetch,
+  ) {}
+
+  async send(message: EmailMessage): Promise<void> {
+    const response = await this.fetchImpl("https://api.brevo.com/v3/smtp/email", {
+      method: "POST",
+      headers: { "api-key": this.apiKey, "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({
+        sender: this.from,
+        to: message.to,
+        subject: message.subject,
+        htmlContent: message.html,
+        textContent: message.text,
+        ...(message.tag ? { tags: [message.tag] } : {}),
+      }),
+    });
+    if (!response.ok) {
+      // Brevo echoes the request on some errors; keep only the status and code.
+      const detail = await response.json().catch(() => null) as { code?: string } | null;
+      throw new Error(`Email provider rejected the message (${response.status}${detail?.code ? ` ${detail.code}` : ""})`);
+    }
+  }
+}
+
+/** Drops mail when no provider is configured, so local development never needs one. */
+class DisabledSender implements EmailSender {
+  async send(message: EmailMessage): Promise<void> {
+    console.warn(`[email] not configured; dropped "${message.subject}" to ${message.to.length} recipient(s)`);
+  }
+}
+
+export function emailSender(env: EmailEnv): EmailSender {
+  if (env.EMAIL_SENDER) return env.EMAIL_SENDER;
+  if (env.BREVO_API_KEY && env.EMAIL_FROM) {
+    return new BrevoHttpSender(env.BREVO_API_KEY, { email: env.EMAIL_FROM, name: env.EMAIL_FROM_NAME ?? "Bugmole" });
+  }
+  return new DisabledSender();
+}
+
+export function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}