hatchkit 0.1.40 → 0.1.42

package/dist/email/presets.d.ts

@@ -0,0 +1,14 @@
+export interface EmailAddressPreset {
+    /** Local part. Joined with `@<domain>` at apply time. */
+    localPart: string;
+    /** Human-readable description shown in the multi-select prompt. */
+    description: string;
+    /** Whether this preset is ticked by default in the picker. */
+    defaultChecked: boolean;
+}
+export declare const DEFAULT_FORWARD_PRESETS: EmailAddressPreset[];
+/** Whether to enable a catch-all rule (`*@domain` → destination) by
+ *  default. Catch-all is a safety net for anything not matched by an
+ *  explicit rule — recommended for personal/operator domains. */
+export declare const DEFAULT_CATCH_ALL = true;
+//# sourceMappingURL=presets.d.ts.map

package/dist/email/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../src/email/presets.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,eAAO,MAAM,uBAAuB,EAAE,kBAAkB,EAMvD,CAAC;AAEF;;iEAEiE;AACjE,eAAO,MAAM,iBAAiB,OAAO,CAAC"}

package/dist/email/presets.js

@@ -0,0 +1,33 @@
+/*
+ * Email forwarding presets.
+ *
+ * Default set of local-parts to offer when configuring Cloudflare Email
+ * Routing on a new project's zone. The picker is multi-select so the
+ * user can untick anything that doesn't apply, or add custom entries.
+ *
+ * Curated to cover the common public-facing aliases without bloating
+ * the rule list (each rule is a distinct Email Routing entry):
+ *   · hello@  — generic first-touch contact
+ *   · rico@   — personal alias (the operator's first name)
+ *   · admin@  — system / infrastructure correspondence (TLS notices,
+ *               registrar alerts, dotenvx/Github billing receipts)
+ *   · support@— customer-facing support inbox
+ *   · hi@     — short personal alternative to hello@
+ *
+ * A catch-all rule (`*@domain`) is offered separately because
+ * Cloudflare's API treats it differently — it's exactly one rule per
+ * zone (PUT semantics), not a list. The default is "enable catch-all"
+ * so stray addresses (`careers@`, `dmarc@`, …) still reach the user.
+ */
+export const DEFAULT_FORWARD_PRESETS = [
+    { localPart: "hello", description: "general first-touch contact", defaultChecked: true },
+    { localPart: "rico", description: "personal alias", defaultChecked: true },
+    { localPart: "admin", description: "infrastructure / system alerts", defaultChecked: true },
+    { localPart: "support", description: "customer-facing support", defaultChecked: true },
+    { localPart: "hi", description: "short personal alias", defaultChecked: false },
+];
+/** Whether to enable a catch-all rule (`*@domain` → destination) by
+ *  default. Catch-all is a safety net for anything not matched by an
+ *  explicit rule — recommended for personal/operator domains. */
+export const DEFAULT_CATCH_ALL = true;
+//# sourceMappingURL=presets.js.map

package/dist/email/presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.js","sourceRoot":"","sources":["../../src/email/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAWH,MAAM,CAAC,MAAM,uBAAuB,GAAyB;IAC3D,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,6BAA6B,EAAE,cAAc,EAAE,IAAI,EAAE;IACxF,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,IAAI,EAAE;IAC1E,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,gCAAgC,EAAE,cAAc,EAAE,IAAI,EAAE;IAC3F,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,yBAAyB,EAAE,cAAc,EAAE,IAAI,EAAE;IACtF,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,sBAAsB,EAAE,cAAc,EAAE,KAAK,EAAE;CAChF,CAAC;AAEF;;iEAEiE;AACjE,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC"}

package/dist/email/setup.d.ts

