dkimkit 0.0.0-stage → 0.7.0

package/dist/src/hosted/api.js

@@ -0,0 +1,919 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { ApiError, apiErrorHint, ConfigError } from '../errors.js';
+import { isValidDomain, normalizeName } from '../records.js';
+import { AccountAuth, LogMailer, SESSION_TTL_MS } from './auth.js';
+import { BillingService, WebhookSignatureError } from './billing.js';
+import { addDomains, MAX_BULK_DOMAINS, splitDomainList } from './bulk.js';
+import { EMAIL_PROVIDERS, isEmailProvider } from '../providers/email/factory.js';
+import { Vault } from './crypto.js';
+import { FEEDBACK_KINDS, MAX_FEEDBACK_LENGTH, Site } from './site.js';
+import { iso, toPublicAccount, toPublicDomain, toPublicEstimate, toPublicEvent, toPublicUsage, toWidgetDomain } from './serialize.js';
+import { ConflictError, DomainService, NotFoundError, PlanLimitError, } from './service.js';
+import { openStore, utcDay } from './store.js';
+import { MAX_SESSION_SEC, WidgetService } from './widget.js';
+import { BackgroundRunner } from './worker.js';
+const MAX_BODY_BYTES = 64 * 1024;
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const escHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const STATUSES = ['pending', 'awaiting_dns', 'verifying', 'verified', 'conflict', 'failed'];
+class HttpError extends Error {
+    status;
+    type;
+    extra;
+    constructor(status, type, message, extra = {}) {
+        super(message);
+        this.status = status;
+        this.type = type;
+        this.extra = extra;
+    }
+}
+const invalid = (message) => new HttpError(400, 'invalid_request', message);
+const WEB_DIR = new URL('../../../web/', import.meta.url);
+export function loadWidgetAssets() {
+    return {
+        loader: readFileSync(new URL('widget.js', WEB_DIR), 'utf8'),
+        frame: readFileSync(new URL('widget-frame.html', WEB_DIR), 'utf8'),
+        dashboard: readFileSync(new URL('dashboard.html', WEB_DIR), 'utf8'),
+    };
+}
+const SESSION_COOKIE = 'dkimkit_session';
+// Sessions started before the rename keep working until they expire.
+const LEGACY_SESSION_COOKIE = 'sds_session';
+/** The request handler, separate from the listener so it can be mounted elsewhere. */
+export function createApiHandler(opts) {
+    const { service, widget, auth, billing } = opts;
+    const assets = opts.assets ?? loadWidgetAssets();
+    const now = opts.now ?? Date.now;
+    const log = opts.log ?? (() => { });
+    const limiter = new RateLimiter(opts.rateLimit?.perSecond ?? 10, opts.rateLimit?.burst ?? 30);
+    // Sign-in emails: a burst of 5 per client address, then one every 12 seconds.
+    const emailLimiter = new RateLimiter(1 / 12, 5);
+    // Feedback form: a burst of 5 per client address, then one a minute.
+    const feedbackLimiter = new RateLimiter(1 / 60, 5);
+    const secureCookies = opts.publicUrl?.startsWith('https://') ?? false;
+    const requireAuth = () => {
+        if (!auth || !opts.publicUrl)
+            throw new HttpError(404, 'not_found', 'Self-serve accounts are not enabled on this server.');
+        return auth;
+    };
+    const requireBilling = () => {
+        if (!billing)
+            throw invalid('Billing is not enabled on this server.');
+        return billing;
+    };
+    const sessionCookie = (token, maxAgeSec, name = SESSION_COOKIE) => `${name}=${token}; HttpOnly; Path=/; SameSite=Lax; Max-Age=${maxAgeSec}${secureCookies ? '; Secure' : ''}`;
+    const readCookie = (req, name) => req.headers.cookie
+        ?.split(';')
+        .map((c) => c.trim().split('='))
+        .find(([k]) => k === name)?.[1];
+    const sessionToken = (req) => readCookie(req, SESSION_COOKIE) ?? readCookie(req, LEGACY_SESSION_COOKIE) ?? '';
+    const dashboardView = async (account) => ({
+        account: toPublicAccount(account),
+        email: account.email,
+        billing_enabled: Boolean(billing),
+        billing: billing ? toPublicEstimate(await billing.estimate(account)) : null,
+        feedback_enabled: Boolean(opts.site),
+        free_plan: !billing && opts.freePlan ? { free_domains: account.domainLimit ?? opts.freePlan.freeDomains, payments_coming_soon: true } : null,
+        usage: toPublicUsage(`${utcDay(now()).slice(0, 7)}-01`, utcDay(now()), await service.usage(account, `${utcDay(now()).slice(0, 7)}-01`, utcDay(now()), false), account),
+    });
+    const baseUrl = (req) => {
+        if (opts.publicUrl)
+            return opts.publicUrl.replace(/\/$/, '');
+        const proto = String(req.headers['x-forwarded-proto'] ?? 'http').split(',')[0].trim();
+        return `${proto}://${req.headers.host}`;
+    };
+    const sessionView = async (ctx) => {
+        const row = await widget.domainOf(ctx);
+        const host = row && row.status !== 'verified' ? await widget.hostOf(row.domain) : null;
+        return {
+            object: 'widget_session',
+            expires_at: iso(ctx.session.expiresAt),
+            app_name: ctx.account.name,
+            needs_domain: row === null,
+            domain: row && toWidgetDomain(row),
+            dns_host: host && { name: host.name, provider: host.provider },
+        };
+    };
+    const sendFeedback = async (form) => {
+        const label = FEEDBACK_KINDS[form.kind];
+        log('info', 'feedback received', { kind: form.kind, length: form.message.length });
+        if (!opts.feedback?.to) {
+            log('warn', 'feedback not emailed: CONTACT_EMAIL is not set', { kind: form.kind, email: form.email, message: form.message });
+            return;
+        }
+        const from = form.email || 'anonymous (no email given)';
+        const summary = form.message.replace(/\s+/g, ' ').slice(0, 60);
+        await opts.feedback.mailer.send({
+            to: opts.feedback.to,
+            subject: `${label}: ${summary}${form.message.length > 60 ? '…' : ''}`,
+            text: `${label} from ${from}\n\n${form.message}\n`,
+            html: `<p><b>${escHtml(label)}</b> from ${escHtml(from)}</p><pre style="white-space:pre-wrap;font:inherit">${escHtml(form.message)}</pre>`,
+            ...(form.email ? { replyTo: form.email } : {}),
+        });
+    };
+    const routes = [
+        ['GET', /^\/v1\/account$/, async ({ account }) => [200, toPublicAccount(account)]],
+        ['PATCH', /^\/v1\/account$/, async ({ account, body }) => [200, toPublicAccount(await service.updateAccount(account, parseAccountPatch(await body())))]],
+        ['POST', /^\/v1\/account\/rotate-api-key$/, async ({ account }) => [200, { object: 'api_key', api_key: await service.rotateApiKey(account) }]],
+        ['POST', /^\/v1\/account\/rotate-webhook-secret$/, async ({ account }) => [200, toPublicAccount(await service.rotateWebhookSecret(account))]],
+        ['GET', /^\/v1\/usage$/, async ({ account, query }) => {
+                const { from, to } = parseUsagePeriod(query, now());
+                const groupBy = query.get('group_by');
+                if (groupBy !== null && groupBy !== 'tenant')
+                    throw invalid('group_by must be "tenant".');
+                return [200, toPublicUsage(from, to, await service.usage(account, from, to, groupBy === 'tenant'), account)];
+            }],
+        ['POST', /^\/v1\/domains$/, async ({ account, body }) => [201, toPublicDomain(await service.createDomain(account, parseDomainInput(await body())))]],
+        ['GET', /^\/v1\/domains$/, async ({ account, query }) => {
+                const limit = query.has('limit') ? Number(query.get('limit')) : 20;
+                if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+                    throw invalid('limit must be an integer from 1 to 100.');
+                const status = query.get('status') ?? undefined;
+                if (status && !STATUSES.includes(status))
+                    throw invalid(`status must be one of: ${STATUSES.join(', ')}.`);
+                const page = await service.listDomains(account, {
+                    limit,
+                    tenantId: query.get('tenant_id') ?? undefined,
+                    status: status,
+                    after: query.get('starting_after') ?? undefined,
+                });
+                return [200, { object: 'list', data: page.domains.map(toPublicDomain), has_more: page.next !== null, next_cursor: page.next }];
+            }],
+        ['GET', /^\/v1\/domains\/([\w-]+)$/, async ({ account, params }) => [200, toPublicDomain(await service.getDomain(account, params[0]))]],
+        ['PATCH', /^\/v1\/domains\/([\w-]+)$/, async ({ account, params, body }) => [200, toPublicDomain(await service.updateDomain(account, params[0], parseDomainPatch(await body(), (await service.getDomain(account, params[0])).domain)))]],
+        ['DELETE', /^\/v1\/domains\/([\w-]+)$/, async ({ account, params, query }) => {
+                await service.deleteDomain(account, params[0], { remote: query.get('remote') === 'true' });
+                return [200, { id: params[0], object: 'domain', deleted: true }];
+            }],
+        ['POST', /^\/v1\/domains\/([\w-]+)\/verify$/, async ({ account, params }) => [202, toPublicDomain(await service.verifyNow(account, params[0]))]],
+        ['GET', /^\/v1\/domains\/([\w-]+)\/events$/, async ({ account, params }) => {
+                await service.getDomain(account, params[0]); // 404 unless it's this account's domain
+                return [200, { object: 'list', data: (await service.listEvents(params[0])).map(toPublicEvent) }];
+            }],
+        // Widget: sessions are minted server-side with the secret key...
+        ['POST', /^\/v1\/widget-sessions$/, async ({ req, account, body }) => {
+                const { session, token } = await widget.createSession(account, parseWidgetSession(await body()));
+                const base = baseUrl(req);
+                return [201, {
+                        object: 'widget_session',
+                        id: session.id,
+                        client_secret: token,
+                        domain_id: session.domainId,
+                        expires_at: iso(session.expiresAt),
+                        frame_url: `${base}/widget/frame?session=${token}`,
+                        script_url: `${base}/widget.js`,
+                    }];
+            }],
+        // ...and used from the browser with the session token.
+        ['GET', /^\/v1\/widget\/session$/, async (ctx) => [200, await sessionView(ctx)], 'session'],
+        ['POST', /^\/v1\/widget\/domain$/, async (ctx) => {
+                const body = await ctx.body();
+                rejectUnknown(body, ['domain']);
+                await widget.setDomain(ctx, optString(body, 'domain', 253) ?? '');
+                return [201, await sessionView(ctx)];
+            }, 'session'],
+        ['POST', /^\/v1\/widget\/connect$/, async (ctx) => {
+                const dns = parseDns(await ctx.body());
+                await widget.connect(ctx, dns.provider, dns.credentials);
+                return [200, await sessionView(ctx)];
+            }, 'session'],
+        ['POST', /^\/v1\/widget\/verify$/, async (ctx) => {
+                await widget.verify(ctx);
+                return [202, await sessionView(ctx)];
+            }, 'session'],
+        ['POST', /^\/v1\/widget\/resolve-conflicts$/, async (ctx) => {
+                await widget.resolveConflicts(ctx);
+                return [200, await sessionView(ctx)];
+            }, 'session'],
+        ['GET', /^\/widget\.js$/, async () => ({
+                status: 200,
+                headers: {
+                    'content-type': 'text/javascript; charset=utf-8',
+                    'cache-control': 'public, max-age=300',
+                    'access-control-allow-origin': '*',
+                    'x-content-type-options': 'nosniff',
+                },
+                body: assets.loader,
+            }), 'public'],
+        ['GET', /^\/widget\/frame$/, async ({ query }) => renderFrame(assets.frame, await widget.authenticate(query.get('session') ?? ''), query), 'public'],
+        // Public website: landing, pricing, docs, about, contact, feedback and legal pages, and /site.js.
+        ['GET', /^\/(pricing|about|contact|feedback|terms|privacy|refunds|site\.js|docs(\/[\w-]*)?)?$/, async ({ req }) => {
+                const path = new URL(req.url ?? '/', 'http://localhost').pathname;
+                const page = opts.site?.render(path);
+                if (page)
+                    return page;
+                // Without a site, the root goes straight to the dashboard (if sign-up is on).
+                if (path === '/' && auth && opts.publicUrl)
+                    return { status: 302, headers: { location: '/dashboard' }, body: '' };
+                throw new HttpError(404, 'not_found', `No page at ${path}.`);
+            }, 'public'],
+        // The website's feedback form: a plain HTML form post, answered with the page itself.
+        ['POST', /^\/feedback$/, async ({ req, rawBody }) => {
+                const site = opts.site;
+                if (!site)
+                    throw new HttpError(404, 'not_found', 'No page at /feedback.');
+                if (!req.headers['content-type']?.startsWith('application/x-www-form-urlencoded')) {
+                    throw new HttpError(415, 'unsupported_media_type', 'Send the feedback form.');
+                }
+                const fields = new URLSearchParams(await rawBody());
+                const kind = (fields.get('kind') ?? '') in FEEDBACK_KINDS ? fields.get('kind') : 'feedback';
+                const form = { kind, message: (fields.get('message') ?? '').trim(), email: (fields.get('email') ?? '').trim() };
+                // Bots fill in the hidden field; they're thanked and nothing is sent.
+                if (fields.get('website'))
+                    return site.feedbackPage({ ...form, sent: true });
+                if (!form.message)
+                    return site.feedbackPage({ ...form, error: 'Please write a message.' });
+                if (form.message.length > MAX_FEEDBACK_LENGTH) {
+                    return site.feedbackPage({ ...form, error: `Please keep it under ${MAX_FEEDBACK_LENGTH} characters.` });
+                }
+                if (form.email && (form.email.length > 254 || !EMAIL_RE.test(form.email))) {
+                    return site.feedbackPage({ ...form, error: 'That email address doesn’t look right. Fix it, or leave it empty.' });
+                }
+                if (feedbackLimiter.take(`ip:${req.socket.remoteAddress}`, now()) > 0) {
+                    return { ...site.feedbackPage({ ...form, error: 'You’ve sent a lot of feedback in a short time. Please wait a minute and try again.' }), status: 429 };
+                }
+                await sendFeedback(form);
+                return site.feedbackPage({ ...form, sent: true });
+            }, 'public'],
+        // Self-serve accounts: passwordless email links and the dashboard.
+        ['GET', /^\/(signup|login)$/, async () => {
+                requireAuth();
+                return { status: 302, headers: { location: '/dashboard' }, body: '' };
+            }, 'public'],
+        ['GET', /^\/dashboard$/, async () => {
+                requireAuth();
+                return renderDashboard(assets.dashboard, opts.site?.appName ?? 'DKIMkit', billing?.freeDomains ?? opts.freePlan?.freeDomains);
+            }, 'public'],
+        ['POST', /^\/v1\/auth\/email-link$/, async ({ req, body }) => {
+                const accountAuth = requireAuth();
+                const retryAfter = emailLimiter.take(`ip:${req.socket.remoteAddress}`, now());
+                if (retryAfter > 0) {
+                    throw new HttpError(429, 'rate_limited', 'Too many sign-in emails. Please wait a minute and try again.');
+                }
+                const input = await body();
+                rejectUnknown(input, ['email', 'name']);
+                await accountAuth.requestLink(optString(input, 'email', 254) ?? '', optString(input, 'name', 100));
+                // Same response whether or not the account exists.
+                return [202, { ok: true }];
+            }, 'public'],
+        ['GET', /^\/auth\/callback$/, async ({ query }) => {
+                const accountAuth = requireAuth();
+                try {
+                    const { sessionToken, created } = await accountAuth.completeLink(query.get('token') ?? '');
+                    return {
+                        status: 303,
+                        headers: { location: created ? '/dashboard?welcome=1' : '/dashboard', 'set-cookie': sessionCookie(sessionToken, SESSION_TTL_MS / 1000), 'cache-control': 'no-store' },
+                        body: '',
+                    };
+                }
+                catch (err) {
+                    if (!(err instanceof ConfigError))
+                        throw err;
+                    return { status: 303, headers: { location: '/dashboard?link=expired', 'cache-control': 'no-store' }, body: '' };
+                }
+            }, 'public'],
+        ['GET', /^\/dashboard\/api\/me$/, async ({ account }) => [200, await dashboardView(account)], 'dashboard'],
+        ['POST', /^\/dashboard\/api\/logout$/, async ({ req }) => {
+                await requireAuth().logout(sessionToken(req));
+                const cleared = [sessionCookie('', 0), sessionCookie('', 0, LEGACY_SESSION_COOKIE)];
+                return { status: 200, headers: { 'set-cookie': cleared, 'content-type': 'application/json' }, body: '{"ok":true}' };
+            }, 'dashboard'],
+        ['POST', /^\/dashboard\/api\/api-key$/, async ({ account }) => [200, { object: 'api_key', api_key: await service.rotateApiKey(account) }], 'dashboard'],
+        ['PATCH', /^\/dashboard\/api\/account$/, async ({ account, body }) => {
+                const updated = await service.updateAccount(account, parseAccountPatch(await body()));
+                return [200, await dashboardView(updated)];
+            }, 'dashboard'],
+        ['GET', /^\/dashboard\/api\/domains$/, async ({ account }) => {
+                const rows = [];
+                for (let after; rows.length < 1000;) {
+                    const page = await service.listDomains(account, { limit: 100, after });
+                    rows.push(...page.domains);
+                    if (page.next === null)
+                        break;
+                    after = page.next;
+                }
+                // Where each unfinished domain's DNS lives, so the dashboard can group records by DNS host.
+                const hosts = await Promise.all(rows.map((r) => (r.status === 'verified' ? null : widget.hostOf(r.domain).catch(() => null))));
+                return [200, { object: 'list', data: rows.map((r, i) => ({ ...toPublicDomain(r), dns_host: hosts[i] ? { name: hosts[i].name, provider: hosts[i].provider } : null })) }];
+            }, 'dashboard'],
+        ['POST', /^\/dashboard\/api\/domains$/, async ({ account, body }) => {
+                const input = parseBulkInput(await body());
+                const results = await addDomains(service, (d) => widget.hostOf(d), account, input);
+                return [200, {
+                        object: 'bulk_result',
+                        data: [
+                            ...results.map((r) => r.ok
+                                ? { domain: r.domain, ok: true, id: r.row.id, dns: r.row.dnsProvider, dns_host: r.host.name }
+                                : { domain: r.domain, ok: false, error: { type: toHttpError(r.error).type, message: toHttpError(r.error).message } }),
+                            ...input.invalid.map((entry) => ({ domain: entry, ok: false, error: { type: 'invalid_request', message: 'Not a valid domain name.' } })),
+                        ],
+                    }];
+            }, 'dashboard'],
+        ['POST', /^\/dashboard\/api\/domains\/([\w-]+)\/verify$/, async ({ account, params }) => [200, toPublicDomain(await service.verifyNow(account, params[0]))], 'dashboard'],
+        ['DELETE', /^\/dashboard\/api\/domains\/([\w-]+)$/, async ({ account, params }) => {
+                // Also removes the domain and its inbound route at the email provider. DNS records are left alone.
+                await service.deleteDomain(account, params[0], { remote: true });
+                return [200, { id: params[0], object: 'domain', deleted: true }];
+            }, 'dashboard'],
+        ['POST', /^\/dashboard\/api\/checkout$/, async ({ account }) => [200, { url: await requireBilling().checkoutUrl(account) }], 'dashboard'],
+        ['POST', /^\/dashboard\/api\/portal$/, async ({ account }) => [200, { url: await requireBilling().portalUrl(account) }], 'dashboard'],
+        // Payment provider → us. Authenticated by the provider's signature over the raw body.
+        ['POST', /^\/billing\/webhook$/, async ({ req, rawBody }) => {
+                const result = await requireBilling().handleWebhook(await rawBody(), req.headers);
+                return [200, { received: true, result }];
+            }, 'public'],
+    ];
+    return async (req, res) => {
+        const started = now();
+        const requestId = typeof req.headers['x-request-id'] === 'string' ? req.headers['x-request-id'].slice(0, 64) : randomUUID();
+        res.setHeader('x-request-id', requestId);
+        let accountId;
+        let status = 500;
+        try {
+            const url = new URL(req.url ?? '/', 'http://localhost');
+            if (req.method === 'GET' && url.pathname === '/healthz') {
+                status = 200;
+                return sendJson(res, 200, { ok: true });
+            }
+            const matching = routes.filter(([, re]) => re.test(url.pathname));
+            if (matching.length === 0)
+                throw new HttpError(404, 'not_found', `No route for ${url.pathname}.`);
+            const route = matching.find(([method]) => method === req.method);
+            if (!route)
+                throw new HttpError(405, 'method_not_allowed', `${req.method} is not supported here.`);
+            const [, re, handler, auth = 'account'] = route;
+            let account;
+            let session;
+            if (auth === 'dashboard') {
+                const accountAuth = requireAuth();
+                // Cookie-authenticated writes must come from our own pages (CSRF).
+                if (req.method !== 'GET' && req.headers.origin !== new URL(opts.publicUrl).origin) {
+                    throw new HttpError(403, 'forbidden', 'Cross-site request rejected.');
+                }
+                account = await accountAuth.sessionAccount(sessionToken(req));
+                if (!account)
+                    throw new HttpError(401, 'unauthorized', 'Please sign in.');
+                accountId = account.id;
+                const retryAfter = limiter.take(account.id, now());
+                if (retryAfter > 0)
+                    throw new HttpError(429, 'rate_limited', 'Too many requests.');
+            }
+            else if (auth !== 'public') {
+                const key = /^Bearer\s+(\S+)$/i.exec(req.headers.authorization ?? '')?.[1] ?? '';
+                if (auth === 'session') {
+                    const ctx = key.startsWith('wss_') ? await widget.authenticate(key) : undefined;
+                    if (!ctx)
+                        throw new HttpError(401, 'session_expired', 'This setup session has expired. Reload the page to start again.');
+                    ({ account, session } = ctx);
+                }
+                else {
+                    account = key && !key.startsWith('wss_') ? await service.authenticate(key) : undefined;
+                    if (!account)
+                        throw new HttpError(401, 'unauthorized', 'Missing or invalid API key. Send Authorization: Bearer <key>.');
+                }
+                accountId = account.id;
+                const retryAfter = limiter.take(session?.id ?? account.id, now());
+                if (retryAfter > 0) {
+                    res.setHeader('retry-after', String(Math.ceil(retryAfter / 1000)));
+                    throw new HttpError(429, 'rate_limited', 'Too many requests.');
+                }
+            }
+            const result = await handler({
+                req,
+                account: account,
+                session: session,
+                params: re.exec(url.pathname).slice(1),
+                query: url.searchParams,
+                body: () => readJsonObject(req),
+                rawBody: () => readRawBody(req),
+            });
+            if (Array.isArray(result)) {
+                status = result[0];
+                sendJson(res, result[0], result[1]);
+            }
+            else {
+                status = result.status;
+                res.writeHead(result.status, result.headers);
+                res.end(result.body);
+            }
+        }
+        catch (err) {
+            const e = toHttpError(err);
+            status = e.status;
+            if (e.status === 500)
+                log('error', 'request failed', { request_id: requestId, error: err instanceof Error ? err.stack : String(err) });
+            else if (e.status === 502)
+                log('warn', 'provider rejected request', { request_id: requestId, error: e.message });
+            sendJson(res, e.status, { error: { type: e.type, message: e.message, request_id: requestId, ...e.extra } });
+        }
+        finally {
+            log('info', 'request', { request_id: requestId, method: req.method, path: req.url?.split('?')[0], status, ms: now() - started, account_id: accountId });
+        }
+    };
+}
+function toHttpError(err) {
+    if (err instanceof HttpError)
+        return err;
+    if (err instanceof ConfigError)
+        return invalid(err.message);
+    if (err instanceof NotFoundError)
+        return new HttpError(404, 'not_found', err.message);
+    if (err instanceof PlanLimitError) {
+        return new HttpError(402, 'plan_limit_reached', err.message, { domain_limit: err.limit, ...(err.upgradeUrl ? { upgrade_url: err.upgradeUrl } : {}) });
+    }
+    if (err instanceof WebhookSignatureError)
+        return new HttpError(400, 'invalid_signature', err.message);
+    if (err instanceof ConflictError) {
+        return new HttpError(409, 'conflict', err.message, err.existingId ? { existing_id: err.existingId } : {});
+    }
+    if (err instanceof ApiError) {
+        return new HttpError(502, 'provider_error', err.message, {
+            provider: err.provider,
+            provider_status: err.status,
+            ...(apiErrorHint(err) ? { hint: apiErrorHint(err) } : {}),
+        });
+    }
+    return new HttpError(500, 'internal_error', 'Something went wrong on our side.');
+}
+// ---- input parsing ----
+const DAY_RE = /^\d{4}-\d{2}-\d{2}$/;
+/** from/to as inclusive UTC days; defaults to the current calendar month so far. */
+export function parseUsagePeriod(query, now) {
+    const today = new Date(now).toISOString().slice(0, 10);
+    const from = query.get('from') ?? `${today.slice(0, 7)}-01`;
+    const to = query.get('to') ?? today;
+    for (const [name, day] of [['from', from], ['to', to]]) {
+        if (!DAY_RE.test(day) || Number.isNaN(Date.parse(`${day}T00:00:00Z`)) || new Date(`${day}T00:00:00Z`).toISOString().slice(0, 10) !== day) {
+            throw invalid(`${name} must be a date like 2026-10-01.`);
+        }
+    }
+    if (from > to)
+        throw invalid('from must not be after to.');
+    if ((Date.parse(`${to}T00:00:00Z`) - Date.parse(`${from}T00:00:00Z`)) / 86_400_000 > 366)
+        throw invalid('The period can be at most 366 days.');
+    return { from, to };
+}
+function rejectUnknown(body, allowed, prefix = '') {
+    const unknown = Object.keys(body).filter((k) => !allowed.includes(k));
+    if (unknown.length > 0)
+        throw invalid(`Unknown field${unknown.length > 1 ? 's' : ''}: ${unknown.map((k) => prefix + k).join(', ')}.`);
+}
+function optString(body, key, max, label = key) {
+    const v = body[key];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== 'string' || v.length > max)
+        throw invalid(`${label} must be a string of at most ${max} characters.`);
+    return v.trim() || undefined;
+}
+function optBool(body, key, label = key) {
+    const v = body[key];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== 'boolean')
+        throw invalid(`${label} must be true or false.`);
+    return v;
+}
+function asObject(v, label) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        throw invalid(`${label} must be an object.`);
+    return v;
+}
+function parseMetadata(v) {
+    const obj = asObject(v, 'metadata');
+    const entries = Object.entries(obj);
+    if (entries.length > 20)
+        throw invalid('metadata can have at most 20 keys.');
+    for (const [k, val] of entries) {
+        if (k.length > 40 || typeof val !== 'string' || val.length > 500) {
+            throw invalid('metadata keys must be at most 40 characters and values strings of at most 500.');
+        }
+    }
+    return obj;
+}
+/** Without a hostname, the email provider's default applies (e.g. parse.<domain>, or the domain itself for Mailgun). */
+function parseInbound(v, domain) {
+    if (v === null)
+        return null;
+    const obj = asObject(v, 'inbound');
+    rejectUnknown(obj, ['url', 'hostname', 'spam_check', 'send_raw'], 'inbound.');
+    const url = optString(obj, 'url', 2048, 'inbound.url');
+    if (!url || !/^https:\/\/\S+$/.test(url))
+        throw invalid('inbound.url must be an https:// URL.');
+    const given = optString(obj, 'hostname', 253, 'inbound.hostname');
+    const hostname = given === undefined ? undefined : normalizeName(given);
+    if (hostname !== undefined && (!isValidDomain(hostname) || !(hostname === domain || hostname.endsWith(`.${domain}`)))) {
+        throw invalid(`inbound.hostname must be ${domain} or a subdomain of it.`);
+    }
+    return { url, ...(hostname ? { hostname } : {}), spamCheck: optBool(obj, 'spam_check', 'inbound.spam_check') ?? false, sendRaw: optBool(obj, 'send_raw', 'inbound.send_raw') ?? false };
+}
+function parseDns(v) {
+    const obj = asObject(v, 'dns');
+    rejectUnknown(obj, ['provider', 'cloudflare_api_token', 'aws_access_key_id', 'aws_secret_access_key', 'aws_session_token', 'route53_hosted_zone_id'], 'dns.');
+    const provider = optString(obj, 'provider', 20, 'dns.provider');
+    if (!provider)
+        throw invalid('dns.provider is required.');
+    return {
+        provider,
+        credentials: {
+            cloudflareApiToken: optString(obj, 'cloudflare_api_token', 200, 'dns.cloudflare_api_token'),
+            awsAccessKeyId: optString(obj, 'aws_access_key_id', 128, 'dns.aws_access_key_id'),
+            awsSecretAccessKey: optString(obj, 'aws_secret_access_key', 128, 'dns.aws_secret_access_key'),
+            awsSessionToken: optString(obj, 'aws_session_token', 4096, 'dns.aws_session_token'),
+            route53HostedZoneId: optString(obj, 'route53_hosted_zone_id', 64, 'dns.route53_hosted_zone_id'),
+        },
+    };
+}
+export function parseDomainInput(body) {
+    rejectUnknown(body, ['domain', 'subdomain', 'tenant_id', 'metadata', 'sendgrid_subuser', 'inbound', 'dns', 'overwrite']);
+    const domain = normalizeName(optString(body, 'domain', 253) ?? '');
+    if (!isValidDomain(domain))
+        throw invalid('domain must be a valid domain name, like example.com.');
+    const subdomain = optString(body, 'subdomain', 63);
+    if (subdomain && !/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/i.test(subdomain))
+        throw invalid('subdomain must be a single DNS label, like "em".');
+    const dns = body.dns === undefined ? { provider: 'manual', credentials: {} } : parseDns(body.dns);
+    return {
+        domain,
+        subdomain: subdomain?.toLowerCase() ?? null,
+        tenantId: optString(body, 'tenant_id', 128) ?? null,
+        metadata: body.metadata === undefined ? {} : parseMetadata(body.metadata),
+        sendgridSubuser: optString(body, 'sendgrid_subuser', 64) ?? null,
+        inbound: body.inbound === undefined ? null : parseInbound(body.inbound, domain),
+        dnsProvider: dns.provider,
+        dnsCredentials: dns.credentials,
+        overwrite: optBool(body, 'overwrite') ?? false,
+    };
+}
+function parseDomainPatch(body, domain) {
+    rejectUnknown(body, ['tenant_id', 'metadata', 'inbound', 'dns', 'overwrite']);
+    const patch = {};
+    if ('tenant_id' in body)
+        patch.tenantId = optString(body, 'tenant_id', 128) ?? null;
+    if (body.metadata !== undefined)
+        patch.metadata = parseMetadata(body.metadata);
+    if (body.inbound !== undefined)
+        patch.inbound = parseInbound(body.inbound, domain);
+    if (body.dns !== undefined) {
+        const dns = parseDns(body.dns);
+        patch.dnsProvider = dns.provider;
+        patch.dnsCredentials = Object.fromEntries(Object.entries(dns.credentials).filter(([, v]) => v !== undefined));
+    }
+    const overwrite = optBool(body, 'overwrite');
+    if (overwrite !== undefined)
+        patch.overwrite = overwrite;
+    return patch;
+}
+/** Dashboard bulk add: `domains` is pasted text (one per line or comma separated) or an array. */
+function parseBulkInput(body) {
+    rejectUnknown(body, ['domains', 'inbound', 'cloudflare_api_token', 'aws_access_key_id', 'aws_secret_access_key']);
+    const raw = body.domains;
+    if (typeof raw !== 'string' && !(Array.isArray(raw) && raw.every((d) => typeof d === 'string'))) {
+        throw invalid('domains must be text with one domain per line, or an array of domains.');
+    }
+    const { domains, invalid: bad } = splitDomainList(Array.isArray(raw) ? raw.join('\n') : raw);
+    if (domains.length === 0 && bad.length === 0)
+        throw invalid('Enter at least one domain.');
+    if (domains.length > MAX_BULK_DOMAINS)
+        throw invalid(`Add at most ${MAX_BULK_DOMAINS} domains at a time.`);
+    let inbound = null;
+    if (body.inbound !== undefined && body.inbound !== null) {
+        const obj = asObject(body.inbound, 'inbound');
+        rejectUnknown(obj, ['url', 'hostname_prefix'], 'inbound.');
+        const url = optString(obj, 'url', 2048, 'inbound.url');
+        if (!url || !/^https:\/\/\S+$/.test(url))
+            throw invalid('inbound.url must be an https:// URL.');
+        const prefix = optString(obj, 'hostname_prefix', 63, 'inbound.hostname_prefix')?.toLowerCase();
+        if (prefix && !/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(prefix))
+            throw invalid('inbound.hostname_prefix must be a single DNS label, like "parse".');
+        inbound = { url, ...(prefix ? { hostnamePrefix: prefix } : {}) };
+    }
+    const accessKeyId = optString(body, 'aws_access_key_id', 128);
+    const secretAccessKey = optString(body, 'aws_secret_access_key', 128);
+    if (Boolean(accessKeyId) !== Boolean(secretAccessKey))
+        throw invalid('Enter both the AWS access key ID and secret access key, or neither.');
+    return {
+        domains,
+        invalid: bad,
+        inbound,
+        cloudflareApiToken: optString(body, 'cloudflare_api_token', 200),
+        ...(accessKeyId && secretAccessKey ? { aws: { accessKeyId, secretAccessKey } } : {}),
+    };
+}
+const EMAIL_CREDENTIAL_FIELDS = [
+    ['api_key', 'apiKey', 300],
+    ['account_token', 'accountToken', 200],
+    ['inbound_server_id', 'inboundServerId', 40],
+    ['region', 'region', 40],
+    ['access_key_id', 'accessKeyId', 128],
+    ['secret_access_key', 'secretAccessKey', 128],
+    ['session_token', 'sessionToken', 4096],
+];
+/** `email_provider: { provider: "postmark", account_token: "…" }`, etc. Fields left out keep their saved values. */
+function parseEmailProvider(v) {
+    const obj = asObject(v, 'email_provider');
+    rejectUnknown(obj, ['provider', ...EMAIL_CREDENTIAL_FIELDS.map(([f]) => f)], 'email_provider.');
+    const provider = optString(obj, 'provider', 20, 'email_provider.provider');
+    if (!provider || !isEmailProvider(provider))
+        throw invalid(`email_provider.provider must be one of: ${EMAIL_PROVIDERS.join(', ')}.`);
+    const credentials = {};
+    for (const [field, key, max] of EMAIL_CREDENTIAL_FIELDS) {
+        const value = optString(obj, field, max, `email_provider.${field}`);
+        if (value !== undefined)
+            credentials[key] = value;
+    }
+    return { provider, credentials };
+}
+function parseAccountPatch(body) {
+    rejectUnknown(body, ['name', 'webhook_url', 'sendgrid_api_key', 'email_provider', 'widget_origins']);
+    const patch = {};
+    const name = optString(body, 'name', 200);
+    if (name !== undefined)
+        patch.name = name;
+    if ('webhook_url' in body)
+        patch.webhookUrl = optString(body, 'webhook_url', 2048) ?? null;
+    const key = optString(body, 'sendgrid_api_key', 200);
+    if (key !== undefined)
+        patch.sendgridApiKey = key;
+    if (body.email_provider !== undefined)
+        patch.emailProvider = parseEmailProvider(body.email_provider);
+    if (body.widget_origins !== undefined)
+        patch.widgetOrigins = parseOrigins(body.widget_origins);
+    return patch;
+}
+const LOCAL_HOSTS = ['localhost', '127.0.0.1', '[::1]'];
+function parseOrigins(v) {
+    if (!Array.isArray(v) || v.length > 20)
+        throw invalid('widget_origins must be an array of at most 20 origins.');
+    return v.map((o) => {
+        const hint = `widget_origins entries must be origins like https://app.example.com (http:// only for localhost): ${String(o)}`;
+        if (typeof o !== 'string')
+            throw invalid(hint);
+        let url;
+        try {
+            url = new URL(o);
+        }
+        catch {
+            throw invalid(hint);
+        }
+        const secure = url.protocol === 'https:' || (url.protocol === 'http:' && LOCAL_HOSTS.includes(url.hostname));
+        if (!secure || url.origin !== o.replace(/\/$/, ''))
+            throw invalid(hint);
+        return url.origin;
+    });
+}
+function parseWidgetSession(body) {
+    rejectUnknown(body, ['domain_id', 'tenant_id', 'metadata', 'subdomain', 'sendgrid_subuser', 'inbound_url', 'expires_in']);
+    let expiresInSec;
+    if (body.expires_in !== undefined) {
+        expiresInSec = Number(body.expires_in);
+        if (!Number.isInteger(expiresInSec) || expiresInSec < 60 || expiresInSec > MAX_SESSION_SEC) {
+            throw invalid(`expires_in must be between 60 and ${MAX_SESSION_SEC} seconds.`);
+        }
+    }
+    const domainId = optString(body, 'domain_id', 64);
+    const tenantId = optString(body, 'tenant_id', 128);
+    if (domainId) {
+        if (Object.keys(body).some((k) => k !== 'domain_id' && k !== 'expires_in')) {
+            throw invalid('With domain_id, the domain\'s own settings apply; pass only domain_id and expires_in.');
+        }
+        return { domainId, expiresInSec };
+    }
+    if (!tenantId)
+        throw invalid('Pass domain_id for an existing domain, or tenant_id to let the user enter their domain.');
+    const inboundUrl = optString(body, 'inbound_url', 2048) ?? null;
+    if (inboundUrl && !/^https:\/\/\S+$/.test(inboundUrl))
+        throw invalid('inbound_url must be an https:// URL.');
+    const subdomain = optString(body, 'subdomain', 63)?.toLowerCase() ?? null;
+    if (subdomain && !/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(subdomain))
+        throw invalid('subdomain must be a single DNS label, like "em".');
+    return {
+        expiresInSec,
+        defaults: {
+            tenantId,
+            metadata: body.metadata === undefined ? {} : parseMetadata(body.metadata),
+            subdomain,
+            sendgridSubuser: optString(body, 'sendgrid_subuser', 64) ?? null,
+            inboundUrl,
+        },
+    };
+}
+// ---- widget frame ----
+const THEME_MODES = ['light', 'dark', 'auto'];
+/** The iframe page. Embeddable only by the account's widget origins, since users type credentials into it. */
+function renderFrame(template, ctx, query) {
+    const nonce = randomBytes(16).toString('base64');
+    const accent = query.get('accent') ?? '';
+    // Number(null) is 0, so an absent radius must not count as an explicit 0.
+    const radius = query.has('radius') ? Number(query.get('radius')) : NaN;
+    const config = {
+        allowedOrigins: ctx?.account.widgetOrigins ?? [],
+        valid: Boolean(ctx),
+        theme: {
+            accent: /^#[0-9a-f]{6}$/i.test(accent) ? accent : null,
+            // Light unless the host opts in: matching the host page matters more than the OS setting.
+            mode: THEME_MODES.includes(query.get('mode') ?? '') ? query.get('mode') : 'light',
+            radius: Number.isInteger(radius) && radius >= 0 && radius <= 24 ? radius : null,
+        },
+    };
+    const ancestors = ctx ? ctx.account.widgetOrigins.join(' ') : "'none'";
+    return {
+        status: ctx ? 200 : 401,
+        headers: {
+            'content-type': 'text/html; charset=utf-8',
+            'cache-control': 'no-store',
+            'referrer-policy': 'no-referrer',
+            'x-content-type-options': 'nosniff',
+            'content-security-policy': [
+                "default-src 'none'",
+                `script-src 'nonce-${nonce}'`,
+                "style-src 'unsafe-inline'",
+                "img-src 'self' data:",
+                "connect-src 'self'",
+                "base-uri 'none'",
+                "form-action 'none'",
+                `frame-ancestors ${ancestors}`,
+            ].join('; '),
+        },
+        body: template
+            .replaceAll('__NONCE__', nonce)
+            // A function replacement, so `$` sequences in the JSON are never treated as patterns.
+            .replace('__CONFIG__', () => JSON.stringify(config).replace(/</g, '\\u003c')),
+    };
+}
+/** The account dashboard (sign-in and billing). Never framed; scripts by nonce only. */
+/** `freeDomains`: the free plan's limit, shown on the sign-in screen. */
+function renderDashboard(template, appName, freeDomains) {
+    const nonce = randomBytes(16).toString('base64');
+    const name = appName.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    return {
+        status: 200,
+        headers: {
+            'content-type': 'text/html; charset=utf-8',
+            'cache-control': 'no-store',
+            'referrer-policy': 'same-origin',
+            'x-content-type-options': 'nosniff',
+            'content-security-policy': [
+                "default-src 'none'",
+                `script-src 'nonce-${nonce}'`,
+                "style-src 'unsafe-inline'",
+                "img-src 'self' data:",
+                "connect-src 'self'",
+                "base-uri 'none'",
+                "form-action 'self'",
+                "frame-ancestors 'none'",
+            ].join('; '),
+        },
+        // Function replacements, so `$` in the name is never treated as a pattern.
+        body: template
+            .replaceAll('__NONCE__', nonce)
+            .replaceAll('__APP_NAME__', () => name)
+            .replaceAll('__FREE_DOMAINS__', freeDomains === undefined ? '' : String(freeDomains)),
+    };
+}
+// ---- plumbing ----
+/** The exact request body, for signature verification. */
+async function readRawBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > 1024 * 1024)
+            throw new HttpError(413, 'payload_too_large', 'Request body is too large.');
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+async function readJsonObject(req) {
+    if (!req.headers['content-type']?.startsWith('application/json')) {
+        throw new HttpError(415, 'unsupported_media_type', 'Send Content-Type: application/json.');
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            throw new HttpError(413, 'payload_too_large', 'Request body is too large.');
+        chunks.push(chunk);
+    }
+    let body;
+    try {
+        body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+    }
+    catch {
+        throw invalid('Request body is not valid JSON.');
+    }
+    return asObject(body, 'Request body');
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+    res.end(JSON.stringify(body));
+}
+/** Token bucket per account. Returns 0 when allowed, else ms until a token is available. */
+class RateLimiter {
+    perSecond;
+    burst;
+    buckets = new Map();
+    constructor(perSecond, burst) {
+        this.perSecond = perSecond;
+        this.burst = burst;
+    }
+    take(key, now) {
+        const bucket = this.buckets.get(key) ?? { tokens: this.burst, at: now };
+        bucket.tokens = Math.min(this.burst, bucket.tokens + ((now - bucket.at) / 1000) * this.perSecond);
+        bucket.at = now;
+        this.buckets.set(key, bucket);
+        if (bucket.tokens >= 1) {
+            bucket.tokens -= 1;
+            return 0;
+        }
+        return ((1 - bucket.tokens) / this.perSecond) * 1000;
+    }
+}
+/** The free plan's cap before payments launch. An operator-set domain limit replaces it. */
+function freePlanCap(plan, contactEmail) {
+    const n = plan.freeDomains;
+    return (account) => account.domainLimit !== null
+        ? null
+        : {
+            limit: n,
+            message: `The free plan includes ${n} domain${n === 1 ? '' : 's'}. Paid plans with more domains are coming soon${contactEmail ? `; email ${contactEmail} if you need more now` : ''}.`,
+        };
+}
+export async function startHostedApi(opts) {
+    if ((opts.signup || opts.billing || opts.site) && !opts.publicUrl) {
+        throw new ConfigError('Sign-up, billing and the website need a public URL (PUBLIC_URL).');
+    }
+    const store = opts.store ?? (await openStore(opts.database ?? ':memory:'));
+    const publicUrl = opts.publicUrl?.replace(/\/$/, '');
+    const billing = opts.billing ? new BillingService(store, opts.billing, { publicUrl: publicUrl, now: opts.now, log: opts.log }) : undefined;
+    const freePlan = billing ? undefined : opts.freePlan;
+    const service = new DomainService({
+        store,
+        vault: new Vault(opts.encryptionKey),
+        providers: opts.providers,
+        lookup: opts.lookup,
+        now: opts.now,
+        allowPrivateWebhooks: opts.allowPrivateWebhooks,
+        planCap: billing?.planCap ?? (freePlan && freePlanCap(freePlan, opts.site?.contactEmail)),
+        log: opts.log,
+    });
+    const auth = opts.signup
+        ? new AccountAuth(store, service, opts.signup.mailer ?? new LogMailer(opts.log ?? (() => { })), {
+            publicUrl: publicUrl,
+            appName: opts.signup.appName ?? opts.site?.appName,
+            now: opts.now,
+        })
+        : undefined;
+    const site = opts.site
+        ? new Site({
+            ...opts.site,
+            publicUrl: publicUrl,
+            signupEnabled: Boolean(auth),
+            plan: billing
+                ? { freeDomains: billing.freeDomains, unitAmount: billing.unitAmount, currency: billing.currency, provider: billing.provider.name }
+                : freePlan && { freeDomains: freePlan.freeDomains, unitAmount: 0, currency: 'usd', provider: '', comingSoon: true },
+        })
+        : undefined;
+    const runner = new BackgroundRunner(service, store, {
+        ...opts.runner,
+        now: opts.now,
+        fetch: opts.fetch,
+        allowPrivateWebhooks: opts.allowPrivateWebhooks,
+        billing,
+        log: opts.log,
+    });
+    const widget = new WidgetService(service, store, { now: opts.now, detectHost: opts.detectHost });
+    const feedback = site && { mailer: opts.signup?.mailer ?? new LogMailer(opts.log ?? (() => { })), to: opts.site?.contactEmail };
+    const handler = createApiHandler({ service, widget, auth, billing, freePlan, site, feedback, publicUrl, rateLimit: opts.rateLimit, now: opts.now, log: opts.log });
+    const server = createServer((req, res) => void handler(req, res));
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(opts.port ?? 8080, opts.host ?? '0.0.0.0', () => resolve());
+    });
+    if (opts.workers !== false)
+        runner.start();
+    const { port } = server.address();
+    return {
+        url: `http://${opts.host === '0.0.0.0' || !opts.host ? '127.0.0.1' : opts.host}:${port}`,
+        port,
+        server,
+        store,
+        service,
+        runner,
+        billing,
+        auth,
+        site,
+        async close() {
+            await new Promise((resolve) => {
+                server.close(() => resolve());
+                server.closeIdleConnections();
+            });
+            await runner.stop();
+            await store.close();
+        },
+    };
+}
+//# sourceMappingURL=api.js.map