dkimkit 0.0.0-stage → 0.7.0

package/dist/src/hosted/worker.d.ts

@@ -0,0 +1,45 @@
+import type { FetchLike } from '../http.js';
+import type { DomainService, Logger } from './service.js';
+import type { Store } from './store.js';
+export interface RunnerOptions {
+    /** Domains checked in parallel. Default 4. */
+    concurrency?: number;
+    pollMs?: number;
+    /** How long a claimed job stays locked if the process dies mid-run. */
+    leaseMs?: number;
+    now?: () => number;
+    fetch?: FetchLike;
+    allowPrivateWebhooks?: boolean;
+    /** Reports usage to the billing provider after each metering pass. */
+    billing?: {
+        reportUsage(): Promise<void>;
+    };
+    log?: Logger;
+}
+/** Polls the store for due domain checks and webhook deliveries. Safe to run in several processes. */
+export declare class BackgroundRunner {
+    private readonly service;
+    private readonly store;
+    private readonly opts;
+    private readonly concurrency;
+    private readonly pollMs;
+    private readonly leaseMs;
+    private readonly now;
+    private readonly fetchImpl;
+    private readonly log;
+    private readonly inflight;
+    private domainsRunning;
+    private lastMeteredAt;
+    private timer;
+    private stopped;
+    constructor(service: DomainService, store: Store, opts?: RunnerOptions);
+    start(): void;
+    /** Stops polling and waits for in-flight work to finish. */
+    stop(): Promise<void>;
+    /** Claims and starts whatever is due. Doesn't wait for the work itself; see `drain`. */
+    tick(): Promise<void>;
+    drain(): Promise<void>;
+    private track;
+    private deliver;
+    private retryLater;
+}

package/dist/src/hosted/worker.js