@@ -0,0 +1,93 @@
+import { type CfEmailDestination } from "../utils/cloudflare-api.js";
+/** Cloudflare-published MX hosts for Email Routing. Verified against
+ *  what `GET /zones/{id}/email/routing/dns` returns — kept hardcoded
+ *  so a hatchkit run can describe the records up-front without an
+ *  extra API call, and because the values have been stable since the
+ *  Email Routing product launched. The API stays the source of truth
+ *  in practice: the email module calls `getEmailRoutingDnsRecords()`
+ *  and uses *those* values, falling back to this list only if CF is
+ *  unreachable. */
+export declare const CLOUDFLARE_EMAIL_ROUTING_MX: {
+    host: string;
+    priority: number;
+}[];
+export interface EmailSetupOptions {
+    /** Bearer token with Zone:DNS:Edit + Zone:Email Routing Rules:Edit +
+     *  Account:Email Routing Addresses:Edit. */
+    token: string;
+    /** Optional Cloudflare account id. Discovered from the zone when
+     *  absent (since the destinations API is account-scoped, we always
+     *  need one before the call). */
+    accountId?: string;
+    /** Apex domain — must match a zone the token can access. */
+    domain: string;
+    /** Email address that will receive forwarded mail. CF sends a
+     *  verification email here on first add. */
+    destination: string;
+    /** Local parts to create forwarding rules for. Each becomes a
+     *  `<localPart>@<domain>` literal-match rule forwarding to
+     *  `destination`. Pass an empty list to skip individual rules
+     *  (still useful with `catchAll: true`). */
+    addresses: string[];
+    /** Whether to set a catch-all rule (`*@domain` → destination). */
+    catchAll: boolean;
+    /** SPF includes to merge with Cloudflare's. Use this when the zone
+     *  already sends via Resend / SES / etc. Pre-existing on-zone
+     *  records are also auto-merged. */
+    extraSpfIncludes?: string[];
+    /** DMARC policy. Defaults to "quarantine". */
+    dmarcPolicy?: "none" | "quarantine" | "reject";
+    /** Aggregate-report destination for DMARC. Defaults to
+     *  `dmarc@<domain>` (will be caught by the catch-all if enabled).
+     *  Override when you want CF Email Routing's reports forwarded to
+     *  a known inbox without relying on catch-all. */
+    dmarcRua?: string;
+}
+/** Per-resource report returned by {@link runEmailSetup}. The caller
+ *  feeds the ledger entries into `RunLedger.record()` for rollback. */
+export interface EmailSetupResult {
+    domain: string;
+    zoneId: string;
+    accountId: string;
+    /** True when this run was the one that enabled routing on the zone. */
+    routingEnabledThisRun: boolean;
+    destination: {
+        record: CfEmailDestination;
+        /** True when this run created the destination (verification email
+         *  was just sent). False when it already existed. */
+        createdThisRun: boolean;
+        /** "active" / "pending" — the user must click the verify link
+         *  before forwards land. */
+        verified: string | null;
+    };
+    /** DNS records the run created/updated. Each entry's `created` is
+     *  true when this run added it (use for the rollback ledger). */
+    dnsRecords: Array<{
+        id: string;
+        name: string;
+        type: "MX" | "TXT";
+        content: string;
+        created: boolean;
+        updated: boolean;
+    }>;
+    /** Per-address forwarding rules. */
+    rules: Array<{
+        address: string;
+        id: string;
+        created: boolean;
+        updated: boolean;
+    }>;
+    /** Catch-all is a zone-level singleton — toggled, not "created" in
+     *  the usual sense. `changed` is true when this run flipped its
+     *  enabled state or forward destination. */
+    catchAll?: {
+        enabled: boolean;
+        changed: boolean;
+    };
+}
+export declare function runEmailSetup(opts: EmailSetupOptions): Promise<EmailSetupResult>;
+/** Pretty-print the result for the CLI. Centralised here so both the
+ *  standalone command and the create/adopt-flow hook print the same
+ *  status block. */
+export declare function printEmailSetupSummary(result: EmailSetupResult): void;
+//# sourceMappingURL=setup.d.ts.map

