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

package/src/lib/sending-domain.d.ts

@@ -0,0 +1,744 @@
+/**
+ * @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.
+ */
+/**
+ * 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.
+ */
+export type SendingDomainStatus = 
+/**
+ * The customer asked for the domain. No records exist to publish yet,
+ * because issuing them needs a provider credential that may be absent.
+ */
+'requested'
+/** Records are issued and shown. The customer has DNS work to do. */
+ | 'records-issued'
+/** A lookup has seen every required record. This is the only sending state. */
+ | 'verified'
+/**
+ * A lookup got a conclusive answer and the records were wrong or absent.
+ * Distinct from `records-issued` so a surface can say "we looked, and it is
+ * not there" rather than leaving a customer to wonder whether we ever
+ * checked. Never reached from an unreachable resolver.
+ */
+ | 'failed';
+/** The lifecycle in order, for a surface that renders progress. */
+export declare const SENDING_DOMAIN_STATUSES: readonly SendingDomainStatus[];
+/**
+ * The stored record, one per domain per org.
+ *
+ * Per-ORG rather than per-host: DNS control is proved once for a name, and an
+ * agency running four sites on `client.com` should publish the DKIM record
+ * once, not four times. Which identity a given site *uses* is a separate,
+ * per-host choice ({@link SendingDomainSelection}) — that split is what lets
+ * one verification serve the agency case without making every site repeat the
+ * DNS chore.
+ */
+export interface SendingDomainRecord {
+    /** Normalized, lowercased, no trailing dot. Also the document id. */
+    domain: string;
+    status: SendingDomainStatus;
+    /**
+     * The DKIM selector this domain signs with. Per-org rather than a shared
+     * `resend`, so two orgs verifying the same name cannot collide on one
+     * record — and so revoking one org's identity cannot invalidate another's.
+     *
+     * Requested per-org, but ISSUED by the provider: a provider that signs on a
+     * selector of its own choosing overwrites this when the key is recorded,
+     * because the record the customer publishes has to be the record the
+     * provider will actually sign under. See `sendingDomainProvider`.
+     */
+    dkimSelector: string;
+    /** The public key the provider issued, base64, without the `p=` prefix. */
+    dkimPublicKey?: string | null;
+    /** The provider's return-path host for bounce and complaint routing. */
+    returnPathHost?: string | null;
+    /**
+     * The provider's own id for the domain object it created.
+     *
+     * Stored so a re-request can recognize a domain this deployment already
+     * created rather than creating a second one, and so an operator can find
+     * the object in the provider's dashboard. Never a credential.
+     */
+    providerDomainId?: string | null;
+    /**
+     * The host the provider redirects tracked link clicks through, as a CNAME
+     * target (`links1.resend-dns.com` and the like).
+     *
+     * From the PROVIDER, like the DKIM key and unlike the SPF include: the
+     * target names infrastructure the provider chose and can move, and a value
+     * of ours would point a customer's zone at a host we do not operate. Absent
+     * until a domain is issued with tracking on, and absent forever for one
+     * issued before it was.
+     */
+    trackingTarget?: string | null;
+    createdAtMs?: number | null;
+    verifiedAtMs?: number | null;
+    lastCheckedAtMs?: number | null;
+    /**
+     * Why the last issuing attempt did not produce a key.
+     *
+     * A REASON on a record still at `requested`, never a half-written
+     * `records-issued`. A provider that answered `4xx` has issued nothing, and
+     * a domain whose status says records exist while its DKIM value is empty
+     * would print a blank record for the customer to publish — which reads as
+     * our bug and cannot ever verify.
+     */
+    lastIssueError?: string | null;
+    lastIssueAtMs?: number | null;
+    /** What the last conclusive lookup saw, for a surface that shows the gap. */
+    lastMissing?: string[] | null;
+}
+/**
+ * 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 declare 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 declare function safeProviderDetail(input: string | null | undefined): string;
+/**
+ * Which sending identity one site uses, resolved for a send.
+ *
+ * The `localPart` is stored, never taken from a request: an address assembled
+ * from user input is a `From:` override, and the one invariant `applyFromName`
+ * was built to hold is that the address cannot move off a verified identity.
+ */
+export interface SendingDomainSelection {
+    domain: string;
+    status: SendingDomainStatus;
+    /** Mailbox to send as, for example `hello`. */
+    localPart: string;
+    /** Required records not seen by the last conclusive lookup. */
+    missing?: string[] | null;
+    /**
+     * Whether this domain is one the PLATFORM issued the site — a subdomain of
+     * our own mail apex, whose records we write into our own zone — rather than
+     * a name the customer owns and published DNS for.
+     *
+     * It decides what an UNVERIFIED selection means, which is the one place the
+     * two kinds of domain must not be treated alike. A customer's own domain is
+     * an instruction about the NAME: they published DNS for it and told us what
+     * their recipients would see, so sending as anything else contradicts them.
+     * A platform subdomain carries no such instruction even though the merchant
+     * asked for one — they asked for a domain of their own, and we picked the
+     * name, wrote the records and pointed the site at it. So a subdomain that
+     * has not finished provisioning is our unfinished work rather than their
+     * unfinished DNS. See {@link resolveSendingIdentity}.
+     *
+     * Carried on the selection rather than derived here because the apex lives
+     * in `platform-sending-domain.ts`, which imports from this module; reading
+     * it here would be a cycle. The durable half sets it with
+     * `isPlatformSendingDomain`.
+     *
+     * Absent means "a domain the customer owns", which is the direction that
+     * refuses. A caller that forgets gets the strict answer.
+     */
+    platformIssued?: boolean;
+}
+/**
+ * `{ value, error }` rather than a discriminated union, matching
+ * `validateSsoDomain`: `strictNullChecks` is off repo-wide, so an
+ * `{ ok: true } | { ok: false }` union does not narrow across a library
+ * boundary and the caller ends up unable to reach either arm's fields. Both
+ * keys always present, exactly one of them null.
+ */
+export interface SendingDomainCheck {
+    domain: string | null;
+    error: string | null;
+}
+export declare function normalizeSendingDomain(input: string): string;
+export declare function validateSendingDomain(input: string): SendingDomainCheck;
+/**
+ * The mailbox part of an address, validated so a stored `localPart` cannot
+ * smuggle a second address or a header into the `From:` line.
+ */
+export declare function normalizeLocalPart(input: string): string;
+/**
+ * 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 declare 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 declare function sendingSpfInclude(): string;
+export declare function sendingReturnPathHost(): string;
+/**
+ * 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 declare 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 declare function sendingTrackingCertAuthority(): string;
+/**
+ * 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 declare function sendingTrackingRetentionDays(): number;
+/** What a record is for, so a surface can group and explain rather than dump. */
+export type SendingRecordPurpose = 'spf' | 'dkim' | 'return-path' | 'dmarc' | 'tracking' | 'tracking-caa';
+/** One DNS record, as the customer's registrar labels it. */
+export interface SendingDnsRecord {
+    type: 'TXT' | 'MX' | 'CNAME' | 'CAA';
+    /** Fully-qualified name the record goes on. */
+    name: string;
+    value: string;
+    /** `MX` only. */
+    priority?: number;
+    purpose: SendingRecordPurpose;
+    /**
+     * Whether verification waits on it. DMARC never blocks: it is the
+     * customer's policy about their own domain and we must not make publishing
+     * one a condition of using our product.
+     */
+    required: boolean;
+    /** Why this record exists, in a sentence aimed at whoever edits the zone. */
+    note: string;
+}
+/**
+ * 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 declare function sendingDnsRecords(record: Pick<SendingDomainRecord, 'domain' | 'dkimSelector' | 'dkimPublicKey' | 'returnPathHost' | 'trackingTarget'>): SendingDnsRecord[];
+/** The subset verification waits on, and only those with a value to publish. */
+export declare function sendingDomainRequiredRecords(record: Parameters<typeof sendingDnsRecords>[0]): SendingDnsRecord[];
+/**
+ * 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 declare function sendingDomainPublishableRecords(record: Parameters<typeof sendingDnsRecords>[0]): SendingDnsRecord[];
+/**
+ * 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 declare function sendingRecordKey(entry: SendingDnsRecord): string;
+/** `TXT   send.acme.com   →   v=spf1 …`, matching `formatDnsInstruction`. */
+export declare function formatSendingRecord(entry: SendingDnsRecord): string;
+/**
+ * A customer's DMARC policy is theirs. We read it because it changes what an
+ * unverified domain does to their mail, and we must never ask them to weaken
+ * it to accommodate us.
+ */
+export type DmarcPolicy = 'reject' | 'quarantine' | 'none' | 'absent';
+export interface DmarcAssessment {
+    policy: DmarcPolicy;
+    /** The record as published, or null when there is none. */
+    record: string | null;
+    /**
+     * What this policy does to mail we cannot authenticate. Phrased as a
+     * consequence rather than as the record's contents: a customer deciding
+     * whether to finish their DNS needs the outcome, not the syntax.
+     */
+    consequence: string;
+}
+/**
+ * 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 declare function assessDmarc(records: readonly string[]): DmarcAssessment;
+/**
+ * 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 declare function dmarcRecommendation(domain: string): SendingDnsRecord;
+/** What a set of lookups saw. Assembled by the durable half, compared here. */
+export interface SendingDnsObservation {
+    /** TXT at `send.<domain>`. */
+    spfTxt: readonly string[];
+    /** TXT at `<selector>._domainkey.<domain>`. */
+    dkimTxt: readonly string[];
+    /** MX at `send.<domain>`. */
+    mx: readonly {
+        exchange: string;
+        priority: number;
+    }[];
+    /**
+     * False when ANY of the three lookups failed to get an answer.
+     *
+     * One unreachable lookup poisons the whole observation rather than being
+     * treated as an empty one: a partial read cannot distinguish a customer who
+     * published two of three records from a resolver that answered twice.
+     */
+    conclusive: boolean;
+}
+export type SendingVerificationStatus = 'verified'
+/** We got answers, and at least one required record is not there. */
+ | 'failed'
+/** Nobody answered. Not evidence in either direction. */
+ | 'inconclusive';
+export interface SendingVerification {
+    status: SendingVerificationStatus;
+    /** Keys of the required records not seen. Empty when verified. */
+    missing: string[];
+}
+/**
+ * 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 declare function assessSendingRecords(record: Parameters<typeof sendingDnsRecords>[0], observation: SendingDnsObservation): SendingVerification;
+/**
+ * WHO IS SPEAKING in this message, which is the whole of what decides whether
+ * `USAGE_EMAIL_FROM` is reachable.
+ *
+ * `platform` — Aglyn talking to its own customers. Billing, account notices,
+ * console password resets, staff alerts. These belong on `aglyn.com` and are
+ * the only mail that does.
+ *
+ * `tenant` — a site talking to its visitors. Marketing AND transactional: a
+ * receipt, a booking reminder, a membership password reset are all the tenant
+ * speaking, and all of them carry the tenant's list quality. These leave on
+ * the site's own domain or they do not leave at all.
+ *
+ * The distinction is not promotional-versus-not. A merchant who imports a
+ * purchased list and mails it produces complaints; if that merchant's receipts
+ * ride the same domain as the platform's invoices, one merchant's import
+ * degrades every other merchant's account mail. Splitting by CONTENT would put
+ * the receipts on the safe domain and leave the reputation shared anyway,
+ * because the complaints follow the domain and not the subject line.
+ */
+export type SendingIdentityAudience = 'platform' | 'tenant';
+/**
+ * WHAT KIND OF MESSAGE this is, which decides whether the shared tenant
+ * identity is reachable.
+ *
+ * `transactional` — the recipient's own action produced it, or a fact about
+ * their order or account did. A receipt, a password reset, a booking
+ * confirmation, a supplier notice. **Never blocked**, on any tier, by anything
+ * in this module: a merchant who cannot send a receipt does not have a
+ * degraded product, they have no product.
+ *
+ * `marketing` — the merchant chose to send it. A campaign, an abandoned-cart
+ * sweep, a restock alert, a flow step. It carries the merchant's list quality,
+ * so it may only leave on a domain whose reputation is that merchant's own.
+ *
+ * Orthogonal to {@link SendingIdentityAudience}, which asks WHO is speaking.
+ * Both axes are needed and neither implies the other: platform mail is all
+ * transactional today, tenant mail is both, and the answer to "may this leave
+ * on the pooled address" needs the second axis specifically.
+ *
+ * Defaults to `transactional` wherever it is unset, and the polarity is
+ * deliberate — the same one `resolveSendPriority` chose for the same reason.
+ * Enumerating what is RESTRICTED means a caller who forgets sends a receipt
+ * that goes; enumerating what is permitted means a caller who forgets drops
+ * one. The forgotten-marketing case is caught structurally instead, in
+ * `sendEmail`, which derives the answer from fields a marketing send is
+ * already required to carry rather than from one more thing to remember.
+ */
+export type SendingIdentityPurpose = 'transactional' | 'marketing';
+export interface SendingIdentityInput {
+    /**
+     * The site's chosen sending domain, or null when it has not chosen one.
+     */
+    selection?: SendingDomainSelection | null;
+    /** `USAGE_EMAIL_FROM`, the platform's own verified identity. */
+    platformFrom?: string | null;
+    /**
+     * The shared tenant identity — `sharedTenantSendingFrom()`, an address on
+     * the mail apex.
+     *
+     * Passed in rather than read from the environment here, so this module stays
+     * pure and free of a dependency on `platform-sending-domain.ts` (which
+     * imports from this file; reading it here would be a cycle). The durable
+     * half supplies it, which is also the layer that knows whether this
+     * deployment has one.
+     */
+    sharedFrom?: string | null;
+    /** See {@link SendingIdentityPurpose}. Defaults to `transactional`. */
+    purpose?: SendingIdentityPurpose;
+    /**
+     * Whose mail this is. Defaults to `platform`, which is what every caller
+     * that resolves a PLATFORM identity means and never has to say.
+     *
+     * A default is safe here only because the tenant side never reaches this
+     * function directly: `resolveHostSendingIdentity` is the single door for
+     * host-scoped mail and it passes `tenant` unconditionally. A tenant caller
+     * cannot forget the flag, because it is not the tenant caller that sets it.
+     */
+    audience?: SendingIdentityAudience;
+}
+export type SendingIdentitySource = 
+/** A domain this site has verified — its own name, or one inside our apex. */
+'custom'
+/**
+ * The pooled tenant identity on the mail apex. Every kind of mail from a
+ * site that has no domain of its own, campaigns included — graded more
+ * tightly, because the member is shared with other sites.
+ */
+ | 'shared'
+/** `USAGE_EMAIL_FROM`. Aglyn's own mail, never a tenant's. */
+ | 'platform';
+/**
+ * Why a send was refused. Every arm is a state a customer can be walked out
+ * of, which is the test for whether a refusal is worth having.
+ */
+export type SendingIdentityRefusalCode = 
+/** A domain is selected and its DNS is not finished. */
+'domain-unverified'
+/** A domain is selected and a lookup found its records wrong or absent. */
+ | 'domain-failed'
+/** No custom domain, and the platform identity is not configured either. */
+ | 'platform-unconfigured'
+/**
+ * TENANT mail from a site with no sending domain, on a deployment that has
+ * no shared identity configured either.
+ *
+ * An OPERATOR fault, not a customer one — the shared identity is derived
+ * from the mail apex and needs no tenant action — so it is the tenant-side
+ * twin of `platform-unconfigured` rather than something a merchant can fix.
+ * It stays a refusal and not a fallback for the same reason that one does:
+ * `aglyn.com` carries the platform's own billing and account mail, and a
+ * tenant's list quality must never be charged against it.
+ */
+ | 'tenant-identity-unprovisioned'
+/**
+ * MARKETING mail on the pooled identity, carrying no way out.
+ *
+ * The pool is shared with every other site that has no domain of its own, so
+ * a complaint earned here is charged against their mail as well. Nothing
+ * earns complaints faster than bulk mail a recipient cannot stop, which is
+ * why this is the one thing the pool will not carry.
+ *
+ * Deliberately narrow. Marketing on the pool is allowed — a merchant with no
+ * domain of their own may run campaigns — and it is bounded by the
+ * per-workspace reputation breaker, the new-sender ramp and the suppression
+ * and cadence checks. This refuses only the message that has defeated the
+ * unsubscribe mechanism those controls assume.
+ *
+ * On a domain the merchant owns the same message sends: there the complaint
+ * lands on their own name, and how they spend it is theirs to decide.
+ */
+ | 'shared-identity-no-unsubscribe';
+export interface SendingIdentityRefusal {
+    code: SendingIdentityRefusalCode;
+    /** The domain at fault, or null for `platform-unconfigured`. */
+    domain: string | null;
+    /** One sentence naming the cause and the next action. */
+    message: string;
+    /** Record keys the last conclusive lookup did not see. */
+    missing: string[];
+}
+export interface SendingIdentityVerdict {
+    /** Null whenever `refusal` is set. */
+    from: string | null;
+    /** Null whenever `refusal` is set. */
+    source: SendingIdentitySource | null;
+    domain: string | null;
+    /**
+     * What a surface prints, in every outcome including refusal. Requirement:
+     * the surface must always be able to say which identity is in use, so this
+     * is never empty and never needs the caller to compose it.
+     */
+    summary: string;
+    /** Null on success. Both keys always present — `strictNullChecks` is off. */
+    refusal: SendingIdentityRefusal | null;
+}
+/**
+ * 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 declare function resolveSendingIdentity(input: SendingIdentityInput): SendingIdentityVerdict;
+/**
+ * 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 declare function sendingIdentityRefusal(verdict: SendingIdentityVerdict | null | undefined): SendingIdentityRefusal | 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 declare function pooledMarketingRefusal(verdict: SendingIdentityVerdict | null | undefined, hasUnsubscribe: boolean): SendingIdentityRefusal | null;