@@ -0,0 +1,142 @@
+import { signWebhook, WEBHOOK_SIGNATURE_HEADER } from './crypto.js';
+import { assertPublicHttpsUrl } from './net.js';
+// After the first attempt: 10s, 1m, 5m, 30m, 2h, 6h, 12h, 24h — then give up.
+const WEBHOOK_RETRY_MS = [10e3, 60e3, 5 * 60e3, 30 * 60e3, 2 * 3600e3, 6 * 3600e3, 12 * 3600e3, 24 * 3600e3];
+const WEBHOOK_TIMEOUT_MS = 10_000;
+const METER_EVERY_MS = 3600e3;
+/** Polls the store for due domain checks and webhook deliveries. Safe to run in several processes. */
+export class BackgroundRunner {
+    service;
+    store;
+    opts;
+    concurrency;
+    pollMs;
+    leaseMs;
+    now;
+    fetchImpl;
+    log;
+    inflight = new Set();
+    domainsRunning = 0;
+    lastMeteredAt = -Infinity;
+    timer;
+    stopped = true;
+    constructor(service, store, opts = {}) {
+        this.service = service;
+        this.store = store;
+        this.opts = opts;
+        this.concurrency = opts.concurrency ?? 4;
+        this.pollMs = opts.pollMs ?? 2000;
+        this.leaseMs = opts.leaseMs ?? 5 * 60e3;
+        this.now = opts.now ?? Date.now;
+        this.fetchImpl = opts.fetch ?? fetch;
+        this.log = opts.log ?? (() => { });
+    }
+    start() {
+        this.stopped = false;
+        const loop = async () => {
+            if (this.stopped)
+                return;
+            try {
+                await this.tick();
+            }
+            catch (err) {
+                // e.g. the database is briefly unreachable; try again next poll.
+                this.log('error', 'runner tick failed', { error: String(err) });
+            }
+            if (!this.stopped)
+                this.timer = setTimeout(loop, this.pollMs);
+        };
+        void loop();
+    }
+    /** Stops polling and waits for in-flight work to finish. */
+    async stop() {
+        this.stopped = true;
+        clearTimeout(this.timer);
+        await this.drain();
+    }
+    /** Claims and starts whatever is due. Doesn't wait for the work itself; see `drain`. */
+    async tick() {
+        const now = this.now();
+        const runs = [];
+        const free = this.concurrency - this.domainsRunning;
+        if (free > 0) {
+            for (const row of await this.store.claimDueDomains(now, free, this.leaseMs)) {
+                this.domainsRunning++;
+                const run = this.service
+                    .runDomain(row)
+                    .catch((err) => this.log('error', 'domain run crashed', { domain_id: row.id, error: String(err) }))
+                    .finally(() => this.domainsRunning--);
+                runs.push(run);
+                this.track(run);
+            }
+        }
+        for (const delivery of await this.store.claimDueDeliveries(now, 10, this.leaseMs)) {
+            this.track(this.deliver(delivery));
+        }
+        // Usage metering: an active day per verified domain. Idempotent, so several
+        // runner processes doing this at once is fine.
+        if (now - this.lastMeteredAt >= METER_EVERY_MS) {
+            this.lastMeteredAt = now;
+            const meter = async () => {
+                // Count domains this pass just verified, not only those verified before it.
+                await Promise.allSettled(runs);
+                await this.service.meterActiveDomains();
+                // After metering, so the report includes today's active days.
+                await this.opts.billing?.reportUsage();
+            };
+            this.track(meter().catch((err) => this.log('error', 'usage metering failed', { error: String(err) })));
+        }
+    }
+    async drain() {
+        while (this.inflight.size > 0)
+            await Promise.allSettled([...this.inflight]);
+    }
+    track(p) {
+        this.inflight.add(p);
+        void p.finally(() => this.inflight.delete(p));
+    }
+    async deliver(d) {
+        const account = await this.store.getAccount(d.accountId);
+        if (!account)
+            return;
+        const attempts = d.attempts + 1;
+        try {
+            await assertPublicHttpsUrl(d.url, { allowPrivate: this.opts.allowPrivateWebhooks });
+            const event = JSON.parse(d.payload);
+            const res = await this.fetchImpl(d.url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'user-agent': 'dkimkit-webhooks/1',
+                    [WEBHOOK_SIGNATURE_HEADER]: signWebhook(account.webhookSecret, d.payload, Math.floor(this.now() / 1000)),
+                    'x-dkimkit-event-id': event.id,
+                    'x-dkimkit-event-type': event.type,
+                },
+                body: d.payload,
+                redirect: 'manual',
+                signal: AbortSignal.timeout(WEBHOOK_TIMEOUT_MS),
+            });
+            await res.body?.cancel();
+            if (res.ok) {
+                await this.store.updateDelivery(d.id, { status: 'delivered', attempts, responseStatus: res.status, lastError: null, lockedUntil: null, nextAttemptAt: null });
+                return;
+            }
+            await this.retryLater(d, attempts, `HTTP ${res.status}`, res.status);
+        }
+        catch (err) {
+            await this.retryLater(d, attempts, err instanceof Error ? err.message : String(err), null);
+        }
+    }
+    async retryLater(d, attempts, error, status) {
+        const delay = WEBHOOK_RETRY_MS[attempts - 1];
+        if (delay === undefined) {
+            await this.store.updateDelivery(d.id, { status: 'failed', attempts, lastError: error, responseStatus: status, lockedUntil: null, nextAttemptAt: null });
+            this.log('warn', 'webhook delivery abandoned', { delivery_id: d.id, error });
+            return;
+        }
+        await this.store.updateDelivery(d.id, {
+            attempts, lastError: error, responseStatus: status, lockedUntil: null, nextAttemptAt: this.now() + delay,
+        });
+    }
+}
+//# sourceMappingURL=worker.js.map

package/dist/src/hosted/worker.js.map

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

package/dist/src/http.d.ts