package/dist/email/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/email/setup.ts"],"names":[],"mappings":"AA2BA,OAAO,EAEL,KAAK,kBAAkB,EAExB,MAAM,4BAA4B,CAAC;AAGpC;;;;;;;mBAOmB;AACnB,eAAO,MAAM,2BAA2B;;;GAIvC,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC;gDAC4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd;;qCAEiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf;gDAC4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB;;;gDAG4C;IAC5C,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kEAAkE;IAClE,QAAQ,EAAE,OAAO,CAAC;IAClB;;wCAEoC;IACpC,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,CAAC;IAC/C;;;sDAGkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;uEACuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,qBAAqB,EAAE,OAAO,CAAC;IAC/B,WAAW,EAAE;QACX,MAAM,EAAE,kBAAkB,CAAC;QAC3B;6DACqD;QACrD,cAAc,EAAE,OAAO,CAAC;QACxB;oCAC4B;QAC5B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;KACzB,CAAC;IACF;qEACiE;IACjE,UAAU,EAAE,KAAK,CAAC;QAChB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,IAAI,GAAG,KAAK,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC,CAAC;IACH,oCAAoC;IACpC,KAAK,EAAE,KAAK,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC,CAAC;IACH;;gDAE4C;IAC5C,QAAQ,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CACnD;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiKtF;AAgCD;;oBAEoB;AACpB,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAqDrE"}

package/dist/email/setup.js

