dkimkit 0.0.0-stage → 0.7.0

package/dist/src/providers/email/ses.js

@@ -0,0 +1,123 @@
+import { ApiError, ConfigError } from '../../errors.js';
+import { requestText } from '../../http.js';
+import { normalizeName } from '../../records.js';
+import { signRequest } from '../dns/aws.js';
+const INBOUND_UNSUPPORTED = 'Receiving email with Amazon SES isn’t supported yet. Use SendGrid, Postmark or Mailgun for inbound mail.';
+/**
+ * Amazon SES (API v2) domain identities with Easy DKIM (three CNAMEs) and a
+ * custom MAIL FROM subdomain (an MX for bounces and an SPF TXT). SES checks DNS
+ * by itself, so "validate" reads the current status.
+ */
+export class SesProvider {
+    opts;
+    name = 'ses';
+    label = 'Amazon SES';
+    supportsInbound = false;
+    baseUrl;
+    fetchImpl;
+    constructor(opts) {
+        this.opts = opts;
+        if (!/^[a-z]{2}(-[a-z]+)+-\d$/.test(opts.region))
+            throw new ConfigError(`"${opts.region}" isn’t an AWS region (e.g. us-east-1).`);
+        this.baseUrl = opts.baseUrl ?? `https://email.${opts.region}.amazonaws.com`;
+        this.fetchImpl = opts.fetch ?? fetch;
+    }
+    defaultInboundHostname(domain) {
+        return `parse.${normalizeName(domain)}`;
+    }
+    async findDomain(domain) {
+        const name = normalizeName(domain);
+        try {
+            return this.toAuthentication(name, await this.identity(name), false);
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    /** `subdomain` is the MAIL FROM label (default "mail", giving mail.<domain>). */
+    async ensureDomain(domain, opts = {}) {
+        const existing = await this.findDomain(domain);
+        if (existing)
+            return existing;
+        const name = normalizeName(domain);
+        await this.request('POST', '/v2/email/identities', { EmailIdentity: name });
+        await this.request('PUT', `/v2/email/identities/${encodeURIComponent(name)}/mail-from`, {
+            MailFromDomain: `${opts.subdomain ?? 'mail'}.${name}`,
+            // Until the MX is in place, SES falls back to its own MAIL FROM rather than rejecting mail.
+            BehaviorOnMxFailure: 'USE_DEFAULT_VALUE',
+        });
+        return this.toAuthentication(name, await this.identity(name), true);
+    }
+    async getDomain(id) {
+        return this.toAuthentication(id, await this.identity(id), false);
+    }
+    async deleteDomain(id) {
+        await this.request('DELETE', `/v2/email/identities/${encodeURIComponent(id)}`);
+    }
+    async validateDomain(id) {
+        const identity = await this.identity(id);
+        const dkimStatus = identity.DkimAttributes?.Status ?? 'NOT_STARTED';
+        const dkim = dkimStatus === 'SUCCESS';
+        const results = [{ record: 'dkim', valid: dkim, ...(dkim ? {} : { reason: `DKIM status: ${dkimStatus.toLowerCase().replace(/_/g, ' ')}` }) }];
+        const mailFrom = identity.MailFromAttributes;
+        if (mailFrom?.MailFromDomain) {
+            const ok = mailFrom.MailFromDomainStatus === 'SUCCESS';
+            const status = (mailFrom.MailFromDomainStatus ?? 'PENDING').toLowerCase().replace(/_/g, ' ');
+            results.push({ record: 'mail_from', valid: ok, ...(ok ? {} : { reason: `MAIL FROM status: ${status}` }) });
+        }
+        // Sending is allowed once the identity (via DKIM) verifies; MAIL FROM falls back until its MX is found.
+        return { valid: Boolean(identity.VerifiedForSendingStatus) && dkim, results };
+    }
+    inboundRecords() {
+        throw new ConfigError(INBOUND_UNSUPPORTED);
+    }
+    async ensureInboundParse() {
+        throw new ConfigError(INBOUND_UNSUPPORTED);
+    }
+    async deleteInboundParse() { }
+    identity(name) {
+        return this.request('GET', `/v2/email/identities/${encodeURIComponent(name)}`);
+    }
+    toAuthentication(domain, identity, created) {
+        const records = (identity.DkimAttributes?.Tokens ?? []).map((token, i) => ({
+            type: 'CNAME',
+            name: `${token}._domainkey.${domain}`,
+            value: `${token}.dkim.amazonses.com`,
+            purpose: `dkim${i + 1}`,
+        }));
+        const mailFrom = identity.MailFromAttributes?.MailFromDomain;
+        if (mailFrom) {
+            const host = normalizeName(mailFrom);
+            records.push({ type: 'MX', name: host, value: `feedback-smtp.${this.opts.region}.amazonses.com`, priority: 10, purpose: 'mail_from_mx' });
+            records.push({
+                type: 'TXT',
+                name: host,
+                value: 'v=spf1 include:amazonses.com ~all',
+                purpose: 'mail_from_spf',
+                note: 'If this name already has an SPF record (v=spf1 …), add include:amazonses.com to it instead of creating a second one.',
+            });
+        }
+        return { id: domain, domain, valid: Boolean(identity.VerifiedForSendingStatus), records, created };
+    }
+    async request(method, path, body) {
+        const url = this.baseUrl + path;
+        const payload = body === undefined ? undefined : JSON.stringify(body);
+        const text = await requestText(this.fetchImpl, 'Amazon SES', url, () => ({
+            method,
+            body: payload,
+            headers: signRequest({ method, url, body: payload, headers: payload ? { 'content-type': 'application/json' } : {} }, this.opts.credentials, this.opts.region, 'ses'),
+        }), (t) => {
+            try {
+                const b = JSON.parse(t);
+                return b.message ?? b.Message;
+            }
+            catch {
+                return undefined;
+            }
+        });
+        return (text ? JSON.parse(text) : {});
+    }
+}
+//# sourceMappingURL=ses.js.map

package/dist/src/providers/email/ses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ses.js","sourceRoot":"","sources":["../../../../src/providers/email/ses.ts"],"names":[],"mappings":"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"}

package/dist/src/providers/factory.d.ts

@@ -0,0 +1,14 @@
+import type { DnsProvider, DnsRecord } from '../types.js';
+import { type AwsCredentials } from './dns/aws.js';
+export declare const DNS_PROVIDERS: readonly ["cloudflare", "route53", "manual"];
+export type DnsProviderName = (typeof DNS_PROVIDERS)[number];
+export interface DnsProviderConfig {
+    cloudflareApiToken?: string;
+    /** Explicit AWS keys; otherwise environment or shared credentials file. */
+    aws?: Partial<AwsCredentials>;
+    awsProfile?: string;
+    route53HostedZoneId?: string;
+    onManualRecords?: (records: DnsRecord[]) => Promise<void>;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function createDnsProvider(name: string, config?: DnsProviderConfig): DnsProvider;

package/dist/src/providers/factory.js

@@ -0,0 +1,32 @@
+import { ConfigError } from '../errors.js';
+import { loadAwsCredentials } from './dns/aws.js';
+import { CloudflareDns } from './dns/cloudflare.js';
+import { ManualDns } from './dns/manual.js';
+import { Route53Dns } from './dns/route53.js';
+export const DNS_PROVIDERS = ['cloudflare', 'route53', 'manual'];
+export function createDnsProvider(name, config = {}) {
+    const env = config.env ?? process.env;
+    switch (name) {
+        case 'cloudflare': {
+            const apiToken = config.cloudflareApiToken || env.CLOUDFLARE_API_TOKEN;
+            if (!apiToken)
+                throw new ConfigError('Cloudflare needs an API token (CLOUDFLARE_API_TOKEN).');
+            return new CloudflareDns({ apiToken });
+        }
+        case 'route53': {
+            const { accessKeyId, secretAccessKey, sessionToken } = config.aws ?? {};
+            if (Boolean(accessKeyId) !== Boolean(secretAccessKey)) {
+                throw new ConfigError('Route53 needs both an AWS access key id and a secret access key.');
+            }
+            const credentials = accessKeyId && secretAccessKey
+                ? { accessKeyId, secretAccessKey, ...(sessionToken ? { sessionToken } : {}) }
+                : () => loadAwsCredentials({ profile: config.awsProfile || undefined, env });
+            return new Route53Dns({ credentials, hostedZoneId: config.route53HostedZoneId || undefined });
+        }
+        case 'manual':
+            return new ManualDns(config.onManualRecords ?? (async () => { }));
+        default:
+            throw new ConfigError(`Unknown DNS provider "${name}". Use one of: ${DNS_PROVIDERS.join(', ')}.`);
+    }
+}
+//# sourceMappingURL=factory.js.map

package/dist/src/providers/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/providers/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,kBAAkB,EAAuB,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,YAAY,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC;AAa1E,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,SAA4B,EAAE;IAC5E,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACtC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,YAAY,CAAC,CAAC,CAAC;YAClB,MAAM,QAAQ,GAAG,MAAM,CAAC,kBAAkB,IAAI,GAAG,CAAC,oBAAoB,CAAC;YACvE,IAAI,CAAC,QAAQ;gBAAE,MAAM,IAAI,WAAW,CAAC,uDAAuD,CAAC,CAAC;YAC9F,OAAO,IAAI,aAAa,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;QACzC,CAAC;QACD,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC;YACxE,IAAI,OAAO,CAAC,WAAW,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC;gBACtD,MAAM,IAAI,WAAW,CAAC,kEAAkE,CAAC,CAAC;YAC5F,CAAC;YACD,MAAM,WAAW,GACf,WAAW,IAAI,eAAe;gBAC5B,CAAC,CAAC,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;gBAC7E,CAAC,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,UAAU,IAAI,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;YACjF,OAAO,IAAI,UAAU,CAAC,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,CAAC,mBAAmB,IAAI,SAAS,EAAE,CAAC,CAAC;QAChG,CAAC;QACD,KAAK,QAAQ;YACX,OAAO,IAAI,SAAS,CAAC,MAAM,CAAC,eAAe,IAAI,CAAC,KAAK,IAAI,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC;QACnE;YACE,MAAM,IAAI,WAAW,CAAC,yBAAyB,IAAI,kBAAkB,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtG,CAAC;AACH,CAAC"}

package/dist/src/records.d.ts

@@ -0,0 +1,35 @@
+import type { DnsRecord, PlannedChange, RecordType } from './types.js';
+export declare function isRecordType(type: string): type is RecordType;
+/** A normalized hostname with at least two labels (IDNs must be punycode). */
+export declare function isValidDomain(name: string): boolean;
+export declare function normalizeName(name: string): string;
+/** Hostnames compare case-insensitively without trailing dots; TXT values compare with quoting and chunking removed. */
+export declare function normalizeValue(type: RecordType, value: string): string;
+export declare function sameValue(type: RecordType, a: string, b: string): boolean;
+/** A record already present at the DNS host, in provider-neutral form. */
+export interface ExistingRecord {
+    id: string;
+    type: string;
+    value: string;
+    priority?: number;
+    proxied?: boolean;
+}
+export declare function isSpf(value: string): boolean;
+/**
+ * Adds the mechanisms of `desired` (e.g. "include:mailgun.org") to an existing
+ * SPF record, before its `all`/`redirect` term. Returns null when the existing
+ * record already has them all. A name must have exactly one SPF record, so
+ * providers' SPF records are merged in rather than added next to the old one.
+ */
+export declare function mergeSpf(existing: string, desired: string): {
+    value: string;
+    added: string[];
+} | null;
+/**
+ * Decides what to do with `record` given the records already at its name.
+ * Never replaces a record pointing elsewhere unless `overwrite` is set, and never
+ * deletes records of other types. `desired` is every record being planned, so
+ * a provider's own multi-value sets (e.g. two MX hosts) don't conflict with each other.
+ */
+export declare function decideChange(record: DnsRecord, existing: ExistingRecord[], overwrite?: boolean, desired?: DnsRecord[]): PlannedChange;
+export declare function describeRecord(record: DnsRecord): string;

package/dist/src/records.js

@@ -0,0 +1,109 @@
+const RECORD_TYPES = ['CNAME', 'TXT', 'MX'];
+export function isRecordType(type) {
+    return RECORD_TYPES.includes(type);
+}
+const DOMAIN_RE = /^(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))+$/;
+/** A normalized hostname with at least two labels (IDNs must be punycode). */
+export function isValidDomain(name) {
+    return name.length <= 253 && DOMAIN_RE.test(name);
+}
+export function normalizeName(name) {
+    return name.trim().toLowerCase().replace(/\.+$/, '');
+}
+/** Hostnames compare case-insensitively without trailing dots; TXT values compare with quoting and chunking removed. */
+export function normalizeValue(type, value) {
+    if (type === 'TXT') {
+        return value.trim().replace(/^"(.*)"$/s, '$1').replace(/"\s*"/g, '');
+    }
+    return normalizeName(value);
+}
+export function sameValue(type, a, b) {
+    return normalizeValue(type, a) === normalizeValue(type, b);
+}
+const SPF_TERMINATOR = /^([~+?-]?all|redirect=.*)$/i;
+export function isSpf(value) {
+    return /^v=spf1(\s|$)/i.test(normalizeValue('TXT', value));
+}
+/**
+ * Adds the mechanisms of `desired` (e.g. "include:mailgun.org") to an existing
+ * SPF record, before its `all`/`redirect` term. Returns null when the existing
+ * record already has them all. A name must have exactly one SPF record, so
+ * providers' SPF records are merged in rather than added next to the old one.
+ */
+export function mergeSpf(existing, desired) {
+    const have = normalizeValue('TXT', existing).split(/\s+/).filter(Boolean);
+    const want = normalizeValue('TXT', desired)
+        .split(/\s+/)
+        .filter((t) => t && t.toLowerCase() !== 'v=spf1' && !SPF_TERMINATOR.test(t));
+    const added = want.filter((t) => !have.some((h) => h.toLowerCase() === t.toLowerCase()));
+    if (added.length === 0)
+        return null;
+    const end = have.findIndex((t) => SPF_TERMINATOR.test(t));
+    const merged = end === -1 ? [...have, ...added] : [...have.slice(0, end), ...added, ...have.slice(end)];
+    return { value: merged.join(' '), added };
+}
+/**
+ * Decides what to do with `record` given the records already at its name.
+ * Never replaces a record pointing elsewhere unless `overwrite` is set, and never
+ * deletes records of other types. `desired` is every record being planned, so
+ * a provider's own multi-value sets (e.g. two MX hosts) don't conflict with each other.
+ */
+export function decideChange(record, existing, overwrite = false, desired = []) {
+    const conflict = (reason) => ({ record, action: 'conflict', reason });
+    const siblings = desired.filter((d) => d !== record && d.name === record.name && d.type === record.type);
+    const ours = (e) => siblings.some((s) => sameValue(record.type, s.value, e.value));
+    const sameType = existing.filter((e) => e.type === record.type);
+    const others = existing.filter((e) => e.type !== record.type);
+    if (record.type === 'CNAME' && others.length > 0) {
+        const types = [...new Set(others.map((e) => e.type))].join(', ');
+        return conflict(`a CNAME cannot coexist with the existing ${types} record(s) at this name`);
+    }
+    const blockingCname = others.find((e) => e.type === 'CNAME');
+    if (blockingCname) {
+        return conflict(`an existing CNAME (${blockingCname.value}) blocks other records at this name`);
+    }
+    const match = sameType.find((e) => sameValue(record.type, e.value, record.value));
+    if (match) {
+        if (match.proxied) {
+            return { record, action: 'update', existingId: match.id, reason: 'disable proxying' };
+        }
+        if (record.type === 'MX' && record.priority !== undefined && match.priority !== record.priority) {
+            return { record, action: 'update', existingId: match.id, reason: `priority ${match.priority} → ${record.priority}` };
+        }
+        return { record, action: 'noop' };
+    }
+    if (record.type === 'TXT') {
+        // SPF: merge into the existing record rather than adding a second one.
+        if (isSpf(record.value)) {
+            const spf = sameType.filter((e) => isSpf(e.value));
+            if (spf.length > 1)
+                return conflict('the name already has more than one SPF record, which makes SPF fail; reduce it to one first');
+            if (spf.length === 1) {
+                const merged = mergeSpf(spf[0].value, record.value);
+                if (!merged)
+                    return { record: { ...record, value: normalizeValue('TXT', spf[0].value) }, action: 'noop' };
+                return {
+                    record: { ...record, value: merged.value },
+                    action: 'update',
+                    existingId: spf[0].id,
+                    reason: `add ${merged.added.join(' ')} to the existing SPF record`,
+                };
+            }
+        }
+        // Other TXT records can sit side by side.
+        return { record, action: 'create' };
+    }
+    const foreign = sameType.filter((e) => !ours(e));
+    if (foreign.length === 0)
+        return { record, action: 'create' };
+    const current = foreign.map((e) => e.value).join(', ');
+    if (overwrite && foreign.length === 1) {
+        return { record, action: 'update', existingId: foreign[0].id, reason: `replace ${current}` };
+    }
+    return conflict(`existing ${record.type} points to ${current}; use overwrite to replace it`);
+}
+export function describeRecord(record) {
+    const priority = record.priority !== undefined ? `${record.priority} ` : '';
+    return `${record.type} ${record.name} → ${priority}${record.value}`;
+}
+//# sourceMappingURL=records.js.map

package/dist/src/records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.js","sourceRoot":"","sources":["../../src/records.ts"],"names":[],"mappings":"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"}

package/dist/src/server.d.ts

@@ -0,0 +1,67 @@
+import { type SetupOptions } from './orchestrator.js';
+import type { DnsProvider, EmailProvider } from './types.js';
+/** Body of /api/plan, /api/setup and /api/status. Secrets fall back to environment variables. */
+export interface SetupRequest {
+    domain: string;
+    subdomain?: string;
+    dns: string;
+    /** sendgrid | postmark | mailgun | ses (default sendgrid) */
+    emailProvider?: string;
+    onBehalfOf?: string;
+    credentials?: {
+        sendgridApiKey?: string;
+        postmarkAccountToken?: string;
+        postmarkInboundServerId?: string;
+        mailgunApiKey?: string;
+        mailgunRegion?: string;
+        /** Amazon SES uses the AWS fields below (or the AWS environment) plus this region. */
+        sesRegion?: string;
+        cloudflareApiToken?: string;
+        awsAccessKeyId?: string;
+        awsSecretAccessKey?: string;
+        awsSessionToken?: string;
+        awsProfile?: string;
+        route53HostedZoneId?: string;
+    };
+    inbound?: {
+        url: string;
+        hostname?: string;
+        spamCheck?: boolean;
+        sendRaw?: boolean;
+    };
+    overwrite?: boolean;
+    waitSeconds?: number;
+}
+export interface UiServerOptions {
+    /** Default 4545; 0 picks a free port. */
+    port?: number;
+    token?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Override provider construction (custom providers, tests). */
+    providers?: (req: SetupRequest) => {
+        email: EmailProvider;
+        dns: DnsProvider;
+    } | Promise<{
+        email: EmailProvider;
+        dns: DnsProvider;
+    }>;
+    /** Merged into every setup run. */
+    setupDefaults?: Partial<SetupOptions>;
+    version?: string;
+}
+export interface UiServer {
+    /** Open this once; it exchanges the token for a cookie. */
+    url: string;
+    port: number;
+    close(): Promise<void>;
+}
+/**
+ * Local web UI. Binds to 127.0.0.1 only. A random token in the first URL is
+ * swapped for a SameSite=Strict cookie; the Host header is checked to block
+ * DNS rebinding; API calls must be JSON POSTs, which cross-origin pages can't
+ * send without a CORS preflight this server never approves.
+ */
+export declare function startUiServer(opts?: UiServerOptions): Promise<UiServer>;
+export declare function parseSetupRequest(input: unknown, { requireDns }?: {
+    requireDns?: boolean | undefined;
+}): SetupRequest;