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

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

@@ -0,0 +1,362 @@
+/**
+ * @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.
+ */
+/**
+ * The apex assigned site subdomains hang off — the WEB namespace.
+ *
+ * The same variable and the same default as `TENANT_APEX` in `@aglyn/aglyn`'s
+ * `host-naming.ts`, read again here rather than imported because
+ * `@aglyn/shared-util-email` is `scope:shared` and may not depend on the
+ * application library. Reading the environment in this module is the idiom
+ * `sendingSpfInclude` and `sendingReturnPathHost` already establish one file
+ * over: the mail policy layer owns its own configuration reads.
+ *
+ * `||` not `??`, matching every other env read in this repo — an empty string
+ * is a variable somebody set to nothing, not a configured value.
+ */
+export declare function tenantWebApex(): string;
+/**
+ * The apex tenant sending domains hang off — the MAIL namespace.
+ *
+ * `mail.{web apex}` by default, so an operator who sets only
+ * `NEXT_PUBLIC_TENANT_DOMAIN` gets a mail namespace inside their own zone
+ * rather than inside ours. Overridable on its own for the operator who wants
+ * mail in a different zone entirely — a separate registrable domain is the
+ * strongest form of the reputation split this feature is about, and there is
+ * no reason for the software to be the thing preventing it.
+ *
+ * Never equal to the web apex. If an operator sets them to the same value the
+ * override is ignored: a mail namespace that IS the web namespace re-creates
+ * exactly the collision this module chose its shape to avoid, and honoring
+ * that setting would be honoring a request to be unsafe.
+ */
+export declare function platformSendingApex(): string;
+/**
+ * The mailbox the shared tenant identity sends as.
+ *
+ * `notifications` rather than `hello`, which is what a site's own domain
+ * defaults to. The two are different promises: `hello@northwind.mail.aglyn.app`
+ * is a site inviting a reply, and this one is a platform address carrying mail
+ * for whichever site the display name in front of it names. Calling it `hello`
+ * would invite replies to a mailbox belonging to no site.
+ */
+export declare const SHARED_TENANT_LOCAL_PART = "notifications";
+/**
+ * How many shared sending domains exist, absent configuration.
+ *
+ * FOUR, and the number is a blast-radius decision rather than a capacity one.
+ * The pool is FIXED-SIZE — it does not grow with hosts — so its whole cost is
+ * four provider domain objects and twelve records in our own zone, whether the
+ * deployment has twelve sites or a hundred thousand. That is the property that
+ * makes this design survive a scale a per-host domain does not.
+ *
+ * One would be simpler and is wrong: every site without a domain of its own
+ * would share a single reputation, so one compromised site blasting "receipts"
+ * takes every other site's password resets down with it. Four caps that at a
+ * quarter, for three more domain objects.
+ *
+ * Not larger, because each member is a reputation that has to be EARNED — one
+ * warm domain sending steadily is worth more than eight cold ones — and
+ * because each is a provider slot on an account whose allowance is ten on the
+ * plan this deployment pays for. Raising it is a real decision with a real
+ * cost, so it is a configuration value rather than a constant somebody bumps.
+ */
+export declare const DEFAULT_SHARED_POOL_SIZE = 4;
+/** How many members this deployment's pool has. */
+export declare function sharedPoolSize(): number;
+/**
+ * Whether a label names a pool member.
+ *
+ * By PATTERN rather than by list, so raising the pool size can never hand a
+ * tenant a label the pool is about to want. `PLATFORM_MAIL_RESERVED_LABELS`
+ * covers the fixed names; this covers a family whose size is configurable, and
+ * a blocklist that had to be edited in step with an environment variable is a
+ * blocklist that will be forgotten.
+ */
+export declare function isSharedPoolLabel(label: string): boolean;
+/**
+ * The pool, in order: `shared1.mail.aglyn.app`, `shared2.…`, and so on.
+ *
+ * The names say what they are on purpose. A recipient who looks sees an address
+ * that is plainly platform infrastructure rather than one pretending to be the
+ * merchant's own — which is what the console tells the merchant is happening,
+ * and a `From:` that oversold the arrangement would be the one surface
+ * contradicting the disclosure.
+ */
+export declare function sharedSendingPool(apex?: string, size?: number): string[];
+/**
+ * Which pool member one host sends on. Deterministic, and stored nowhere.
+ *
+ * ## Rendezvous hashing, and why not `hash % size`
+ *
+ * The requirement is that a host's sending identity does not move underneath
+ * it. Reputation is built by sending steadily from one name, so a reassignment
+ * is not a rebalance — it is a reset, and it throws away every day of standing
+ * the old name had earned.
+ *
+ * `hash(hostId) % size` satisfies that only while `size` never changes. Growing
+ * a pool from four to eight remaps roughly HALF of all hosts, silently moving
+ * half the platform's transactional mail onto cold domains. The operator's
+ * reason for growing the pool is usually that one member is in trouble, which
+ * makes the moment they act the worst possible moment to shuffle everybody.
+ *
+ * Rendezvous (highest-random-weight) hashing scores the host against EVERY
+ * member and takes the winner. Adding a member moves only the hosts that now
+ * score highest on the new one — about 1/size of them — and removing a member
+ * moves only that member's own hosts. Nothing else observes the change.
+ *
+ * That property is why this is worth ten lines instead of a modulo, and it is
+ * also why the assignment needs no stored field: there is nothing to pin,
+ * because the function does not change its mind. A pinned column would be one
+ * more write per host on a path whose whole point is costing nothing per host.
+ *
+ * Ties break on the domain name so the answer is total rather than dependent on
+ * iteration order. A 32-bit collision across a four-member pool is vanishingly
+ * unlikely and would still have to resolve to something.
+ */
+export declare function sharedSendingDomainFor(hostId: string | null | undefined, apex?: string, size?: number): string;
+/**
+ * The address one host sends TRANSACTIONAL mail on when it has no domain of
+ * its own.
+ *
+ * `''` when the deployment has no usable pool, or when the caller has no host.
+ * The caller must treat that as a REFUSAL rather than substituting anything: a
+ * caller with no `hostId` does not know which site it is sending for, and the
+ * honest answer to that is not "some pool member".
+ *
+ * ## The address always sits ON a pool member, never under one
+ *
+ * Under `adkim=s` the `From:` domain and the DKIM `d=` must be the same name,
+ * exactly. Each pool member is its own provider domain object with its own key
+ * signing for itself, so an address on the member aligns. An address BENEATH a
+ * member — a per-host `From:` over a shared key — does not, and the published
+ * record's `aspf=r` would let it scrape a DMARC pass off SPF alone until the
+ * first recipient forwarded it. There is deliberately no configuration that can
+ * produce that shape: the local part is the only part an operator may set.
+ */
+export declare function sharedTenantSendingFrom(hostId: string | null | undefined, apex?: string, size?: number): string;
+/**
+ * Whether a domain is one of this deployment's pool members.
+ *
+ * Used where a surface has a domain and needs to know whether its reputation is
+ * pooled — so the disclosure is driven by the same function the send path
+ * resolves through, rather than by a second opinion assembled at the surface.
+ */
+export declare function isSharedSendingDomain(domain: string | null | undefined, apex?: string, size?: number): boolean;
+/**
+ * ⛔ WHY A DOMAIN MAY NOT BE TORN DOWN, or `null` when it may.
+ *
+ * Every path that destroys a sending domain — the site delete, the erasure,
+ * the orphan reaper — asks this ONE function first, and it lives here because
+ * this module is the only place that knows what the pool is. A guard held
+ * anywhere else is a guard the next teardown path forgets to consult.
+ *
+ * `shared-pool` is the answer that matters, and the reason it has to be
+ * explicit rather than emergent. A pool member is owned by NO HOST: it is
+ * platform infrastructure that every site without a domain of its own sends
+ * on, and {@link sharedSendingDomainFor} assigns hosts to it by hash rather
+ * than by a stored pointer. So any reaper keyed on "nothing points at this"
+ * describes a pool member perfectly, and releasing one takes a quarter of the
+ * platform's transactional mail — receipts, password resets, booking
+ * confirmations — down with it. Silently: nothing raises an error when a
+ * domain merely stops being verified, the sends just start refusing.
+ *
+ * It is asked of the LABEL as well as of the domain, in three ways, because
+ * pool membership answered from the CURRENT pool alone is not enough:
+ *
+ *   - the domain is in the pool this deployment builds today;
+ *   - the caller's own label is a pool label. {@link platformSendingLabel}
+ *     refuses to derive a label for a reserved name, so a pool member's domain
+ *     hands back an empty label, and a caller that then fell back to a label
+ *     it was handed separately would walk straight past the derivation that
+ *     was protecting it;
+ *   - the label UNDER the apex is a pool label, whatever the pool size says.
+ *     A deployment shrunk from eight members to four still holds `shared5`
+ *     through `shared8` at the provider, and they are still infrastructure —
+ *     a membership test against the current pool would hand all four to the
+ *     reaper on the day somebody lowered the number.
+ *
+ * `not-our-zone` is the other refusal and a different kind: a customer's own
+ * verified domain, which this deployment never provisioned, holds no provider
+ * slot for, and must never write DNS into.
+ */
+export declare function sendingDomainTeardownRefusal(domain: string | null | undefined, label?: string | null | undefined, apex?: string, size?: number): 'shared-pool' | 'not-our-zone' | null;
+/**
+ * Labels that would name mail infrastructure inside the mail apex.
+ *
+ * The question this set answers is narrow: which labels, taken by a tenant,
+ * would position that tenant to publish records under a name some other part
+ * of the system relies on?
+ *
+ * `send` is the one that matters and the one a pattern check misses.
+ * {@link SENDING_SUBDOMAIN} is `send`, so a tenant holding that label holds
+ * `send.mail.aglyn.app` — the return-path name of the mail apex itself, and a
+ * bounce-routing surface rather than anything a site needs.
+ *
+ * Names containing a dot or an underscore are NOT in here and do not need to
+ * be: {@link LABEL_PATTERN} admits neither character, so `_dmarc` and
+ * `resend._domainkey` are unreachable by construction rather than by
+ * blocklist. A blocklist entry for a string the grammar cannot produce reads
+ * as though the grammar allows it.
+ */
+export declare const PLATFORM_MAIL_RESERVED_LABELS: readonly string[];
+/**
+ * Whether a label is one a TENANT may not take inside the mail apex.
+ *
+ * Two sources, and the second is why this is a function rather than a `Set`
+ * lookup: the fixed infrastructure names above, plus the pool family, whose
+ * size is a configuration value. A pool grown from four to eight must not be
+ * able to want a label a site was handed last week, and a blocklist that had to
+ * be edited in step with an environment variable is one that gets forgotten.
+ *
+ * This is the TENANT policy, not the name grammar. The pool's own builder
+ * deliberately does not consult it — `shared3` is reserved precisely so that
+ * the pool can have it — which is why {@link mailDomainWithinApex} exists as
+ * the shape check underneath both.
+ */
+export declare function isReservedMailLabel(label: string): boolean;
+/**
+ * Whether a label is shaped like one, ignoring whether it is reserved or
+ * taken. Exported so the claim path can tell "not a label" (never fixable by
+ * suffixing) from "taken" (fixable).
+ */
+export declare function isWellFormedMailLabel(label: string): boolean;
+/**
+ * The sending domain for one PINNED label, or `''` when the label must not
+ * become one.
+ *
+ * The ONLY place a label is turned into a mail domain. Everything downstream —
+ * the Resend domain object, the DNS records written into the zone, the `From:`
+ * header — is built from what this returns, so a name this refuses cannot
+ * reach any of them.
+ *
+ * It takes the PINNED label, never a host's live subdomain, and that is the
+ * rename guarantee expressed as a type: there is no argument here that changes
+ * when a site is renamed. {@link mailLabelCandidate} is the separate, one-time
+ * step that proposes a label from a slug.
+ *
+ * `''` rather than a throw: every caller's correct response to an unusable
+ * label is the same one — provision nothing — and a falsy return is what this
+ * library's other normalizers already give back for input they will not
+ * accept.
+ */
+export declare function platformSendingDomainFor(label: string | null | undefined, apex?: string): string;
+/**
+ * Propose a mail label from a site's subdomain. Called ONCE, at provisioning.
+ *
+ * Its output is pinned and then never recomputed, so this function's result
+ * changing later — because the site was renamed, or because a label joined the
+ * reserved set — cannot move an existing site's mail. That is deliberate: the
+ * value of a sending domain is its age, and a name that can be recomputed is a
+ * name that can be lost.
+ *
+ * `attempt` de-collides. A label already claimed by another site yields
+ * `{label}-2`, `-3`, and so on, which is the same shape `suggestSubdomains`
+ * uses for a taken web slug — a merchant meeting `northwind-coffee-2` has met
+ * that pattern before. Truncated so the suffix never pushes the label past a
+ * legal length, because a name that is silently cut at 63 octets is a name
+ * whose DNS records do not match its domain.
+ *
+ * Returns `''` when nothing usable can be built, and the caller must treat
+ * that as "this site cannot be provisioned" rather than substituting anything.
+ */
+export declare function mailLabelCandidate(subdomain: string | null | undefined, attempt?: number): string;
+/**
+ * Whether a domain is one this deployment provisions and owns, as against a
+ * customer's own name.
+ *
+ * The distinction decides who does the DNS work — a domain inside our apex is
+ * written by API and needs nothing from the tenant — and what a delete may
+ * remove. A record set inside our zone is ours to clean up; a customer's zone
+ * is one we must never write to.
+ *
+ * The bare apex is deliberately NOT one of these.
+ */
+export declare function isPlatformSendingDomain(domain: string | null | undefined, apex?: string): boolean;
+/**
+ * The pinned label a platform sending domain belongs to, or `''`.
+ *
+ * The inverse of {@link platformSendingDomainFor}, and it re-runs the same
+ * refusals rather than merely stripping the suffix. A stored domain is data
+ * like any other — it can predate a reserved-label entry or have been written
+ * by hand — and a cleanup path that trusted it would derive a label from a
+ * name the current rules would never have issued.
+ */
+export declare function platformSendingLabel(domain: string | null | undefined, apex?: string): string;
+/** One record to write into the zone, as a DNS API addresses it. */
+export interface PlatformZoneRecord {
+    type: 'TXT' | 'MX' | 'CNAME' | 'CAA';
+    /**
+     * Name RELATIVE to the ZONE — `send.acme.mail`, not
+     * `send.acme.mail.aglyn.app`.
+     *
+     * Zone APIs address records by their name within the zone, and a name
+     * carrying the zone would be created at `…aglyn.app.aglyn.app`. The
+     * fully-qualified form is what `sendingDnsRecords` produces for a customer
+     * to paste at their own registrar; this is the same record addressed the way
+     * an API to our own zone addresses it.
+     *
+     * The zone is the REGISTRABLE domain (`aglyn.app`), not the mail apex —
+     * `mail.aglyn.app` is a name inside that zone, not a zone of its own, so its
+     * label is part of every record name here.
+     */
+    name: string;
+    value: string;
+    /** `MX` only. */
+    priority?: number;
+}
+/**
+ * Turn the records a sending domain requires into records addressed within the
+ * zone.
+ *
+ * Derived from {@link sendingDnsRecords}' output rather than rebuilt, for the
+ * reason that function exists at all: the records we WRITE must be the records
+ * the verifier LOOKS FOR. Two generators is how a wizard comes to print one
+ * target while the check reads another — a check that cannot fail, then a
+ * check that cannot pass.
+ *
+ * Records with no value are dropped. A domain with no issued DKIM key yields
+ * no DKIM record, and writing an empty TXT would publish a record that says
+ * nothing while looking published.
+ */
+export declare function platformZoneRecords(records: readonly {
+    type: 'TXT' | 'MX' | 'CNAME' | 'CAA';
+    name: string;
+    value: string;
+    priority?: number;
+}[], zone?: string): PlatformZoneRecord[];
+/**
+ * Every name one sending domain owns inside the zone, for the cleanup path.
+ *
+ * Derived rather than written out at the call site, because the mail apex is a
+ * configuration value: a teardown that assembled `send.{label}.mail` by hand
+ * would delete nothing on a deployment whose mail apex is not `mail.…`, and
+ * would leave a live signing key in the zone for every site it "cleaned".
+ *
+ * The DKIM name needs the SELECTOR, which is the provider's choice and not
+ * ours — `sendingDkimSelector` proposes one and the provider overwrites it. A
+ * caller with no selector gets the other names and must treat the DKIM record
+ * as unhandled rather than guessing, since a guessed selector deletes nothing
+ * and reports success.
+ */
+export declare function platformZoneNamesFor(label: string, selector?: string | null, apex?: string, zone?: string): string[];
+/**
+ * The return-path name for one pinned label, relative to the zone.
+ *
+ * Used where a caller needs only the bounce name — the record that has to keep
+ * resolving after a rename, because bounces arrive after the send.
+ */
+export declare function platformReturnPathName(label: string, apex?: string, zone?: string): string;