@aglyn/shared-util-email 1.0.0-beta.143

package/src/lib/sending-domain.js

@@ -0,0 +1,798 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * CUSTOM SENDING DOMAINS — policy half.
+ *
+ * Everything the platform sends leaves from one verified identity
+ * (`USAGE_EMAIL_FROM`) on one domain. A tenant's campaign and another tenant's
+ * password reset therefore share a DKIM `d=` and a reputation: one merchant's
+ * complaint rate is charged against every merchant's authentication mail. A
+ * custom sending domain is the control that moves a tenant's reputation onto a
+ * domain that tenant owns.
+ *
+ * ## Pure, and dependency-free, for the same reason `send-rate.ts` is
+ *
+ * The decision — which identity does this send leave on, and may it leave at
+ * all — is a pure function of a stored record and the environment. It is
+ * unit-testable with no Firestore harness, no DNS resolver and no route. The
+ * durable half (the record, the DNS probe, the verification sweep) lives in
+ * `@aglyn/tenant-data-admin`, which is the only layer that may hold the Admin
+ * SDK. `@aglyn/shared-util-email` is `scope:shared` and may not import it.
+ *
+ * ## THE BOUNDARY THAT MATTERS MOST
+ *
+ * **A CUSTOMER'S OWN sending domain that is not verified refuses the send. It
+ * never falls back to any other identity.** {@link resolveSendingIdentity} has
+ * no arm that reaches another address from such a domain, and
+ * {@link sendingIdentityRefusal} is what a caller must print.
+ *
+ * Silent fallback would be wrong three ways, and each is independently
+ * disqualifying: the customer believes their DNS is finished when it is not;
+ * the recipient sees a `From:` they did not expect from a brand they did;
+ * and the tenant's reputation risk lands back on the shared domain the custom
+ * domain existed to move it off.
+ *
+ * **WHOSE DOMAIN IT IS carries the whole rule**, and it is the distinction
+ * `SendingDomainSelection.platformIssued` records. There are three cases and
+ * only the first refuses:
+ *
+ *   - A domain the CUSTOMER owns, unverified. An instruction of theirs that we
+ *     would be ignoring. Refused.
+ *   - A platform subdomain we issued, unverified. The merchant asked for a
+ *     domain; we chose the name, wrote the records and pointed the site at
+ *     it, so there is nothing of theirs to contradict and everything that can
+ *     leave it unfinished is ours to fix. Sends on the pool.
+ *   - Nothing selected. Likewise no statement to contradict, and the site
+ *     still has receipts to send. Sends on the pool, which is what the console
+ *     has always told merchants happens.
+ *
+ * The last two are why the DEDICATED subdomain can be rationed safely: it is
+ * an optimization on top of a floor that always holds, so exhausting the
+ * provider's domain allowance degrades delivery reputation rather than
+ * stopping the mail.
+ *
+ * ## The shared identity carries marketing too, and is GRADED for it
+ *
+ * The shared identity pools reputation across every site using it, so one
+ * merchant's imported list is charged against every other site's password
+ * resets. The answer to that is measurement, not exclusion: refusing marketing
+ * outright made campaigns unreachable for every site that had not bought a
+ * domain, while doing nothing about the pooled site whose receipts were already
+ * bouncing.
+ *
+ * So a pooled campaign is graded against the STRICTER reputation thresholds —
+ * the watch levels in `sender-reputation.ts` rather than the trip levels — and
+ * the site earning the complaints is the one that stops. `sendEmail` refuses
+ * outright only the case a seven-day window cannot catch in time: bulk mail
+ * carrying no unsubscribe link, which is {@link pooledMarketingRefusal}.
+ *
+ * That is a REPUTATION rule and not a pricing one. Which plans may run a
+ * campaign at all is an entitlement decided elsewhere, and nothing here reads
+ * a plan.
+ *
+ * The failure mode this guards against is the house one. `USAGE_EMAIL_FROM`
+ * was empty in production for weeks; because mail is best-effort at every
+ * call site, every send returned `{sent: false, reason: 'unconfigured'}`,
+ * nothing threw, and no surface said anything was wrong. A refusal that is
+ * only a log line is that same defect wearing a new reason string — so the
+ * refusal carries the domain, the missing records, and a sentence a person can
+ * act on, and the campaign route answers it as a `409` rather than a no-op.
+ *
+ * ## Scope: this module issues records and decides. It does not verify.
+ *
+ * Reading live DNS belongs to the durable half, which reuses the pinned-
+ * resolver probe that already backs SSO domain verification — the one that
+ * distinguishes "the record is absent" from "nobody answered". That third
+ * state is why {@link SendingDomainStatus} has no arm meaning "checked and we
+ * are not sure": an unreachable resolver leaves the stored status alone.
+ */ /*==========================================
+  The record
+==========================================*/ /**
+ * Where a domain is in its verification lifecycle.
+ *
+ * Persisted, unlike the site-domain machine's live-computed
+ * `ProjectDomainState`. A site domain can be re-read from the hosting provider
+ * on every request; a sending domain's proof is a DKIM key the mail provider
+ * issued once, and the send path must be able to answer "may this leave?"
+ * without a network call on the critical path of every message.
+ */ /** The lifecycle in order, for a surface that renders progress. */ export const SENDING_DOMAIN_STATUSES = [
+    'requested',
+    'records-issued',
+    'verified',
+    'failed'
+];
+/**
+ * The one {@link SendingDomainRecord.lastIssueError} value that is not a
+ * provider failure.
+ *
+ * A dedicated platform subdomain draws on an allowance the provider grants the
+ * whole account, so a claim made while that allowance is spent is refused
+ * before any call is made. It is stored in the same field as a provider
+ * refusal because it is the same fact from the record's point of view — no key
+ * was issued, and the domain stays `requested` — but it is a DIFFERENT
+ * sentence to the person reading it: nothing failed, nobody's DNS is wrong,
+ * and pressing the retry does not move it until there is room.
+ *
+ * Named here rather than at either end because the two ends are in different
+ * projects: the console's provisioning sweep writes it and the email plugin's
+ * status model reads it, and a string spelled out twice is one a rename
+ * silently breaks in the surface rather than in the writer.
+ */ export const SENDING_DOMAIN_AT_CAPACITY = 'at-capacity';
+/**
+ * A provider's failure reduced to something safe to store, log and print.
+ *
+ * Provider error bodies are attacker-adjacent text we did not write, and the
+ * one thing that must never appear in a Firestore document, a log line or an
+ * admin surface is the credential that made the call. Vendor keys have a
+ * recognizable shape — a short prefix, an underscore, a long opaque body
+ * (`re_`, `sk_`, `rk_`, `whsec_`) — and an `Authorization` header echoed into
+ * an error message carries the whole thing.
+ *
+ * This is the LAST line rather than the only one: callers build their detail
+ * from a fixed vocabulary and never from response prose, so nothing should
+ * reach here that needs redacting. A guard that is only ever a no-op in
+ * practice is exactly the guard worth having on a secret.
+ */ export function safeProviderDetail(input) {
+    return String(input != null ? input : '').replace(/\bBearer\s+\S+/gi, 'Bearer [redacted]').replace(/\b[A-Za-z]{2,8}_[A-Za-z0-9]{12,}\b/g, '[redacted]').trim().slice(0, 120);
+}
+/*==========================================
+  Domain validation
+==========================================*/ const DOMAIN_PATTERN = /^(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))+$/;
+/**
+ * Domains whose mail nobody but their operator may authorize.
+ *
+ * Publishing our DKIM record in one of these zones is impossible, so a claim
+ * on one can never verify — but refusing it up front is a sentence the
+ * customer can act on rather than a verification that silently never
+ * completes.
+ */ const PUBLIC_EMAIL_DOMAINS = new Set([
+    'gmail.com',
+    'googlemail.com',
+    'yahoo.com',
+    'ymail.com',
+    'hotmail.com',
+    'outlook.com',
+    'live.com',
+    'msn.com',
+    'aol.com',
+    'icloud.com',
+    'me.com',
+    'mac.com',
+    'proton.me',
+    'protonmail.com',
+    'gmx.com',
+    'zoho.com',
+    'fastmail.com',
+    'hey.com',
+    'qq.com',
+    '163.com',
+    '126.com'
+]);
+export function normalizeSendingDomain(input) {
+    const raw = String(input != null ? input : '').trim().toLowerCase();
+    const at = raw.lastIndexOf('@');
+    return (at >= 0 ? raw.slice(at + 1) : raw).replace(/^@+/, '').replace(/\.$/, '');
+}
+export function validateSendingDomain(input) {
+    const domain = normalizeSendingDomain(input);
+    if (!domain || !DOMAIN_PATTERN.test(domain)) {
+        return {
+            domain: null,
+            error: 'Enter a valid domain, for example acme.com'
+        };
+    }
+    if (PUBLIC_EMAIL_DOMAINS.has(domain)) {
+        return {
+            domain: null,
+            error: 'Mailbox providers do not delegate sending for their own domains, so ' + 'this domain can never be verified. Use a domain you own.'
+        };
+    }
+    return {
+        domain,
+        error: null
+    };
+}
+/**
+ * The mailbox part of an address, validated so a stored `localPart` cannot
+ * smuggle a second address or a header into the `From:` line.
+ */ export function normalizeLocalPart(input) {
+    const raw = String(input != null ? input : '').trim().toLowerCase();
+    return /^[a-z0-9](?:[a-z0-9._+-]{0,62}[a-z0-9])?$/.test(raw) ? raw : '';
+}
+/*==========================================
+  The records the customer must publish
+==========================================*/ /**
+ * The subdomain the envelope sender and its bounce routing live on.
+ *
+ * A subdomain rather than the root for two reasons the customer feels: their
+ * existing root SPF is untouched, so their Workspace or Microsoft mail keeps
+ * authenticating; and this SPF does not spend any of the root record's
+ * ten-lookup budget, which is a limit that fails closed and is easy to reach.
+ */ export const SENDING_SUBDOMAIN = 'send';
+/**
+ * `||` not `??`, matching the rest of the env reads in this repo: an empty
+ * string is a variable somebody set to nothing, not a configured value, and an
+ * empty SPF include would print an instruction that authorizes no one.
+ *
+ * Configurable because a self-host operator may front a different provider —
+ * the same reason `AGLYN_DOMAIN_PROVIDER` exists. The defaults describe the
+ * provider this deployment actually uses.
+ */ export function sendingSpfInclude() {
+    return process.env.AGLYN_EMAIL_SPF_INCLUDE || 'amazonses.com';
+}
+export function sendingReturnPathHost() {
+    return process.env.AGLYN_EMAIL_RETURN_PATH_HOST || 'feedback-smtp.us-east-1.amazonses.com';
+}
+/**
+ * The label the CLICK-TRACKING host hangs off the sending domain.
+ *
+ * An ESP measures clicks by rewriting every `<a href>` to point at this host
+ * and redirecting from it, so it needs a name of its own with a TLS
+ * certificate. `links` is what the platform's own domains already use, and
+ * keeping one label across every domain class means an operator reading a
+ * zone sees the same name everywhere.
+ */ export const SENDING_TRACKING_SUBDOMAIN = 'links';
+/**
+ * The certificate authority the tracking host's TLS certificate comes from.
+ *
+ * Only ever consulted to build a CAA record, and only matters for a domain
+ * that ALREADY publishes CAA — see the note on the record itself. Configurable
+ * for the same reason {@link sendingSpfInclude} is: a self-host operator
+ * fronting a different provider fronts a different CA.
+ */ export function sendingTrackingCertAuthority() {
+    return process.env.AGLYN_EMAIL_TRACKING_CA || 'amazon.com';
+}
+/**
+ * How long a tracked domain is held before its provider object is released.
+ *
+ * Every link in every message a tracked domain has already sent points at
+ * that domain's tracking host, and the provider deletes the host with the
+ * domain — a tracking subdomain cannot even be removed on its own, precisely
+ * because live mail points at it. So a same-day teardown does not merely stop
+ * future tracking, it retroactively breaks the links in mail already
+ * delivered, for recipients who have done nothing.
+ *
+ * 30 days is the window most campaign clicks arrive in, and it costs one
+ * provider domain slot per released site for that long — the trade is
+ * deliberate and the ceiling is documented in `provision-sending-domain.ts`.
+ * `0` disables the hold for an operator who would rather have the slot back.
+ *
+ * ⚠️ It does NOT gate an erasure. A person asking to be erased outranks a
+ * link, and the caller passes `immediate` for that path.
+ */ export function sendingTrackingRetentionDays() {
+    const raw = Number(process.env.AGLYN_SENDING_TRACKING_RETENTION_DAYS);
+    return Number.isFinite(raw) && raw >= 0 ? raw : 30;
+}
+/**
+ * Every record for a domain, in the order a customer should create them.
+ *
+ * ONE function, so the records a card prints and the records the verifier
+ * accepts cannot drift apart. `tenant-dns.ts` carries the same invariant for
+ * site domains and documents what it cost to learn: a wizard printing one
+ * target while the route checked another produced a check that could not fail,
+ * then a check that could not pass, over three separate issues.
+ *
+ * The DKIM value is absent until the provider issues a key. That is a real
+ * state, not an error — {@link sendingDomainRequiredRecords} treats a record
+ * with no value as unpublishable and keeps the domain out of `records-issued`.
+ */ export function sendingDnsRecords(record) {
+    var _ref, _ref1;
+    const domain = normalizeSendingDomain(record == null ? void 0 : record.domain);
+    const selector = String((_ref = record == null ? void 0 : record.dkimSelector) != null ? _ref : '').trim() || 'aglyn';
+    const sendHost = `${SENDING_SUBDOMAIN}.${domain}`;
+    const returnPath = (record == null ? void 0 : record.returnPathHost) || sendingReturnPathHost();
+    const dkimKey = String((_ref1 = record == null ? void 0 : record.dkimPublicKey) != null ? _ref1 : '').trim();
+    return [
+        {
+            type: 'TXT',
+            name: sendHost,
+            value: `v=spf1 include:${sendingSpfInclude()} ~all`,
+            purpose: 'spf',
+            required: true,
+            note: `Authorizes our infrastructure for mail whose envelope sender is ` + `${sendHost}. It sits on this subdomain so your existing root SPF is ` + `untouched.`
+        },
+        {
+            type: 'TXT',
+            name: `${selector}._domainkey.${domain}`,
+            value: dkimKey ? `p=${dkimKey}` : '',
+            purpose: 'dkim',
+            required: true,
+            note: 'The signing key. This is the record DMARC alignment depends on — ' + 'without it, mail from your domain fails whatever policy you publish.'
+        },
+        {
+            type: 'MX',
+            name: sendHost,
+            value: returnPath,
+            priority: 10,
+            purpose: 'return-path',
+            required: true,
+            note: 'Routes bounces and spam complaints back to us so they can be ' + 'suppressed. It is on the send subdomain and does not affect mail ' + 'delivered to your normal inboxes.'
+        },
+        ...trackingRecords(domain, record == null ? void 0 : record.trackingTarget)
+    ];
+}
+/**
+ * The two records that make CLICK TRACKING work, and neither is required.
+ *
+ * An ESP measures a click by rewriting every `<a href>` in the HTML part to
+ * point at a tracking host on the sending domain, then redirecting. No host,
+ * no rewriting, and the click rate is structurally 0% — which reads on a
+ * dashboard as low engagement rather than as a wiring fault, so it stays
+ * unnoticed. That is the same shape as the `"html": ""` defect this library
+ * already carries a fix for, one layer up.
+ *
+ * ## Why `required: false`
+ *
+ * Verification is about AUTHENTICATION — can this domain prove it sent the
+ * mail. Tracking is measurement. A customer who publishes SPF, DKIM and the
+ * return path can send perfectly well and must not be held at `requested`
+ * over a record that only decides whether we can count clicks; and making
+ * these required would un-verify every domain already verified without them.
+ * {@link sendingDomainPublishableRecords} is what puts them in a zone we own.
+ *
+ * ## ⚠️ The CAA record is the one that can hurt
+ *
+ * CAA restricts which authorities may issue a certificate for a name, and the
+ * lookup stops at the FIRST name in the tree that publishes any. So:
+ *
+ *  - A domain publishing NO CAA today needs nothing. Any authority may
+ *    already issue, and adding this record would be the change that starts
+ *    restricting them.
+ *  - A domain that DOES publish CAA has to ADD this one alongside what it has,
+ *    never in place of it. Replacing the set is how a zone stops its own web
+ *    certificates renewing.
+ *
+ * It is emitted on the sending domain rather than on the registrable root so
+ * that a customer following it verbatim scopes the permission to the name we
+ * put a tracking host under, instead of widening it across everything they
+ * own. Deriving the registrable root would need a public-suffix list this
+ * library does not have, and a guess at it prints a record for the wrong name.
+ *
+ * @returns nothing at all until the provider has issued a tracking target.
+ *          A CNAME with no value is a record that says nothing while looking
+ *          published, the same rule the DKIM row follows.
+ */ function trackingRecords(domain, trackingTarget) {
+    const target = String(trackingTarget != null ? trackingTarget : '').trim();
+    if (!domain || !target) return [];
+    const authority = sendingTrackingCertAuthority();
+    return [
+        {
+            type: 'CNAME',
+            name: `${SENDING_TRACKING_SUBDOMAIN}.${domain}`,
+            value: target,
+            purpose: 'tracking',
+            required: false,
+            note: 'Counts link clicks. Every link in an email is rewritten to point ' + 'here and redirected, so without it clicks cannot be measured at ' + 'all — mail still sends, and the click rate reads a permanent 0%.'
+        },
+        {
+            type: 'CAA',
+            name: domain,
+            value: `0 issue "${authority}"`,
+            purpose: 'tracking-caa',
+            required: false,
+            note: `Only needed if this domain already publishes CAA records. Add this ` + `one ALONGSIDE them — replacing the set would stop your other ` + `certificates renewing. If you publish no CAA at all, skip it: any ` + `authority may already issue, and ${authority} is the one that ` + `issues the certificate for the tracking host above.`
+        }
+    ];
+}
+/** The subset verification waits on, and only those with a value to publish. */ export function sendingDomainRequiredRecords(record) {
+    return sendingDnsRecords(record).filter((entry)=>entry.required && Boolean(entry.value));
+}
+/**
+ * Everything worth WRITING into a zone this platform owns.
+ *
+ * Deliberately wider than {@link sendingDomainRequiredRecords}, and the gap
+ * between them is the whole point. `required` answers "does verification wait
+ * on this", which tracking must not; this answers "should we publish it",
+ * which tracking must be — a platform subdomain's zone is ours, so there is
+ * nobody to ask and no reason to leave the click rate at zero.
+ *
+ * Reusing the required set here is what left the platform's own subdomains
+ * untracked: one flag was being asked two different questions, and the
+ * conservative answer to the first silently decided the second.
+ *
+ * DMARC is still excluded — it carries `required: false` too, but a policy is
+ * the domain owner's to choose and this platform publishes one deliberately
+ * elsewhere, not as a side effect of provisioning.
+ */ export function sendingDomainPublishableRecords(record) {
+    return sendingDnsRecords(record).filter((entry)=>Boolean(entry.value) && (entry.required || entry.purpose === 'tracking'));
+}
+/**
+ * A stable key for one record, used to report which are still missing without
+ * putting a full DKIM public key into a status document or a log line.
+ */ export function sendingRecordKey(entry) {
+    return `${entry.type}:${entry.name}`;
+}
+/** `TXT   send.acme.com   →   v=spf1 …`, matching `formatDnsInstruction`. */ export function formatSendingRecord(entry) {
+    const target = entry.priority ? `${entry.priority} ${entry.value}` : entry.value;
+    return `${String(entry.type).padEnd(5)}  ${entry.name}  →  ${target}`;
+}
+/**
+ * Read a `_dmarc` TXT answer.
+ *
+ * Only records that actually begin `v=DMARC1` count. A zone often carries
+ * unrelated TXT records at any name, and treating the first string found as a
+ * policy would report a verification token as `p=none`.
+ */ export function assessDmarc(records) {
+    var _ref;
+    const found = (records != null ? records : []).map((entry)=>String(entry != null ? entry : '').trim()).find((entry)=>/^v\s*=\s*DMARC1\b/i.test(entry));
+    if (!found) {
+        return {
+            policy: 'absent',
+            record: null,
+            consequence: 'Your domain publishes no DMARC policy. Mail we cannot authenticate ' + 'will usually still be delivered, and anyone may send mail claiming ' + 'to be from your domain.'
+        };
+    }
+    const policy = /(^|;)\s*p\s*=\s*(reject|quarantine|none)\b/i.exec(found);
+    const value = ((_ref = policy == null ? void 0 : policy[2]) != null ? _ref : 'none').toLowerCase();
+    if (value === 'reject') {
+        return {
+            policy: 'reject',
+            record: found,
+            consequence: 'Your domain publishes p=reject. Until the DKIM record below is ' + 'live, every message we send from this domain is refused outright — ' + 'not filed as spam, refused.'
+        };
+    }
+    if (value === 'quarantine') {
+        return {
+            policy: 'quarantine',
+            record: found,
+            consequence: 'Your domain publishes p=quarantine. Until the DKIM record below is ' + 'live, our mail from this domain lands in spam, which reads as low ' + 'engagement rather than as a configuration problem.'
+        };
+    }
+    return {
+        policy: 'none',
+        record: found,
+        consequence: 'Your domain publishes p=none, which monitors but enforces nothing. ' + 'Mail we cannot authenticate is still delivered.'
+    };
+}
+/**
+ * The DMARC record we suggest to a domain that has none, offered and never
+ * required.
+ *
+ * `p=none` deliberately: it starts reporting without changing the delivery of
+ * any mail the customer already sends from other systems. Recommending
+ * `p=reject` to a domain whose other senders are unknown to us would break
+ * their invoicing or their helpdesk, and we would not find out.
+ */ export function dmarcRecommendation(domain) {
+    return {
+        type: 'TXT',
+        name: `_dmarc.${normalizeSendingDomain(domain)}`,
+        value: 'v=DMARC1; p=none; rua=mailto:dmarc@' + normalizeSendingDomain(domain),
+        purpose: 'dmarc',
+        required: false,
+        note: 'Recommended, not required, and yours to set. This starts DMARC in ' + 'report-only mode so you can see who sends as your domain before you ' + 'enforce anything. Point rua at a mailbox you read.'
+    };
+}
+/**
+ * Compare the records we asked for against the records that are live.
+ *
+ * Pure, and separated from the lookups for the reason `sso-drift-logic.ts` is
+ * separated from `sso-provisioning.ts`: the decision a customer's verification
+ * rests on should be reachable from a test without standing up DNS, so the
+ * route's spec can fake the I/O and run the REAL comparison.
+ *
+ * `inconclusive` is the load-bearing arm. A resolver outage must not be read
+ * as every customer deleting their records at the same instant, so it produces
+ * neither `verified` nor `failed` and the caller leaves the stored status
+ * alone. This is the same three-state discipline the SSO drift sweep uses, for
+ * the same reason.
+ *
+ * The SPF comparison is a `startsWith` on `v=spf1` plus a search for the
+ * include, not an exact match: a zone may legitimately carry a longer policy
+ * with extra mechanisms, and demanding our exact string would fail a
+ * configuration that works. The DKIM comparison IS exact on the key, because
+ * a key that is nearly right is a key that does not sign.
+ */ export function assessSendingRecords(record, observation) {
+    const required = sendingDomainRequiredRecords(record);
+    /*
+   * A domain with no issued DKIM key can never verify, whatever else is live.
+   *
+   * Checked on the DKIM record specifically rather than on the requirement set
+   * being empty: SPF and the return path both have values before a key is
+   * issued, so a domain with no signing key at all would otherwise satisfy
+   * every requirement in the set and reach the sending state. DKIM is the
+   * record that must align for DMARC — a domain that cannot sign is exactly
+   * the domain this feature must not let send.
+   */ const hasDkim = required.some((entry)=>entry.purpose === 'dkim');
+    if (!required.length || !hasDkim) {
+        return {
+            status: 'failed',
+            missing: [
+                'dkim-key-not-issued'
+            ]
+        };
+    }
+    if (!(observation == null ? void 0 : observation.conclusive)) return {
+        status: 'inconclusive',
+        missing: []
+    };
+    const include = `include:${sendingSpfInclude()}`;
+    const missing = [];
+    for (const entry of required){
+        const key = sendingRecordKey(entry);
+        if (entry.purpose === 'spf') {
+            var _observation_spfTxt;
+            const found = ((_observation_spfTxt = observation.spfTxt) != null ? _observation_spfTxt : []).some((txt)=>/^v\s*=\s*spf1\b/i.test(String(txt != null ? txt : '').trim()) && String(txt).toLowerCase().includes(include));
+            if (!found) missing.push(key);
+        } else if (entry.purpose === 'dkim') {
+            var _observation_dkimTxt;
+            const expected = entry.value.replace(/^p=/, '');
+            const found = ((_observation_dkimTxt = observation.dkimTxt) != null ? _observation_dkimTxt : []).some((txt)=>String(txt != null ? txt : '').replace(/\s+/g, '').includes(expected.replace(/\s+/g, '')));
+            if (!found) missing.push(key);
+        } else if (entry.purpose === 'return-path') {
+            var _observation_mx;
+            const found = ((_observation_mx = observation.mx) != null ? _observation_mx : []).some((mx)=>{
+                var _ref;
+                return String((_ref = mx == null ? void 0 : mx.exchange) != null ? _ref : '').toLowerCase() === entry.value.toLowerCase();
+            });
+            if (!found) missing.push(key);
+        }
+    }
+    return missing.length ? {
+        status: 'failed',
+        missing
+    } : {
+        status: 'verified',
+        missing: []
+    };
+}
+/**
+ * What a merchant is told when bulk mail with no opt-out meets the pool.
+ *
+ * It names a DEFECT rather than a policy, because that is what it is: every
+ * marketing path in the product attaches an unsubscribe link, so a message
+ * arriving here without one has lost it somewhere a merchant cannot see. The
+ * text therefore points at support and at the workaround that is genuinely
+ * theirs to take, instead of asking them to fix something they did not break.
+ */ const POOLED_MARKETING_NO_UNSUBSCRIBE_MESSAGE = 'This marketing message has no unsubscribe link, so it was not sent on the ' + 'shared Aglyn address. That address is shared with other sites, and bulk ' + 'mail nobody can stop earns complaints that are charged against all of ' + 'them. Every campaign and automated email the product sends carries an ' + 'unsubscribe link, so this is a fault worth reporting. A sending domain of ' + 'this site’s own — added or requested at Emails → Sending — is not subject ' + 'to this check.';
+/**
+ * Choose the identity a message leaves on, or refuse.
+ *
+ * The whole rule, and the reason this function exists rather than an inline
+ * `?:` at the send site:
+ *
+ * 1. Selection, `verified` → that identity.
+ * 2. Selection of a PLATFORM-ISSUED subdomain, not verified → treated as no
+ *    selection, and resolved by arms 4-5.
+ * 3. Selection of a CUSTOMER'S OWN domain, not verified → **REFUSED**.
+ * 4. No selection, `tenant` audience, `marketing` → **REFUSED**.
+ * 5. No selection, `tenant` audience, `transactional` → the shared identity,
+ *    if this deployment has one; **REFUSED** if it does not.
+ * 6. No selection, `platform` audience → the platform identity, named as such.
+ *
+ * There is no arm that reaches ANY other address from an unverified selection
+ * a CUSTOMER made. Somebody who has told us to send as their domain has made a
+ * statement about what their recipients will see; quietly sending as somebody
+ * else instead is not a degraded version of honoring it. That is arm 3, and
+ * neither the shared identity nor the platform one is consulted inside it.
+ *
+ * Arm 2 is the same sentence read the other way. A platform subdomain is a
+ * name WE chose, provisioned and pointed the site at — the merchant asked for
+ * a domain, not for that name and not for a DNS state — so there is no
+ * statement of theirs to contradict, and everything that can leave one
+ * unverified is ours: the provider's domain allowance, a zone write, a sweep
+ * that has not run. Refusing there would make the dedicated domain a single
+ * point of failure for receipts on exactly the tiers that pay for it.
+ *
+ * Arms 4 and 5 are the site that has chosen nothing. It is not the same case
+ * as arm 3 and must not get the same answer: there is no instruction to
+ * contradict, and a site that cannot send a receipt is not a site. So
+ * transactional mail goes, on the pooled identity, which is what the console
+ * has always disclosed. What does NOT go is marketing, because the pool is
+ * only usable while nobody is spending it on a list — and arm 2 lands here
+ * too, so a campaign from a site whose subdomain is unfinished still refuses.
+ *
+ * Arm 6 is the platform's own mail and is unreachable from a tenant audience,
+ * which is what keeps a merchant's list quality off `aglyn.com`. The `tenant`
+ * checks sit ABOVE the `platformFrom` read rather than inside it, so the
+ * platform address is not preferred-but-overridable for a tenant — it is
+ * simply not an address this audience can reach.
+ *
+ * Deciding all of it here rather than at the call sites is what makes it a
+ * property: `resolveHostSendingIdentity` passes `tenant` for every host-scoped
+ * send, so no individual caller has to remember.
+ */ export function resolveSendingIdentity(input) {
+    var _ref, _ref1, _ref2;
+    const selection = (_ref = input == null ? void 0 : input.selection) != null ? _ref : null;
+    const platformFrom = String((_ref1 = input == null ? void 0 : input.platformFrom) != null ? _ref1 : '').trim() || null;
+    const audience = (input == null ? void 0 : input.audience) === 'tenant' ? 'tenant' : 'platform';
+    const sharedFrom = String((_ref2 = input == null ? void 0 : input.sharedFrom) != null ? _ref2 : '').trim().toLowerCase();
+    // Defaulted to the arm that can never be blocked. See `SendingIdentityPurpose`.
+    const purpose = (input == null ? void 0 : input.purpose) === 'marketing' ? 'marketing' : 'transactional';
+    if (selection) {
+        var _selection_missing;
+        const domain = normalizeSendingDomain(selection.domain);
+        const localPart = normalizeLocalPart(selection.localPart);
+        const missing = ((_selection_missing = selection.missing) != null ? _selection_missing : []).map(String).filter(Boolean);
+        if (selection.status === 'verified' && domain && localPart) {
+            const from = `${localPart}@${domain}`;
+            return {
+                from,
+                source: 'custom',
+                domain,
+                summary: `Sending as ${from} on your verified domain ${domain}.`,
+                refusal: null
+            };
+        }
+        /*
+     * AN UNFINISHED PLATFORM SUBDOMAIN IS NOT A SELECTION, AND FALLS THROUGH.
+     *
+     * The dedicated subdomain is an OPTIMIZATION and the pool is the
+     * GUARANTEE, which is the property that lets the dedicated tier be
+     * rationed at all. Everything that can stop one arriving is ours: the
+     * provider's account-wide domain allowance, a zone write that failed, a
+     * provisioning sweep that has not run yet, DNS that has not propagated.
+     * None of it is anything the merchant can act on, and all of it would
+     * otherwise refuse their receipts — leaving a PAYING workspace unable to
+     * send while a free one, which is never issued a subdomain and therefore
+     * never has a selection, sends on the pool perfectly well.
+     *
+     * So this drops to the unselected arm below, which is the same code path a
+     * site with no domain of its own takes. That arm still refuses MARKETING,
+     * and it must: the reason a campaign may not leave on the pool — one
+     * merchant's complaint rate charged against every other site's password
+     * resets — is unrelated to why this site has no domain yet.
+     *
+     * A CUSTOMER'S OWN domain is the opposite case and is deliberately not
+     * included. Arm 2 below still refuses it outright, because there the
+     * merchant published DNS and told us what their recipients would see.
+     */ if (selection.platformIssued && audience === 'tenant') {
+            return resolveSendingIdentity({
+                selection: null,
+                platformFrom,
+                sharedFrom,
+                purpose,
+                audience
+            });
+        }
+        // A selected domain that is verified but has no usable address is a
+        // storage fault, not a customer one, and it is still not a reason to send
+        // as somebody else.
+        const code = selection.status === 'failed' ? 'domain-failed' : 'domain-unverified';
+        return {
+            from: null,
+            source: null,
+            domain: domain || null,
+            summary: `Blocked: ${domain || 'the selected domain'} is not verified.`,
+            refusal: {
+                code,
+                domain: domain || null,
+                missing,
+                message: code === 'domain-failed' ? `We checked the DNS for ${domain} and the required records are ` + `not published yet, so this send was refused rather than sent ` + `from a different address. Publish the records shown on the ` + `sending domain card, then verify.` : `${domain || 'The selected sending domain'} has not been ` + `verified yet, so this send was refused rather than sent from a ` + `different address. Publish the records shown on the sending ` + `domain card, then verify.`
+            }
+        };
+    }
+    /*
+   * TENANT mail with nothing selected. The PLATFORM identity is not consulted
+   * at all — not preferred-but-overridable, not a last resort. It is simply
+   * not an address this audience can reach, which is why these checks sit
+   * above the `platformFrom` read rather than inside it.
+   */ if (audience === 'tenant') {
+        /*
+     * Re-validated here rather than trusted, for the same reason `localPart` is
+     * on the selection branch: this is the one function that decides what goes
+     * into a `From:` header, and a malformed address reaching the provider is a
+     * failed send whose cause names the wrong layer.
+     */ const sharedAt = sharedFrom.lastIndexOf('@');
+        const sharedLocal = sharedAt > 0 ? normalizeLocalPart(sharedFrom.slice(0, sharedAt)) : '';
+        const sharedDomain = sharedAt > 0 ? normalizeSendingDomain(sharedFrom.slice(sharedAt + 1)) : '';
+        const shared = sharedLocal && sharedDomain ? `${sharedLocal}@${sharedDomain}` : '';
+        if (shared) {
+            return {
+                from: shared,
+                source: 'shared',
+                domain: sharedDomain,
+                summary: purpose === 'marketing' ? `Sending as ${shared} on a shared Aglyn domain. Delivery ` + 'reputation there is pooled with the other sites using it, so ' + 'campaigns are graded against the stricter complaint and ' + 'bounce limits until this site sends from a domain of its own.' : `Sending as ${shared} on a shared Aglyn domain. Delivery ` + 'reputation there is pooled with the other sites using it.',
+                refusal: null
+            };
+        }
+        return {
+            from: null,
+            source: null,
+            domain: null,
+            summary: 'Blocked: this deployment has no shared sending identity.',
+            refusal: {
+                code: 'tenant-identity-unprovisioned',
+                domain: null,
+                missing: [],
+                message: 'This site has no sending domain of its own, and this deployment ' + 'has no shared sending identity configured for it to fall back to, ' + 'so the message was refused rather than sent from the platform’s ' + 'own address. Nothing on this site can fix it and nothing about ' + 'the site is wrong — the shared identity is an operator setting. ' + 'Contact support, and note that no mail leaves this site until it ' + 'is set.'
+            }
+        };
+    }
+    if (!platformFrom) {
+        return {
+            from: null,
+            source: null,
+            domain: null,
+            summary: 'Blocked: no sending identity is configured.',
+            refusal: {
+                code: 'platform-unconfigured',
+                domain: null,
+                missing: [],
+                message: 'This deployment has no sending identity. Set USAGE_EMAIL_FROM, or ' + 'verify a custom sending domain.'
+            }
+        };
+    }
+    const platformDomain = normalizeSendingDomain(platformFrom);
+    return {
+        from: platformFrom,
+        source: 'platform',
+        domain: platformDomain || null,
+        summary: `Sending as ${platformFrom} on the shared platform domain.`,
+        refusal: null
+    };
+}
+/**
+ * The refusal on a verdict, or null.
+ *
+ * A function rather than `verdict.refusal` at each call site for the reason
+ * `rateLimitedRetryAtMs` is one: with `strictNullChecks` off, consumers cannot
+ * narrow this union reliably across the library boundary, and every call site
+ * would re-derive the same defensive read.
+ */ export function sendingIdentityRefusal(verdict) {
+    var _ref;
+    return (_ref = verdict == null ? void 0 : verdict.refusal) != null ? _ref : null;
+}
+/**
+ * The one thing the pool will not carry: MARKETING mail with no way out.
+ *
+ * ## What this is not
+ *
+ * It is not a marketing gate. A site with no domain of its own may run
+ * campaigns on the pool — that is the point of the pool, and refusing it made
+ * the whole marketing feature unreachable for every site that had not bought
+ * a domain. What bounds one site's ability to spend the pool's reputation is
+ * measurement rather than prohibition: the per-workspace reputation breaker
+ * grades seven days of complaints and bounces and stops the workspace that is
+ * earning them, the new-sender ramp keeps a first import off the pool, and the
+ * suppression, topic, cadence and frequency checks refuse the individual
+ * message. Those act on the site responsible, which a blanket refusal never
+ * did.
+ *
+ * ## Why THIS one still refuses
+ *
+ * Every one of those controls is downstream of the recipient being able to
+ * stop the mail. Bulk mail with no unsubscribe mechanism does not accumulate
+ * complaints slowly enough for a seven-day window to catch it, and on a shared
+ * member the complaints are charged to sites that did nothing. So it is
+ * refused outright, at the send, where the message is in hand.
+ *
+ * It is a DEFECT check rather than a policy: every marketing path in the
+ * product attaches a link, so this fires only when one has gone missing —
+ * an unset `EMAIL_UNSUBSCRIBE_SECRET`, a host with no public origin, or a new
+ * caller that forgot. On the pool that misconfiguration is charged to other
+ * people, which is what makes it a refusal here and a logged warning on a
+ * domain the merchant owns.
+ *
+ * Takes the verdict rather than the source string so a caller cannot pass the
+ * wrong field, and returns the same refusal shape every other arm produces so
+ * `sendEmail` has one thing to print.
+ *
+ * @param hasUnsubscribe whether the message carries an opt-out — a minted URL
+ *        or a caller-supplied `List-Unsubscribe` header. Passed in because
+ *        this module never sees the message.
+ */ export function pooledMarketingRefusal(verdict, hasUnsubscribe) {
+    var _ref;
+    if ((verdict == null ? void 0 : verdict.source) !== 'shared') return null;
+    if (hasUnsubscribe) return null;
+    return {
+        code: 'shared-identity-no-unsubscribe',
+        domain: (_ref = verdict == null ? void 0 : verdict.domain) != null ? _ref : null,
+        missing: [],
+        message: POOLED_MARKETING_NO_UNSUBSCRIBE_MESSAGE
+    };
+}
+
+//# sourceMappingURL=sending-domain.js.map