@@ -0,0 +1,14 @@
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export interface RequestOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+export declare const sleep: (ms: number, signal?: AbortSignal) => Promise<undefined>;
+/** JSON request with retries on rate limits and transient server errors. */
+export declare function requestJson<T>(fetchImpl: FetchLike, provider: string, url: string, opts: RequestOptions, describeError: (body: unknown) => string | undefined, retries?: number): Promise<T>;
+/**
+ * Raw request returning the response text. `buildInit` runs per attempt so
+ * callers can re-sign requests on retry.
+ */
+export declare function requestText(fetchImpl: FetchLike, provider: string, url: string, buildInit: () => RequestInit, describeError: (text: string) => string | undefined, retries?: number): Promise<string>;

package/dist/src/http.js

@@ -0,0 +1,54 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { ApiError } from './errors.js';
+const RETRYABLE = new Set([429, 500, 502, 503, 504]);
+const MAX_RETRY_DELAY_MS = 30_000;
+export const sleep = (ms, signal) => delay(ms, undefined, { signal });
+/** JSON request with retries on rate limits and transient server errors. */
+export async function requestJson(fetchImpl, provider, url, opts, describeError, retries = 2) {
+    const hasBody = opts.body !== undefined;
+    const init = {
+        method: opts.method ?? 'GET',
+        headers: {
+            Accept: 'application/json',
+            ...(hasBody ? { 'Content-Type': 'application/json' } : {}),
+            ...opts.headers,
+        },
+        body: hasBody ? JSON.stringify(opts.body) : undefined,
+    };
+    const text = await send(fetchImpl, provider, url, () => init, (t) => describeError(parseJson(t)), retries);
+    return (text ? parseJson(text) : undefined);
+}
+/**
+ * Raw request returning the response text. `buildInit` runs per attempt so
+ * callers can re-sign requests on retry.
+ */
+export async function requestText(fetchImpl, provider, url, buildInit, describeError, retries = 2) {
+    return send(fetchImpl, provider, url, buildInit, describeError, retries);
+}
+async function send(fetchImpl, provider, url, buildInit, describeError, retries) {
+    for (let attempt = 0;; attempt++) {
+        const res = await fetchImpl(url, buildInit());
+        const text = await res.text();
+        if (res.ok)
+            return text;
+        if (RETRYABLE.has(res.status) && attempt < retries) {
+            await sleep(retryDelay(res, attempt));
+            continue;
+        }
+        throw new ApiError(provider, res.status, describeError(text) || res.statusText || `HTTP ${res.status}`, parseJson(text));
+    }
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function retryDelay(res, attempt) {
+    const retryAfter = Number(res.headers.get('retry-after'));
+    const ms = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 1000 * 2 ** attempt;
+    return Math.min(ms, MAX_RETRY_DELAY_MS);
+}
+//# sourceMappingURL=http.js.map

package/dist/src/http.js.map

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

package/dist/src/index.d.ts

@@ -0,0 +1,19 @@
+export * from './types.js';
+export * from './errors.js';
+export { decideChange, describeRecord, isValidDomain, normalizeName, normalizeValue, sameValue, type ExistingRecord } from './records.js';
+export { authoritativeLookup, ResolverLookup, waitForPropagation, type DnsLookup, type WaitOptions } from './propagation.js';
+export { setupDomain, checkStatus, type SetupOptions, type SetupResult, type SetupEvent, type SetupStatus, type StatusResult } from './orchestrator.js';
+export { SendGridProvider, SENDGRID_INBOUND_MX, type SendGridOptions } from './providers/email/sendgrid.js';
+export { CloudflareDns, type CloudflareOptions } from './providers/dns/cloudflare.js';
+export { ManualDns } from './providers/dns/manual.js';
+export type { FetchLike } from './http.js';
+export { Route53Dns, type Route53Options } from './providers/dns/route53.js';
+export { loadAwsCredentials, signRequest, type AwsCredentials } from './providers/dns/aws.js';
+export { createDnsProvider, DNS_PROVIDERS, type DnsProviderName, type DnsProviderConfig } from './providers/factory.js';
+export { startUiServer, parseSetupRequest, type UiServer, type UiServerOptions, type SetupRequest } from './server.js';
+export { verifyWebhookSignature, signWebhook, WEBHOOK_SIGNATURE_HEADER } from './hosted/crypto.js';
+export { detectDnsHost, type DnsHost } from './dns-host.js';
+export { PostmarkProvider, type PostmarkOptions } from './providers/email/postmark.js';
+export { MailgunProvider, type MailgunOptions } from './providers/email/mailgun.js';
+export { SesProvider, type SesOptions } from './providers/email/ses.js';
+export { createEmailProvider, EMAIL_PROVIDERS, type EmailCredentials, type EmailProviderName } from './providers/email/factory.js';

package/dist/src/index.js

@@ -0,0 +1,19 @@
+export * from './types.js';
+export * from './errors.js';
+export { decideChange, describeRecord, isValidDomain, normalizeName, normalizeValue, sameValue } from './records.js';
+export { authoritativeLookup, ResolverLookup, waitForPropagation } from './propagation.js';
+export { setupDomain, checkStatus } from './orchestrator.js';
+export { SendGridProvider, SENDGRID_INBOUND_MX } from './providers/email/sendgrid.js';
+export { CloudflareDns } from './providers/dns/cloudflare.js';
+export { ManualDns } from './providers/dns/manual.js';
+export { Route53Dns } from './providers/dns/route53.js';
+export { loadAwsCredentials, signRequest } from './providers/dns/aws.js';
+export { createDnsProvider, DNS_PROVIDERS } from './providers/factory.js';
+export { startUiServer, parseSetupRequest } from './server.js';
+export { verifyWebhookSignature, signWebhook, WEBHOOK_SIGNATURE_HEADER } from './hosted/crypto.js';
+export { detectDnsHost } from './dns-host.js';
+export { PostmarkProvider } from './providers/email/postmark.js';
+export { MailgunProvider } from './providers/email/mailgun.js';
+export { SesProvider } from './providers/email/ses.js';
+export { createEmailProvider, EMAIL_PROVIDERS } from './providers/email/factory.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,SAAS,EAAuB,MAAM,cAAc,CAAC;AAC1I,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,kBAAkB,EAAoC,MAAM,kBAAkB,CAAC;AAC7H,OAAO,EAAE,WAAW,EAAE,WAAW,EAA6F,MAAM,mBAAmB,CAAC;AACxJ,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAwB,MAAM,+BAA+B,CAAC;AAC5G,OAAO,EAAE,aAAa,EAA0B,MAAM,+BAA+B,CAAC;AACtF,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAEtD,OAAO,EAAE,UAAU,EAAuB,MAAM,4BAA4B,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAuB,MAAM,wBAAwB,CAAC;AAC9F,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAgD,MAAM,wBAAwB,CAAC;AACxH,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAA0D,MAAM,aAAa,CAAC;AACvH,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AACnG,OAAO,EAAE,aAAa,EAAgB,MAAM,eAAe,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAwB,MAAM,+BAA+B,CAAC;AACvF,OAAO,EAAE,eAAe,EAAuB,MAAM,8BAA8B,CAAC;AACpF,OAAO,EAAE,WAAW,EAAmB,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAiD,MAAM,8BAA8B,CAAC"}

package/dist/src/orchestrator.d.ts

@@ -0,0 +1,70 @@
+import { type DnsLookup } from './propagation.js';
+import type { DnsProvider, DnsRecord, DomainAuthentication, EmailProvider, InboundAction, InboundParseOptions, PlannedChange, ValidationResult } from './types.js';
+export type SetupEvent = {
+    type: 'domain';
+    auth: DomainAuthentication;
+} | {
+    type: 'plan';
+    changes: PlannedChange[];
+} | {
+    type: 'applied';
+    changes: PlannedChange[];
+} | {
+    type: 'propagation';
+    pending: DnsRecord[];
+    total: number;
+    elapsedMs: number;
+} | {
+    type: 'validation';
+    attempt: number;
+    result: ValidationResult;
+} | {
+    type: 'inbound';
+    hostname: string;
+    url: string;
+    action: InboundAction;
+};
+export interface SetupOptions {
+    domain: string;
+    subdomain?: string;
+    inbound?: InboundParseOptions;
+    /** Replace existing CNAME/MX records that point elsewhere. */
+    overwrite?: boolean;
+    /** Plan only: create nothing in DNS. Note the provider may still create the domain to learn its records. */
+    dryRun?: boolean;
+    /** Called before writing DNS when there are changes; return false to abort. */
+    confirm?: (changes: PlannedChange[]) => Promise<boolean>;
+    propagation?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+        lookup?: DnsLookup;
+    };
+    validation?: {
+        attempts?: number;
+        intervalMs?: number;
+    };
+    onEvent?: (event: SetupEvent) => void;
+    /** Stops waiting (propagation, validation retries) and rejects with an AbortError. */
+    signal?: AbortSignal;
+}
+export type SetupStatus = 'complete' | 'dry-run' | 'aborted' | 'dns-pending' | 'validation-failed';
+export interface SetupResult {
+    status: SetupStatus;
+    domain: DomainAuthentication;
+    changes: PlannedChange[];
+    pending?: DnsRecord[];
+    validation?: ValidationResult;
+    inbound?: InboundAction;
+}
+/**
+ * Runs the full lifecycle: provider domain → DNS plan/apply → propagation →
+ * provider validation → inbound parse. Idempotent, so it is safe to re-run
+ * after a `dns-pending` or `validation-failed` result.
+ */
+export declare function setupDomain(email: EmailProvider, dns: DnsProvider, opts: SetupOptions): Promise<SetupResult>;
+export interface StatusResult {
+    domain: DomainAuthentication | null;
+    validation?: ValidationResult;
+}
+/** Read-only check: finds the domain and asks the provider to re-validate it. */
+export declare function checkStatus(email: EmailProvider, domain: string, subdomain?: string): Promise<StatusResult>;