@@ -0,0 +1,263 @@
+/*
+ * Email setup orchestrator.
+ *
+ * Configures Cloudflare Email Routing end-to-end for one zone:
+ *   1. Enable Email Routing on the zone (idempotent).
+ *   2. Verify (or add) the destination address — the verification email
+ *      lands in the user's inbox; they click the link before routing
+ *      starts working. Skipping verify isn't an option — Cloudflare
+ *      rejects forwards to unverified destinations.
+ *   3. Upsert the receiving MX records (3 Cloudflare hosts).
+ *   4. Upsert a single SPF TXT, merging Cloudflare's include with any
+ *      pre-existing senders (e.g. Resend). One SPF record per zone is
+ *      the RFC 7208 rule — multiple records cause PermError.
+ *   5. Upsert a DMARC TXT at `_dmarc.<zone>`. Default `p=quarantine`
+ *      with `sp=none` to avoid breaking subdomain senders.
+ *   6. Create the forwarding rules — one per `<localPart>@<zone>` →
+ *      destination. Idempotent: existing rules with matching matchers
+ *      get their forward updated; otherwise we POST a new rule.
+ *   7. Optionally set the catch-all (a single rule per zone, separate
+ *      endpoint from the rule list).
+ *
+ * Caller surfaces results via the {@link EmailSetupResult} so the
+ * create/adopt run-ledger can record each newly created resource for
+ * later rollback.
+ */
+import chalk from "chalk";
+import { CloudflareApi, } from "../utils/cloudflare-api.js";
+import { buildDmarcRecord, buildSpfRecord, parseSpfIncludes } from "./spf.js";
+/** Cloudflare-published MX hosts for Email Routing. Verified against
+ *  what `GET /zones/{id}/email/routing/dns` returns — kept hardcoded
+ *  so a hatchkit run can describe the records up-front without an
+ *  extra API call, and because the values have been stable since the
+ *  Email Routing product launched. The API stays the source of truth
+ *  in practice: the email module calls `getEmailRoutingDnsRecords()`
+ *  and uses *those* values, falling back to this list only if CF is
+ *  unreachable. */
+export const CLOUDFLARE_EMAIL_ROUTING_MX = [
+    { host: "route1.mx.cloudflare.net", priority: 1 },
+    { host: "route2.mx.cloudflare.net", priority: 2 },
+    { host: "route3.mx.cloudflare.net", priority: 3 },
+];
+export async function runEmailSetup(opts) {
+    const cf = new CloudflareApi({ token: opts.token, accountId: opts.accountId });
+    const zone = await cf.getZoneByName(opts.domain);
+    if (!zone) {
+        throw new Error(`No Cloudflare zone for "${opts.domain}". Add the zone to your CF account and re-run.`);
+    }
+    const accountId = opts.accountId ?? zone.account?.id;
+    if (!accountId) {
+        throw new Error(`Cloudflare account id could not be resolved for zone ${opts.domain}. Set it via \`hatchkit config add dns\` (advanced — leave blank only when the token spans one account).`);
+    }
+    // Step 1 — enable routing on the zone. Idempotent; CF returns the
+    // current settings on re-enable. We still record whether *this* call
+    // flipped enabled=false → true so the rollback ledger doesn't yank
+    // a routing setup the user enabled by hand earlier.
+    const beforeRouting = await cf.getEmailRouting(zone.id);
+    if (!beforeRouting?.enabled) {
+        await cf.enableEmailRouting(zone.id);
+    }
+    const routingEnabledThisRun = !beforeRouting?.enabled;
+    // Step 2 — destination address. CF sends a verification email if it
+    // didn't already exist.
+    const dest = await cf.addEmailDestination(accountId, opts.destination);
+    // Step 3 — MX records. Fetch CF's recommended list first (in case the
+    // hosts change), fall back to the constant if the call fails.
+    let mxRecords = CLOUDFLARE_EMAIL_ROUTING_MX.map((m) => ({
+        name: opts.domain,
+        content: m.host,
+        priority: m.priority,
+    }));
+    try {
+        const recommended = await cf.getEmailRoutingDnsRecords(zone.id);
+        const mx = recommended.filter((r) => r.type === "MX");
+        if (mx.length > 0) {
+            mxRecords = mx.map((r) => ({
+                name: r.name,
+                content: r.content,
+                priority: r.priority ?? 10,
+            }));
+        }
+    }
+    catch {
+        // Fall back to constants — see the comment on
+        // CLOUDFLARE_EMAIL_ROUTING_MX. CF's list is authoritative; the
+        // fallback keeps setup working if that one endpoint flakes.
+    }
+    const dnsRecords = [];
+    for (const mx of mxRecords) {
+        const res = await cf.upsertRecord(zone.id, {
+            type: "MX",
+            name: mx.name,
+            content: mx.content,
+            priority: mx.priority,
+        });
+        dnsRecords.push({
+            id: res.id,
+            name: mx.name,
+            type: "MX",
+            content: mx.content,
+            created: res.created,
+            updated: res.updated,
+        });
+    }
+    // Step 4 — SPF. Merge Cloudflare's include with whatever's already on
+    // the zone (Resend, SES, etc.) and any caller-supplied includes.
+    const existingSpf = await findApexSpf(cf, zone.id, opts.domain);
+    const mergedIncludes = new Set(["_spf.mx.cloudflare.net"]);
+    for (const inc of opts.extraSpfIncludes ?? [])
+        mergedIncludes.add(inc);
+    if (existingSpf) {
+        for (const inc of parseSpfIncludes(existingSpf.content))
+            mergedIncludes.add(inc);
+    }
+    const spfContent = buildSpfRecord({ includes: [...mergedIncludes] });
+    // Delete any *other* SPF TXT records first — exactly one SPF record
+    // per zone per RFC 7208. The upsert below patches `existingSpf` in
+    // place; stale duplicates (zone moved between providers, etc.) get
+    // removed here.
+    await deleteStaleSpfRecords(cf, zone.id, opts.domain, existingSpf?.id);
+    const spfRes = await cf.upsertRecord(zone.id, {
+        type: "TXT",
+        name: opts.domain,
+        content: spfContent,
+    });
+    dnsRecords.push({
+        id: spfRes.id,
+        name: opts.domain,
+        type: "TXT",
+        content: spfContent,
+        created: spfRes.created,
+        updated: spfRes.updated,
+    });
+    // Step 5 — DMARC.
+    const dmarcName = `_dmarc.${opts.domain}`;
+    const dmarcContent = buildDmarcRecord({
+        rua: opts.dmarcRua ?? `dmarc@${opts.domain}`,
+        policy: opts.dmarcPolicy ?? "quarantine",
+    });
+    const dmarcRes = await cf.upsertRecord(zone.id, {
+        type: "TXT",
+        name: dmarcName,
+        content: dmarcContent,
+    });
+    dnsRecords.push({
+        id: dmarcRes.id,
+        name: dmarcName,
+        type: "TXT",
+        content: dmarcContent,
+        created: dmarcRes.created,
+        updated: dmarcRes.updated,
+    });
+    // Step 6 — per-address forwarding rules.
+    const rules = [];
+    for (const localPart of opts.addresses) {
+        const address = `${localPart}@${opts.domain}`;
+        const res = await cf.upsertEmailRoutingRule(zone.id, {
+            address,
+            forwardTo: [opts.destination],
+            name: `Forward ${address}`,
+        });
+        rules.push({ address, id: res.id, created: res.created, updated: res.updated });
+    }
+    // Step 7 — catch-all (zone-level singleton). `changed` reflects the
+    // catch-all rule itself — its `enabled` flag and forward destination —
+    // not the zone-level Email Routing toggle (that's `routingEnabledThisRun`).
+    let catchAll;
+    if (opts.catchAll) {
+        const beforeRule = await cf.getEmailCatchAll(zone.id);
+        const beforeEnabled = beforeRule?.enabled ?? false;
+        const beforeForward = (beforeRule?.actions?.[0]?.value ?? []).join(",");
+        const wantForward = [opts.destination].join(",");
+        await cf.setEmailCatchAll(zone.id, {
+            forwardTo: [opts.destination],
+            enabled: true,
+            name: "Catch-all",
+        });
+        catchAll = { enabled: true, changed: !beforeEnabled || beforeForward !== wantForward };
+    }
+    return {
+        domain: opts.domain,
+        zoneId: zone.id,
+        accountId,
+        routingEnabledThisRun,
+        destination: {
+            record: dest,
+            createdThisRun: !dest.existed,
+            verified: dest.verified ?? null,
+        },
+        dnsRecords,
+        rules,
+        catchAll,
+    };
+}
+/** Find the apex SPF TXT record (one starting with `v=spf1`). Returns
+ *  null when no SPF record exists yet. There MAY be other TXT records
+ *  at the apex (verification tokens, etc.) — they're left alone. */
+async function findApexSpf(cf, zoneId, domain) {
+    const all = await cf.findRecordsByName(zoneId, domain, "TXT");
+    return all.find((r) => /^"?v=spf1\b/i.test(r.content)) ?? null;
+}
+/** Delete every *other* SPF TXT at the apex except the one we're about
+ *  to upsert. Multiple SPF records cause receivers to PermError per
+ *  RFC 7208, so a clean zone has exactly one. Skips the record we're
+ *  keeping (identified by id). */
+async function deleteStaleSpfRecords(cf, zoneId, domain, keepId) {
+    const all = await cf.findRecordsByName(zoneId, domain, "TXT");
+    for (const rec of all) {
+        if (!/^"?v=spf1\b/i.test(rec.content))
+            continue;
+        if (rec.id === keepId)
+            continue;
+        await cf.deleteRecord(zoneId, rec.id);
+    }
+}
+/** Pretty-print the result for the CLI. Centralised here so both the
+ *  standalone command and the create/adopt-flow hook print the same
+ *  status block. */
+export function printEmailSetupSummary(result) {
+    console.log(chalk.bold(`\n  ── Email setup: ${result.domain} ──────────────────────────\n`));
+    if (result.routingEnabledThisRun) {
+        console.log(chalk.green("  ✓ Enabled Cloudflare Email Routing on zone"));
+    }
+    else {
+        console.log(chalk.dim("  · Email Routing already enabled"));
+    }
+    const verifySuffix = result.destination.verified === "active"
+        ? chalk.green(" (verified)")
+        : chalk.yellow(" (pending — check inbox + click verify link)");
+    if (result.destination.createdThisRun) {
+        console.log(chalk.green(`  ✓ Added destination ${result.destination.record.email}`) + verifySuffix);
+    }
+    else {
+        console.log(chalk.dim(`  · Destination ${result.destination.record.email} already on account`) +
+            verifySuffix);
+    }
+    for (const rec of result.dnsRecords) {
+        const tag = rec.created
+            ? chalk.green("✓ created")
+            : rec.updated
+                ? chalk.yellow("· updated")
+                : chalk.dim("· unchanged");
+        console.log(`  ${tag} ${rec.type.padEnd(4)} ${rec.name}  →  ${truncate(rec.content, 60)}`);
+    }
+    for (const r of result.rules) {
+        const tag = r.created
+            ? chalk.green("✓ created")
+            : r.updated
+                ? chalk.yellow("· updated")
+                : chalk.dim("· unchanged");
+        console.log(`  ${tag} rule ${r.address}`);
+    }
+    if (result.catchAll) {
+        const tag = result.catchAll.changed ? chalk.green("✓ enabled") : chalk.dim("· already enabled");
+        console.log(`  ${tag} catch-all *@${result.domain}`);
+    }
+    if (result.destination.verified !== "active") {
+        console.log(chalk.yellow(`\n  ! Forwards won't deliver until ${result.destination.record.email} clicks the Cloudflare verification email.`));
+    }
+}
+function truncate(s, n) {
+    return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+//# sourceMappingURL=setup.js.map

package/dist/email/setup.js.map

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

package/dist/email/spf.d.ts

@@ -0,0 +1,56 @@
+/** Common SPF includes for popular senders. The Resend value is the
+ *  one their dashboard tells you to add; AWS SES users would substitute
+ *  `amazonses.com` etc. Hatchkit auto-includes Cloudflare's host; other
+ *  senders come from configuration. */
+export declare const SPF_INCLUDES: {
+    readonly cloudflareEmailRouting: "_spf.mx.cloudflare.net";
+    readonly resend: "_spf.resend.com";
+    readonly amazonSes: "amazonses.com";
+    readonly google: "_spf.google.com";
+};
+export type SpfQualifier = "~all" | "-all" | "?all" | "+all";
+/** Build a single SPF TXT record content string. Sorts includes for
+ *  deterministic output (matters for idempotent upserts: same input =
+ *  same record content = no PATCH on re-run). */
+export declare function buildSpfRecord(opts: {
+    /** Hostnames to wrap as `include:<host>`. Order-insensitive. */
+    includes: string[];
+    /** Optional `ip4:` / `ip6:` mechanisms. */
+    ip4?: string[];
+    ip6?: string[];
+    /** Default `~all` — see file header. */
+    qualifier?: SpfQualifier;
+}): string;
+/** Parse the includes out of an existing SPF record so we can union
+ *  them with new ones (e.g. when adding Cloudflare to a zone that
+ *  already has Resend). Lenient: returns an empty list for malformed
+ *  input rather than throwing — the caller can decide whether to
+ *  overwrite or surface the parse failure. */
+export declare function parseSpfIncludes(record: string): string[];
+/** Build a DMARC TXT record content string.
+ *
+ *  Default policy is `p=quarantine` — failed-DMARC mail lands in spam
+ *  rather than the inbox. `sp=none` deliberately exempts subdomains
+ *  (e.g. `staging.<domain>`) because they often send via third-party
+ *  services not aligned with the apex. `rua` is the aggregate-report
+ *  destination — same address as the forwarding inbox by default, so
+ *  the operator gets weekly delivery summaries.
+ *
+ *  Tweaks (call sites can override):
+ *   · `policy: "none"` — observe-only, no enforcement. Use during
+ *     a soft rollout when you're not sure every legit sender is
+ *     aligned yet.
+ *   · `subdomainPolicy: "quarantine"` — extend enforcement to
+ *     subdomains. Only safe once those subdomains' senders are known. */
+export declare function buildDmarcRecord(opts: {
+    rua: string;
+    policy?: "none" | "quarantine" | "reject";
+    subdomainPolicy?: "none" | "quarantine" | "reject";
+    /** Percentage of mail subject to policy (0-100). Default 100. Drop
+     *  to e.g. 20 during a soft rollout. */
+    percent?: number;
+    /** SPF/DKIM alignment mode — strict ("s") or relaxed ("r"). */
+    alignmentSpf?: "s" | "r";
+    alignmentDkim?: "s" | "r";
+}): string;
+//# sourceMappingURL=spf.d.ts.map

package/dist/email/spf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spf.d.ts","sourceRoot":"","sources":["../../src/email/spf.ts"],"names":[],"mappings":"AAgCA;;;uCAGuC;AACvC,eAAO,MAAM,YAAY;;;;;CAKf,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7D;;iDAEiD;AACjD,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,gEAAgE;IAChE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,wCAAwC;IACxC,SAAS,CAAC,EAAE,YAAY,CAAC;CAC1B,GAAG,MAAM,CAUT;AAED;;;;8CAI8C;AAC9C,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CASzD;AAED;;;;;;;;;;;;;;yEAcyE;AACzE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,CAAC;IAC1C,eAAe,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,CAAC;IACnD;4CACwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;IACzB,aAAa,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;CAC3B,GAAG,MAAM,CAWT"}

package/dist/email/spf.js

@@ -0,0 +1,102 @@
+/*
+ * SPF + DMARC TXT-record helpers.
+ *
+ * SPF rules-of-the-road that make this small but important:
+ *
+ *   1. **One SPF TXT per domain.** RFC 7208 §3.2 — multiple records
+ *      cause receivers to PermError. So if Resend's records already
+ *      include `v=spf1 …` and Cloudflare Email Routing wants its own
+ *      `v=spf1 …`, they MUST be merged into ONE record, not added as
+ *      siblings.
+ *
+ *   2. **Maximum 10 DNS lookups inside the SPF chain.** Each `include:`
+ *      counts as one lookup. Cloudflare Email Routing's
+ *      `_spf.mx.cloudflare.net` and (e.g.) Resend's
+ *      `_spf.resend.com` each cost one — well under the cap, but worth
+ *      knowing if a user later piles on more senders.
+ *
+ *   3. **Order of `include:` mechanisms does NOT matter for the verdict,
+ *      but a stable order makes hatchkit's idempotent upserts a no-op
+ *      on re-run.** We sort the includes alphabetically before joining.
+ *
+ *   4. **Qualifier (`~all` vs `-all`):** we default to `~all` (softfail)
+ *      — recipients see a soft signal that mail from unauthorised IPs
+ *      is suspicious but they still accept it. This pairs well with
+ *      DMARC at `p=quarantine`, which makes the final disposition call
+ *      via alignment rather than SPF-fail-alone. Upgrade to `-all`
+ *      (hardfail) once you're confident no legitimate sender is missing
+ *      from the include list.
+ */
+const CLOUDFLARE_EMAIL_ROUTING_SPF_INCLUDE = "_spf.mx.cloudflare.net";
+/** Common SPF includes for popular senders. The Resend value is the
+ *  one their dashboard tells you to add; AWS SES users would substitute
+ *  `amazonses.com` etc. Hatchkit auto-includes Cloudflare's host; other
+ *  senders come from configuration. */
+export const SPF_INCLUDES = {
+    cloudflareEmailRouting: CLOUDFLARE_EMAIL_ROUTING_SPF_INCLUDE,
+    resend: "_spf.resend.com",
+    amazonSes: "amazonses.com",
+    google: "_spf.google.com",
+};
+/** Build a single SPF TXT record content string. Sorts includes for
+ *  deterministic output (matters for idempotent upserts: same input =
+ *  same record content = no PATCH on re-run). */
+export function buildSpfRecord(opts) {
+    const includes = [...new Set(opts.includes)].sort();
+    const ip4 = opts.ip4 ? [...new Set(opts.ip4)].sort() : [];
+    const ip6 = opts.ip6 ? [...new Set(opts.ip6)].sort() : [];
+    const parts = ["v=spf1"];
+    for (const i of ip4)
+        parts.push(`ip4:${i}`);
+    for (const i of ip6)
+        parts.push(`ip6:${i}`);
+    for (const inc of includes)
+        parts.push(`include:${inc}`);
+    parts.push(opts.qualifier ?? "~all");
+    return parts.join(" ");
+}
+/** Parse the includes out of an existing SPF record so we can union
+ *  them with new ones (e.g. when adding Cloudflare to a zone that
+ *  already has Resend). Lenient: returns an empty list for malformed
+ *  input rather than throwing — the caller can decide whether to
+ *  overwrite or surface the parse failure. */
+export function parseSpfIncludes(record) {
+    const trimmed = record.trim().replace(/^"|"$/g, "").trim();
+    if (!/^v=spf1\b/i.test(trimmed))
+        return [];
+    const includes = [];
+    for (const part of trimmed.split(/\s+/)) {
+        const m = part.match(/^include:(.+)$/i);
+        if (m)
+            includes.push(m[1].toLowerCase());
+    }
+    return includes;
+}
+/** Build a DMARC TXT record content string.
+ *
+ *  Default policy is `p=quarantine` — failed-DMARC mail lands in spam
+ *  rather than the inbox. `sp=none` deliberately exempts subdomains
+ *  (e.g. `staging.<domain>`) because they often send via third-party
+ *  services not aligned with the apex. `rua` is the aggregate-report
+ *  destination — same address as the forwarding inbox by default, so
+ *  the operator gets weekly delivery summaries.
+ *
+ *  Tweaks (call sites can override):
+ *   · `policy: "none"` — observe-only, no enforcement. Use during
+ *     a soft rollout when you're not sure every legit sender is
+ *     aligned yet.
+ *   · `subdomainPolicy: "quarantine"` — extend enforcement to
+ *     subdomains. Only safe once those subdomains' senders are known. */
+export function buildDmarcRecord(opts) {
+    const parts = [
+        "v=DMARC1",
+        `p=${opts.policy ?? "quarantine"}`,
+        `sp=${opts.subdomainPolicy ?? "none"}`,
+        `rua=mailto:${opts.rua}`,
+        `pct=${opts.percent ?? 100}`,
+        `adkim=${opts.alignmentDkim ?? "r"}`,
+        `aspf=${opts.alignmentSpf ?? "r"}`,
+    ];
+    return parts.join("; ");
+}
+//# sourceMappingURL=spf.js.map

package/dist/email/spf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spf.js","sourceRoot":"","sources":["../../src/email/spf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,oCAAoC,GAAG,wBAAwB,CAAC;AAEtE;;;uCAGuC;AACvC,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,sBAAsB,EAAE,oCAAoC;IAC5D,MAAM,EAAE,iBAAiB;IACzB,SAAS,EAAE,eAAe;IAC1B,MAAM,EAAE,iBAAiB;CACjB,CAAC;AAIX;;iDAEiD;AACjD,MAAM,UAAU,cAAc,CAAC,IAQ9B;IACC,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACpD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,MAAM,KAAK,GAAG,CAAC,QAAQ,CAAC,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,GAAG;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,GAAG;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5C,KAAK,MAAM,GAAG,IAAI,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC,CAAC;IACzD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC,CAAC;IACrC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;;;8CAI8C;AAC9C,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3D,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QACxC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACxC,IAAI,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;yEAcyE;AACzE,MAAM,UAAU,gBAAgB,CAAC,IAUhC;IACC,MAAM,KAAK,GAAa;QACtB,UAAU;QACV,KAAK,IAAI,CAAC,MAAM,IAAI,YAAY,EAAE;QAClC,MAAM,IAAI,CAAC,eAAe,IAAI,MAAM,EAAE;QACtC,cAAc,IAAI,CAAC,GAAG,EAAE;QACxB,OAAO,IAAI,CAAC,OAAO,IAAI,GAAG,EAAE;QAC5B,SAAS,IAAI,CAAC,aAAa,IAAI,GAAG,EAAE;QACpC,QAAQ,IAAI,CAAC,YAAY,IAAI,GAAG,EAAE;KACnC,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}