package/dist/src/orchestrator.js

@@ -0,0 +1,69 @@
+import { DnsConflictError } from './errors.js';
+import { sleep } from './http.js';
+import { authoritativeLookup, waitForPropagation } from './propagation.js';
+/**
+ * Runs the full lifecycle: provider domain → DNS plan/apply → propagation →
+ * provider validation → inbound parse. Idempotent, so it is safe to re-run
+ * after a `dns-pending` or `validation-failed` result.
+ */
+export async function setupDomain(email, dns, opts) {
+    const emit = opts.onEvent ?? (() => { });
+    const { signal } = opts;
+    const auth = await email.ensureDomain(opts.domain, { subdomain: opts.subdomain });
+    emit({ type: 'domain', auth });
+    const records = [...auth.records, ...(opts.inbound ? email.inboundRecords(opts.inbound.hostname) : [])];
+    const changes = await dns.plan(records, { overwrite: opts.overwrite });
+    emit({ type: 'plan', changes });
+    const conflicts = changes.filter((c) => c.action === 'conflict');
+    if (conflicts.length > 0)
+        throw new DnsConflictError(conflicts);
+    if (opts.dryRun)
+        return { status: 'dry-run', domain: auth, changes };
+    const writes = changes.filter((c) => c.action === 'create' || c.action === 'update');
+    if (writes.length > 0) {
+        if (opts.confirm && !(await opts.confirm(changes)))
+            return { status: 'aborted', domain: auth, changes };
+        await dns.apply(changes);
+        emit({ type: 'applied', changes: writes });
+    }
+    // Wait for the planned values, which can differ from the provider's (e.g. an SPF record merged into an existing one).
+    const planned = changes.map((c) => c.record);
+    const lookup = opts.propagation?.lookup ?? (await authoritativeLookup(opts.domain));
+    const pending = await waitForPropagation(planned, lookup, {
+        timeoutMs: opts.propagation?.timeoutMs,
+        intervalMs: opts.propagation?.intervalMs,
+        onProgress: (p, elapsedMs) => emit({ type: 'propagation', pending: p, total: planned.length, elapsedMs }),
+        signal,
+    });
+    if (pending.length > 0)
+        return { status: 'dns-pending', domain: auth, changes, pending };
+    // The provider's resolvers can lag behind the authoritative servers, so retry.
+    const { attempts = 6, intervalMs = 10_000 } = opts.validation ?? {};
+    let validation;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        signal?.throwIfAborted();
+        validation = await email.validateDomain(auth.id);
+        emit({ type: 'validation', attempt, result: validation });
+        if (validation.valid)
+            break;
+        if (attempt < attempts)
+            await sleep(intervalMs, signal);
+    }
+    if (!validation?.valid)
+        return { status: 'validation-failed', domain: auth, changes, validation };
+    let inbound;
+    if (opts.inbound) {
+        signal?.throwIfAborted();
+        inbound = await email.ensureInboundParse(opts.inbound);
+        emit({ type: 'inbound', hostname: opts.inbound.hostname, url: opts.inbound.url, action: inbound });
+    }
+    return { status: 'complete', domain: { ...auth, valid: true }, changes, validation, inbound };
+}
+/** Read-only check: finds the domain and asks the provider to re-validate it. */
+export async function checkStatus(email, domain, subdomain) {
+    const auth = await email.findDomain(domain, subdomain);
+    if (!auth)
+        return { domain: null };
+    return { domain: auth, validation: await email.validateDomain(auth.id) };
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/src/orchestrator.js.map

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

package/dist/src/propagation.d.ts

@@ -0,0 +1,30 @@
+import { Resolver } from 'node:dns/promises';
+import type { DnsRecord } from './types.js';
+export interface DnsLookup {
+    /** True when `record` is currently visible with the expected value. */
+    check(record: DnsRecord): Promise<boolean>;
+}
+export declare class ResolverLookup implements DnsLookup {
+    private readonly resolver;
+    constructor(resolver: Resolver);
+    check(record: DnsRecord): Promise<boolean>;
+}
+/** The zone apex holding `domain` and its nameservers, found by walking up the labels. */
+export declare function findZoneNameservers(domain: string, resolveNs?: (name: string) => Promise<string[]>): Promise<{
+    zone: string;
+    nameservers: string[];
+} | null>;
+/**
+ * Queries the domain's authoritative nameservers directly, so results reflect
+ * what was just written rather than a recursive resolver's cache. Falls back
+ * to public resolvers if the nameservers can't be found.
+ */
+export declare function authoritativeLookup(domain: string): Promise<DnsLookup>;
+export interface WaitOptions {
+    timeoutMs?: number;
+    intervalMs?: number;
+    onProgress?: (pending: DnsRecord[], elapsedMs: number) => void;
+    signal?: AbortSignal;
+}
+/** Polls until every record is visible or the timeout passes. Returns the records still missing. */
+export declare function waitForPropagation(records: DnsRecord[], lookup: DnsLookup, opts?: WaitOptions): Promise<DnsRecord[]>;

package/dist/src/propagation.js

@@ -0,0 +1,76 @@
+import { Resolver } from 'node:dns/promises';
+import { sleep } from './http.js';
+import { normalizeValue, sameValue } from './records.js';
+const PUBLIC_RESOLVERS = ['1.1.1.1', '8.8.8.8'];
+export class ResolverLookup {
+    resolver;
+    constructor(resolver) {
+        this.resolver = resolver;
+    }
+    async check(record) {
+        try {
+            switch (record.type) {
+                case 'CNAME':
+                    return (await this.resolver.resolveCname(record.name)).some((v) => sameValue('CNAME', v, record.value));
+                case 'MX':
+                    return (await this.resolver.resolveMx(record.name)).some((mx) => sameValue('MX', mx.exchange, record.value));
+                case 'TXT': {
+                    const wanted = normalizeValue('TXT', record.value);
+                    return (await this.resolver.resolveTxt(record.name)).some((chunks) => chunks.join('') === wanted);
+                }
+            }
+        }
+        catch (err) {
+            // NXDOMAIN, NODATA, SERVFAIL, timeouts: not visible yet.
+            if (typeof err.code === 'string')
+                return false;
+            throw err;
+        }
+    }
+}
+/** The zone apex holding `domain` and its nameservers, found by walking up the labels. */
+export async function findZoneNameservers(domain, resolveNs = (name) => new Resolver().resolveNs(name)) {
+    const labels = domain.split('.');
+    for (let i = 0; i < labels.length - 1; i++) {
+        const zone = labels.slice(i).join('.');
+        try {
+            const nameservers = await resolveNs(zone);
+            if (nameservers.length > 0)
+                return { zone, nameservers: nameservers.map((n) => n.toLowerCase()) };
+        }
+        catch {
+            // Not a zone apex; try the parent.
+        }
+    }
+    return null;
+}
+/**
+ * Queries the domain's authoritative nameservers directly, so results reflect
+ * what was just written rather than a recursive resolver's cache. Falls back
+ * to public resolvers if the nameservers can't be found.
+ */
+export async function authoritativeLookup(domain) {
+    const system = new Resolver();
+    const found = await findZoneNameservers(domain);
+    const ips = found ? (await Promise.all(found.nameservers.map((ns) => system.resolve4(ns).catch(() => [])))).flat() : [];
+    const resolver = new Resolver({ timeout: 3000, tries: 2 });
+    resolver.setServers(ips.length > 0 ? ips : PUBLIC_RESOLVERS);
+    return new ResolverLookup(resolver);
+}
+/** Polls until every record is visible or the timeout passes. Returns the records still missing. */
+export async function waitForPropagation(records, lookup, opts = {}) {
+    const { timeoutMs = 300_000, intervalMs = 5_000, onProgress, signal } = opts;
+    const started = Date.now();
+    let pending = records;
+    for (;;) {
+        signal?.throwIfAborted();
+        const visible = await Promise.all(pending.map((r) => lookup.check(r)));
+        pending = pending.filter((_, i) => !visible[i]);
+        const elapsed = Date.now() - started;
+        onProgress?.(pending, elapsed);
+        if (pending.length === 0 || elapsed + intervalMs > timeoutMs)
+            return pending;
+        await sleep(intervalMs, signal);
+    }
+}
+//# sourceMappingURL=propagation.js.map

package/dist/src/propagation.js.map

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

package/dist/src/providers/dns/aws.d.ts

@@ -0,0 +1,28 @@
+export interface AwsCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+export interface SignableRequest {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+/**
+ * AWS Signature Version 4. Returns the headers to send (everything except
+ * `host`, which fetch sets itself to the same value that was signed).
+ */
+export declare function signRequest(req: SignableRequest, credentials: AwsCredentials, region: string, service: string, now?: Date): Record<string, string>;
+export interface LoadCredentialsOptions {
+    /** Named profile in the shared credentials file. Overrides environment keys. */
+    profile?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Static credentials from AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, or a profile
+ * in ~/.aws/credentials (AWS_PROFILE, AWS_SHARED_CREDENTIALS_FILE honored).
+ * SSO and instance roles are not supported; export keys for those
+ * (e.g. `aws configure export-credentials --format env`).
+ */
+export declare function loadAwsCredentials(opts?: LoadCredentialsOptions): Promise<AwsCredentials>;