@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/sending-domain-debt.js

@@ -0,0 +1,268 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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.
+ */ /**
+ * A SENDING DOMAIN OUTLIVING ITS OWNER — the debt, and who settles it.
+ *
+ * A site's dedicated sending domain is three resources at three different
+ * lifetimes: a domain object at the mail provider (one of a small, plan-capped
+ * number of account slots), three records in our own DNS zone, and our
+ * Firestore state. Destroying the site destroys none of them. Until this
+ * module existed only `/api/hosts/delete` ever released them, so every other
+ * way a site could stop existing — an org erasure, a host erasure inside one —
+ * spent a provider slot forever and left a live DKIM key in the zone for a
+ * name a future site could claim.
+ *
+ * ## Erasure must not be able to fail because a vendor is down
+ *
+ * An erasure is a legal obligation with a clock on it. A provider outage, a
+ * revoked token or an unconfigured self-host must not stop it, must not leave
+ * it half-done, and must not silently drop a slot on the floor either.
+ *
+ * So the vendor work is ATTEMPTED and the outcome is either settled or
+ * RECORDED AS A DEBT. The erasure then proceeds regardless, and a sweep
+ * collects the debt later. Nothing here throws.
+ *
+ * ## The tombstone is the label claim, which is why there is no new collection
+ *
+ * `sendingLabels/{label}` is a ROOT document created at the moment a site
+ * claims its name. Nothing destroys it implicitly: it is outside
+ * `recursiveDelete(hosts/{hostId})` and outside `recursiveDelete(orgs/{orgId})`,
+ * so it is the ONE record of a site's sending domain that survives both an
+ * erased host and an erased workspace. `orgs/{orgId}/sendingDomains/{domain}`,
+ * which is where the provider's id and the DKIM selector live, does not — an
+ * org erasure destroys it, and with it the only handle on the slot to release.
+ *
+ * That makes the claim the natural tombstone rather than a designed one, and
+ * `releaseHostSendingDomain` already says so in as many words: while the claim
+ * exists, a half-finished teardown is a thing a sweep can find and finish. All
+ * this adds is the two facts the claim did not carry — the provider's domain
+ * id and the selector — copied onto it BEFORE the record holding them goes
+ * away, plus a mark saying the owner is gone.
+ *
+ * A separate `sendingDomainDebts` collection would have needed its own rules,
+ * its own index and its own reconciliation with the claim it duplicates, and
+ * would have introduced the state this design cannot produce: a debt whose
+ * label claim was already released, naming a name a new site can take.
+ *
+ * ## What the reaper is FORBIDDEN to touch
+ *
+ * The four shared pool domains (`shared1.mail.aglyn.app` …) are owned by no
+ * host by design, so "nothing points at this" describes them exactly. They
+ * have no label claim — pool labels are reserved against tenants and
+ * `ensureHostSendingDomain` is the only writer of that collection — so a sweep
+ * over `sendingLabels` cannot reach one by construction. Every path here still
+ * asks {@link sendingDomainTeardownRefusal} before acting, because a guard
+ * that rests only on a scan's starting point is a guard the next scan loses.
+ */ import { platformSendingDomainFor, sendingDomainTeardownRefusal } from "@aglyn/shared-util-email";
+import firebaseAdmin from "./firebase-admin.js";
+import { SENDING_LABELS_COLLECTION, releaseHostSendingDomain } from "./host-sending-domain.js";
+import { SENDING_DOMAINS_COLLECTION, readSendingDomainRecord } from "./sending-domains.js";
+const firestore = ()=>firebaseAdmin.app().firestore();
+const labelRef = (label)=>firestore().collection(SENDING_LABELS_COLLECTION).doc(label);
+/** One claim document as a debt record. */ export function readSendingDomainDebt(snapshot) {
+    var _snapshot_data, _data_hostId, _data_orgId, _data_domain, _data_teardownDetail, _data_providerDomainId, _data_dkimSelector;
+    if (!(snapshot == null ? void 0 : snapshot.exists)) return null;
+    const data = (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {};
+    return {
+        // The document id IS the label — that is what makes the claim atomic — so
+        // it is authoritative over the denormalised field beside it, and it is
+        // what a paging cursor has to be built from.
+        label: String(snapshot.id || data.label || ''),
+        hostId: String((_data_hostId = data.hostId) != null ? _data_hostId : '').trim() || null,
+        orgId: String((_data_orgId = data.orgId) != null ? _data_orgId : '').trim() || null,
+        domain: String((_data_domain = data.domain) != null ? _data_domain : '').trim() || null,
+        claimedAtMs: Number(data.claimedAtMs) || null,
+        orphanedAtMs: Number(data.orphanedAtMs) || null,
+        teardownDetail: String((_data_teardownDetail = data.teardownDetail) != null ? _data_teardownDetail : '').trim() || null,
+        teardownAttempts: Number(data.teardownAttempts) || 0,
+        providerDomainId: String((_data_providerDomainId = data.providerDomainId) != null ? _data_providerDomainId : '').trim() || null,
+        dkimSelector: String((_data_dkimSelector = data.dkimSelector) != null ? _data_dkimSelector : '').trim() || null
+    };
+}
+/**
+ * Everything needed to release one PINNED label's domain, read by label.
+ *
+ * Keyed on the label and never on `hosts/{hostId}.sendingDomain`, and the
+ * difference is not cosmetic. That field is the site's CURRENT SELECTION and a
+ * site may point it at the org's own verified domain through the sending
+ * identity surface — a name this deployment did not provision, holds no
+ * provider slot for, and whose record belongs to the ORG and is shared with
+ * every other site of theirs. A teardown that read the selection would release
+ * an agency's verified domain because one of its sites was deleted.
+ *
+ * The label is the thing this deployment actually created, it is written once
+ * and never rewritten, and {@link platformSendingDomainFor} re-derives the
+ * domain from it under the current apex and the current reserved set.
+ *
+ * Works for a host that no longer exists: the claim carries the org, and the
+ * provider id and selector are copied onto the claim before an erasure
+ * destroys the record they came from.
+ */ export async function readSendingDomainTeardownByLabel(label) {
+    var _debt_hostId;
+    const name = String(label != null ? label : '').trim();
+    if (!name) return null;
+    const claim = await labelRef(name).get().catch(()=>null);
+    const debt = claim ? readSendingDomainDebt(claim) : null;
+    if (!debt) return null;
+    const domain = platformSendingDomainFor(name) || debt.domain;
+    if (!domain) return null;
+    let providerDomainId = debt.providerDomainId;
+    let dkimSelector = debt.dkimSelector;
+    let trackingTarget = null;
+    if (debt.orgId && (!providerDomainId || !dkimSelector)) {
+        var _ref, _ref1, _ref2;
+        const record = readSendingDomainRecord(await firestore().collection('orgs').doc(debt.orgId).collection(SENDING_DOMAINS_COLLECTION).doc(domain).get().catch(()=>null));
+        providerDomainId = (_ref = providerDomainId != null ? providerDomainId : record == null ? void 0 : record.providerDomainId) != null ? _ref : null;
+        dkimSelector = dkimSelector != null ? dkimSelector : String((_ref1 = record == null ? void 0 : record.dkimSelector) != null ? _ref1 : '').trim() || null;
+        trackingTarget = String((_ref2 = record == null ? void 0 : record.trackingTarget) != null ? _ref2 : '').trim() || null;
+    }
+    return {
+        hostId: (_debt_hostId = debt.hostId) != null ? _debt_hostId : '',
+        orgId: debt.orgId,
+        label: name,
+        domain,
+        providerDomainId,
+        dkimSelector,
+        trackingTarget
+    };
+}
+/**
+ * Copy the vendor handles onto the claim and mark the owner gone.
+ *
+ * Written with `merge` onto a document that already exists, so it adds the
+ * debt to the claim rather than replacing it — the `hostId` the claim carries
+ * is what `releaseHostSendingDomain` matches on before deleting it, and losing
+ * that would strand the claim permanently.
+ *
+ * `teardownAttempts` increments so a debt that cannot be settled — a provider
+ * that has forgotten the domain, a token that was never restored — is visible
+ * as a number climbing rather than as a row that looks the same every day.
+ */ export async function recordSendingDomainDebt(teardown, detail) {
+    var _ref;
+    const label = String((_ref = teardown == null ? void 0 : teardown.label) != null ? _ref : '').trim();
+    if (!label) return;
+    const ref = labelRef(label);
+    await firestore().runTransaction(async (transaction)=>{
+        var _teardown_providerDomainId, _teardown_dkimSelector, _teardown_domain;
+        const snapshot = await transaction.get(ref);
+        if (!snapshot.exists) return;
+        const attempts = Number(snapshot.get('teardownAttempts')) || 0;
+        transaction.set(ref, {
+            orphanedAtMs: Number(snapshot.get('orphanedAtMs')) || Date.now(),
+            teardownDetail: String(detail != null ? detail : 'unknown'),
+            teardownAttempts: attempts + 1,
+            providerDomainId: (_teardown_providerDomainId = teardown.providerDomainId) != null ? _teardown_providerDomainId : null,
+            dkimSelector: (_teardown_dkimSelector = teardown.dkimSelector) != null ? _teardown_dkimSelector : null,
+            domain: (_teardown_domain = teardown.domain) != null ? _teardown_domain : null
+        }, {
+            merge: true
+        });
+    }).catch(()=>undefined);
+}
+/**
+ * Release one site's dedicated sending domain, or record what is still owed.
+ *
+ * The single entry point for every path that destroys a site. It never throws
+ * and it never blocks its caller on a vendor: the worst outcome is a debt on
+ * the label claim and a loud line naming the domain.
+ *
+ * Ordered provider → zone → our records by the driver it calls, for the reason
+ * stated there: the provider slot is the scarce resource, and our own record
+ * is what keeps a half-finished teardown findable.
+ */ export async function disposeHostSendingDomain(options) {
+    var _ref;
+    const teardown = (_ref = options == null ? void 0 : options.teardown) != null ? _ref : await readPinnedTeardown(options == null ? void 0 : options.hostId);
+    if (!teardown || !teardown.label || !teardown.domain) return 'none';
+    /*==========================================
+   * ⛔ THE POOL IS NEVER TORN DOWN.
+   *
+   * A pool member has no label claim, so nothing should ever reach here
+   * naming one — which is exactly why the check is here rather than trusted
+   * to the caller's starting point. `shared1.mail.aglyn.app` through
+   * `shared4` carry the transactional mail of every site with no domain of
+   * its own; releasing one stops a quarter of the platform's receipts and
+   * password resets, and stops them silently.
+   *=========================================*/ const refusal = sendingDomainTeardownRefusal(teardown.domain, teardown.label);
+    if (refusal === 'shared-pool') {
+        console.error('[sending-domain-debt] REFUSED to tear down the shared pool member', teardown.domain, '— a pool member belongs to the platform, not to a site, and nothing', 'may release it. Something is pointing a host at a reserved label.');
+        return 'protected';
+    }
+    if (refusal === 'not-our-zone') return 'none';
+    if (!(options == null ? void 0 : options.tearDown)) {
+        // No credential in this process. The debt is the honest state: the
+        // domain still exists at both vendors and something else must settle it.
+        await recordSendingDomainDebt(teardown, 'no-teardown-driver');
+        return 'deferred';
+    }
+    const result = await options.tearDown(teardown).catch(()=>({
+            outcome: 'failed',
+            detail: 'threw'
+        }));
+    /*
+   * `skipped` with nothing ever created at the provider is a real release.
+   *
+   * The driver skips when no credential is configured — a self-host with no
+   * mail provider, or a token that has been withdrawn. When the record never
+   * carried a provider id there is nothing at either vendor to leak: the id
+   * and the DKIM key are stored by the same write, and the zone records are
+   * only written once a key exists. Deferring that forever would hold a name
+   * out of circulation for a domain that was never created.
+   */ const nothingProvisioned = result.outcome === 'skipped' && !teardown.providerDomainId;
+    if (result.outcome === 'removed' || nothingProvisioned) {
+        await releaseHostSendingDomain(teardown);
+        return 'released';
+    }
+    await recordSendingDomainDebt(teardown, result.detail || result.outcome);
+    console.error('[sending-domain-debt] sending domain not released for', teardown.domain, `(${result.detail || result.outcome}) — the provider slot and the zone`, 'records are still held; the reap-sending-domains sweep will retry.');
+    return 'deferred';
+}
+/** The teardown for a host that still exists, taken from its pinned label. */ async function readPinnedTeardown(hostId) {
+    var _host_get;
+    const id = String(hostId != null ? hostId : '').trim();
+    if (!id) return null;
+    const host = await firestore().collection('hosts').doc(id).get().catch(()=>null);
+    if (!(host == null ? void 0 : host.exists)) return null;
+    const teardown = await readSendingDomainTeardownByLabel(String((_host_get = host.get('sendingLabel')) != null ? _host_get : '').trim());
+    // The claim may name a host that has since been re-pointed; the site being
+    // destroyed is the one the caller named.
+    return teardown ? _extends({}, teardown, {
+        hostId: id
+    }) : null;
+}
+/**
+ * Every label claim, oldest first, for the orphan sweep.
+ *
+ * Ordered by document id rather than by a field, and paged with a cursor. A
+ * `limit()` with no ordering returns an arbitrary but STABLE sample — the same
+ * handful every run — and ordering on `claimedAtMs` would silently DROP any
+ * claim written before that field existed, which for a reaper means an orphan
+ * it can never see. `__name__` is present on every document by definition.
+ */ export async function listSendingLabelClaims(options) {
+    var _ref, _ref1;
+    const base = firestore().collection(SENDING_LABELS_COLLECTION).orderBy('__name__').limit(Math.max(1, (_ref = options == null ? void 0 : options.limit) != null ? _ref : 100));
+    const after = String((_ref1 = options == null ? void 0 : options.after) != null ? _ref1 : '').trim();
+    const query = after ? base.startAfter(firestore().collection(SENDING_LABELS_COLLECTION).doc(after)) : base;
+    const snapshot = await query.get();
+    const rows = [];
+    for (const doc of snapshot.docs){
+        const debt = readSendingDomainDebt(doc);
+        if (debt) rows.push(debt);
+    }
+    return rows;
+}
+
+//# sourceMappingURL=sending-domain-debt.js.map

package/src/lib/server/sending-domain-debt.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/sending-domain-debt.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A SENDING DOMAIN OUTLIVING ITS OWNER — the debt, and who settles it.\n *\n * A site's dedicated sending domain is three resources at three different\n * lifetimes: a domain object at the mail provider (one of a small, plan-capped\n * number of account slots), three records in our own DNS zone, and our\n * Firestore state. Destroying the site destroys none of them. Until this\n * module existed only `/api/hosts/delete` ever released them, so every other\n * way a site could stop existing — an org erasure, a host erasure inside one —\n * spent a provider slot forever and left a live DKIM key in the zone for a\n * name a future site could claim.\n *\n * ## Erasure must not be able to fail because a vendor is down\n *\n * An erasure is a legal obligation with a clock on it. A provider outage, a\n * revoked token or an unconfigured self-host must not stop it, must not leave\n * it half-done, and must not silently drop a slot on the floor either.\n *\n * So the vendor work is ATTEMPTED and the outcome is either settled or\n * RECORDED AS A DEBT. The erasure then proceeds regardless, and a sweep\n * collects the debt later. Nothing here throws.\n *\n * ## The tombstone is the label claim, which is why there is no new collection\n *\n * `sendingLabels/{label}` is a ROOT document created at the moment a site\n * claims its name. Nothing destroys it implicitly: it is outside\n * `recursiveDelete(hosts/{hostId})` and outside `recursiveDelete(orgs/{orgId})`,\n * so it is the ONE record of a site's sending domain that survives both an\n * erased host and an erased workspace. `orgs/{orgId}/sendingDomains/{domain}`,\n * which is where the provider's id and the DKIM selector live, does not — an\n * org erasure destroys it, and with it the only handle on the slot to release.\n *\n * That makes the claim the natural tombstone rather than a designed one, and\n * `releaseHostSendingDomain` already says so in as many words: while the claim\n * exists, a half-finished teardown is a thing a sweep can find and finish. All\n * this adds is the two facts the claim did not carry — the provider's domain\n * id and the selector — copied onto it BEFORE the record holding them goes\n * away, plus a mark saying the owner is gone.\n *\n * A separate `sendingDomainDebts` collection would have needed its own rules,\n * its own index and its own reconciliation with the claim it duplicates, and\n * would have introduced the state this design cannot produce: a debt whose\n * label claim was already released, naming a name a new site can take.\n *\n * ## What the reaper is FORBIDDEN to touch\n *\n * The four shared pool domains (`shared1.mail.aglyn.app` …) are owned by no\n * host by design, so \"nothing points at this\" describes them exactly. They\n * have no label claim — pool labels are reserved against tenants and\n * `ensureHostSendingDomain` is the only writer of that collection — so a sweep\n * over `sendingLabels` cannot reach one by construction. Every path here still\n * asks {@link sendingDomainTeardownRefusal} before acting, because a guard\n * that rests only on a scan's starting point is a guard the next scan loses.\n */\n\nimport {\n  platformSendingDomainFor,\n  sendingDomainTeardownRefusal,\n} from '@aglyn/shared-util-email'\nimport firebaseAdmin from './firebase-admin'\nimport {\n  SENDING_LABELS_COLLECTION,\n  releaseHostSendingDomain,\n  type HostSendingDomainTeardown,\n} from './host-sending-domain'\nimport { SENDING_DOMAINS_COLLECTION, readSendingDomainRecord } from './sending-domains'\n\nconst firestore = () => firebaseAdmin.app().firestore()\n\n/**\n * The console-side teardown, injected rather than imported.\n *\n * Releasing the provider's domain object needs a full-access mail credential\n * and removing the zone records needs a DNS token, and neither may be\n * reachable from the tenant runtime — which is what makes them live in\n * `apps/console` and makes this library structurally unable to import them\n * (`sending-domain-credential-isolation.spec.ts` sweeps the tree for it).\n *\n * A caller that HAS those credentials passes the driver in and the domain is\n * released inline. A caller that does not — the tenant runtime, an operator\n * script, a self-host with no provider configured — records the debt and the\n * console's reaper settles it. Both are correct; only the latency differs.\n */\nexport type TeardownSendingDomainDriver = (\n  teardown: HostSendingDomainTeardown,\n) => Promise<{ outcome: 'removed' | 'skipped' | 'failed'; detail: string | null }>\n\n/** What became of one site's dedicated sending domain. */\nexport type SendingDomainDisposition =\n  /** The site had no dedicated domain of its own. Nothing to release. */\n  | 'none'\n  /** Provider slot freed, zone records removed, our records dropped. */\n  | 'released'\n  /** The debt is recorded on the label claim; the reaper owes it a visit. */\n  | 'deferred'\n  /** A shared pool member. Never torn down, by anything, ever. */\n  | 'protected'\n\nexport interface SendingDomainDebtRecord {\n  /** The claimed label, and the id of the claim document. */\n  label: string\n  hostId: string | null\n  orgId: string | null\n  domain: string | null\n  claimedAtMs: number | null\n  /** Set when a teardown could not be completed. Null on a healthy claim. */\n  orphanedAtMs: number | null\n  /** A short code naming what refused, safe to store, log and show. */\n  teardownDetail: string | null\n  /** How many passes have tried and failed to settle this. */\n  teardownAttempts: number\n  providerDomainId: string | null\n  dkimSelector: string | null\n}\n\nconst labelRef = (label: string) =>\n  firestore().collection(SENDING_LABELS_COLLECTION).doc(label)\n\n/** One claim document as a debt record. */\nexport function readSendingDomainDebt(\n  snapshot: FirebaseFirestore.DocumentSnapshot,\n): SendingDomainDebtRecord | null {\n  if (!snapshot?.exists) return null\n  const data = snapshot.data() ?? {}\n  return {\n    // The document id IS the label — that is what makes the claim atomic — so\n    // it is authoritative over the denormalised field beside it, and it is\n    // what a paging cursor has to be built from.\n    label: String(snapshot.id || data.label || ''),\n    hostId: String(data.hostId ?? '').trim() || null,\n    orgId: String(data.orgId ?? '').trim() || null,\n    domain: String(data.domain ?? '').trim() || null,\n    claimedAtMs: Number(data.claimedAtMs) || null,\n    orphanedAtMs: Number(data.orphanedAtMs) || null,\n    teardownDetail: String(data.teardownDetail ?? '').trim() || null,\n    teardownAttempts: Number(data.teardownAttempts) || 0,\n    providerDomainId: String(data.providerDomainId ?? '').trim() || null,\n    dkimSelector: String(data.dkimSelector ?? '').trim() || null,\n  }\n}\n\n/**\n * Everything needed to release one PINNED label's domain, read by label.\n *\n * Keyed on the label and never on `hosts/{hostId}.sendingDomain`, and the\n * difference is not cosmetic. That field is the site's CURRENT SELECTION and a\n * site may point it at the org's own verified domain through the sending\n * identity surface — a name this deployment did not provision, holds no\n * provider slot for, and whose record belongs to the ORG and is shared with\n * every other site of theirs. A teardown that read the selection would release\n * an agency's verified domain because one of its sites was deleted.\n *\n * The label is the thing this deployment actually created, it is written once\n * and never rewritten, and {@link platformSendingDomainFor} re-derives the\n * domain from it under the current apex and the current reserved set.\n *\n * Works for a host that no longer exists: the claim carries the org, and the\n * provider id and selector are copied onto the claim before an erasure\n * destroys the record they came from.\n */\nexport async function readSendingDomainTeardownByLabel(\n  label: string | null | undefined,\n): Promise<HostSendingDomainTeardown | null> {\n  const name = String(label ?? '').trim()\n  if (!name) return null\n\n  const claim = await labelRef(name)\n    .get()\n    .catch(() => null)\n  const debt = claim ? readSendingDomainDebt(claim) : null\n  if (!debt) return null\n\n  const domain = platformSendingDomainFor(name) || debt.domain\n  if (!domain) return null\n\n  let providerDomainId = debt.providerDomainId\n  let dkimSelector = debt.dkimSelector\n  let trackingTarget: string | null = null\n  if (debt.orgId && (!providerDomainId || !dkimSelector)) {\n    const record = readSendingDomainRecord(\n      await firestore()\n        .collection('orgs')\n        .doc(debt.orgId)\n        .collection(SENDING_DOMAINS_COLLECTION)\n        .doc(domain)\n        .get()\n        .catch(() => null as never),\n    )\n    providerDomainId = providerDomainId ?? record?.providerDomainId ?? null\n    dkimSelector = dkimSelector ?? (String(record?.dkimSelector ?? '').trim() || null)\n    trackingTarget = String(record?.trackingTarget ?? '').trim() || null\n  }\n\n  return {\n    hostId: debt.hostId ?? '',\n    orgId: debt.orgId,\n    label: name,\n    domain,\n    providerDomainId,\n    dkimSelector,\n    trackingTarget,\n  }\n}\n\n/**\n * Copy the vendor handles onto the claim and mark the owner gone.\n *\n * Written with `merge` onto a document that already exists, so it adds the\n * debt to the claim rather than replacing it — the `hostId` the claim carries\n * is what `releaseHostSendingDomain` matches on before deleting it, and losing\n * that would strand the claim permanently.\n *\n * `teardownAttempts` increments so a debt that cannot be settled — a provider\n * that has forgotten the domain, a token that was never restored — is visible\n * as a number climbing rather than as a row that looks the same every day.\n */\nexport async function recordSendingDomainDebt(\n  teardown: HostSendingDomainTeardown,\n  detail: string | null,\n): Promise<void> {\n  const label = String(teardown?.label ?? '').trim()\n  if (!label) return\n  const ref = labelRef(label)\n  await firestore()\n    .runTransaction(async (transaction) => {\n      const snapshot = await transaction.get(ref)\n      if (!snapshot.exists) return\n      const attempts = Number(snapshot.get('teardownAttempts')) || 0\n      transaction.set(\n        ref,\n        {\n          orphanedAtMs: Number(snapshot.get('orphanedAtMs')) || Date.now(),\n          teardownDetail: String(detail ?? 'unknown'),\n          teardownAttempts: attempts + 1,\n          providerDomainId: teardown.providerDomainId ?? null,\n          dkimSelector: teardown.dkimSelector ?? null,\n          domain: teardown.domain ?? null,\n        },\n        { merge: true },\n      )\n    })\n    .catch(() => undefined)\n}\n\n/**\n * Release one site's dedicated sending domain, or record what is still owed.\n *\n * The single entry point for every path that destroys a site. It never throws\n * and it never blocks its caller on a vendor: the worst outcome is a debt on\n * the label claim and a loud line naming the domain.\n *\n * Ordered provider → zone → our records by the driver it calls, for the reason\n * stated there: the provider slot is the scarce resource, and our own record\n * is what keeps a half-finished teardown findable.\n */\nexport async function disposeHostSendingDomain(options: {\n  /** The site being destroyed. Its `sendingLabel` is read before it goes. */\n  hostId?: string | null\n  /** Pre-read teardown, for a caller that has already lost the host document. */\n  teardown?: HostSendingDomainTeardown | null\n  tearDown?: TeardownSendingDomainDriver | null\n}): Promise<SendingDomainDisposition> {\n  const teardown = options?.teardown ?? (await readPinnedTeardown(options?.hostId))\n  if (!teardown || !teardown.label || !teardown.domain) return 'none'\n\n  /*==========================================\n   * ⛔ THE POOL IS NEVER TORN DOWN.\n   *\n   * A pool member has no label claim, so nothing should ever reach here\n   * naming one — which is exactly why the check is here rather than trusted\n   * to the caller's starting point. `shared1.mail.aglyn.app` through\n   * `shared4` carry the transactional mail of every site with no domain of\n   * its own; releasing one stops a quarter of the platform's receipts and\n   * password resets, and stops them silently.\n   *=========================================*/\n  const refusal = sendingDomainTeardownRefusal(teardown.domain, teardown.label)\n  if (refusal === 'shared-pool') {\n    console.error(\n      '[sending-domain-debt] REFUSED to tear down the shared pool member',\n      teardown.domain,\n      '— a pool member belongs to the platform, not to a site, and nothing',\n      'may release it. Something is pointing a host at a reserved label.',\n    )\n    return 'protected'\n  }\n  if (refusal === 'not-our-zone') return 'none'\n\n  if (!options?.tearDown) {\n    // No credential in this process. The debt is the honest state: the\n    // domain still exists at both vendors and something else must settle it.\n    await recordSendingDomainDebt(teardown, 'no-teardown-driver')\n    return 'deferred'\n  }\n\n  const result = await options\n    .tearDown(teardown)\n    .catch(() => ({ outcome: 'failed' as const, detail: 'threw' }))\n\n  /*\n   * `skipped` with nothing ever created at the provider is a real release.\n   *\n   * The driver skips when no credential is configured — a self-host with no\n   * mail provider, or a token that has been withdrawn. When the record never\n   * carried a provider id there is nothing at either vendor to leak: the id\n   * and the DKIM key are stored by the same write, and the zone records are\n   * only written once a key exists. Deferring that forever would hold a name\n   * out of circulation for a domain that was never created.\n   */\n  const nothingProvisioned =\n    result.outcome === 'skipped' && !teardown.providerDomainId\n  if (result.outcome === 'removed' || nothingProvisioned) {\n    await releaseHostSendingDomain(teardown)\n    return 'released'\n  }\n\n  await recordSendingDomainDebt(teardown, result.detail || result.outcome)\n  console.error(\n    '[sending-domain-debt] sending domain not released for',\n    teardown.domain,\n    `(${result.detail || result.outcome}) — the provider slot and the zone`,\n    'records are still held; the reap-sending-domains sweep will retry.',\n  )\n  return 'deferred'\n}\n\n/** The teardown for a host that still exists, taken from its pinned label. */\nasync function readPinnedTeardown(\n  hostId: string | null | undefined,\n): Promise<HostSendingDomainTeardown | null> {\n  const id = String(hostId ?? '').trim()\n  if (!id) return null\n  const host = await firestore()\n    .collection('hosts')\n    .doc(id)\n    .get()\n    .catch(() => null)\n  if (!host?.exists) return null\n  const teardown = await readSendingDomainTeardownByLabel(\n    String(host.get('sendingLabel') ?? '').trim(),\n  )\n  // The claim may name a host that has since been re-pointed; the site being\n  // destroyed is the one the caller named.\n  return teardown ? { ...teardown, hostId: id } : null\n}\n\n/**\n * Every label claim, oldest first, for the orphan sweep.\n *\n * Ordered by document id rather than by a field, and paged with a cursor. A\n * `limit()` with no ordering returns an arbitrary but STABLE sample — the same\n * handful every run — and ordering on `claimedAtMs` would silently DROP any\n * claim written before that field existed, which for a reaper means an orphan\n * it can never see. `__name__` is present on every document by definition.\n */\nexport async function listSendingLabelClaims(options: {\n  limit: number\n  after?: string | null\n}): Promise<SendingDomainDebtRecord[]> {\n  const base = firestore()\n    .collection(SENDING_LABELS_COLLECTION)\n    .orderBy('__name__')\n    .limit(Math.max(1, options?.limit ?? 100))\n  const after = String(options?.after ?? '').trim()\n  const query = after\n    ? base.startAfter(\n        firestore().collection(SENDING_LABELS_COLLECTION).doc(after),\n      )\n    : base\n  const snapshot = await query.get()\n  const rows: SendingDomainDebtRecord[] = []\n  for (const doc of snapshot.docs) {\n    const debt = readSendingDomainDebt(doc)\n    if (debt) rows.push(debt)\n  }\n  return rows\n}\n"],"names":["platformSendingDomainFor","sendingDomainTeardownRefusal","firebaseAdmin","SENDING_LABELS_COLLECTION","releaseHostSendingDomain","SENDING_DOMAINS_COLLECTION","readSendingDomainRecord","firestore","app","labelRef","label","collection","doc","readSendingDomainDebt","snapshot","data","exists","String","id","hostId","trim","orgId","domain","claimedAtMs","Number","orphanedAtMs","teardownDetail","teardownAttempts","providerDomainId","dkimSelector","readSendingDomainTeardownByLabel","debt","name","claim","get","catch","trackingTarget","record","recordSendingDomainDebt","teardown","detail","ref","runTransaction","transaction","attempts","set","Date","now","merge","undefined","disposeHostSendingDomain","options","readPinnedTeardown","refusal","console","error","tearDown","result","outcome","nothingProvisioned","host","listSendingLabelClaims","base","orderBy","limit","Math","max","after","query","startAfter","rows","docs","push"],"mappings":"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"}

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

@@ -0,0 +1,151 @@
+/**
+ * @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.
+ */
+/**
+ * RE-CHECKING A VERIFIED SENDING DOMAIN.
+ *
+ * `verifySendingDomain` runs when an admin presses Verify and never again, so
+ * a domain that proved itself once was trusted for as long as the record
+ * existed. DNS does not hold still: a customer migrates their zone, prunes an
+ * unrecognized TXT record, or lets the domain lapse, and the platform keeps
+ * signing mail as a name whose owner has withdrawn permission to.
+ *
+ * ## The failure this must not become
+ *
+ * The obvious sweep — re-run the check nightly, write what it says — is worse
+ * than no sweep. A DNS lookup cannot tell "the record is gone" from "nobody
+ * answered", so the obvious sweep un-verifies every customer at once during a
+ * resolver outage and every one of them silently stops being able to mail.
+ * That is a platform-wide, self-inflicted outage in exchange for closing a
+ * slow leak.
+ *
+ * Two independent things stop it:
+ *
+ * 1. **The probe's third outcome.** `assessSendingRecords` answers
+ *    `inconclusive` unless all three lookups ANSWERED, and `dns-probe.ts` asks
+ *    public resolvers before the runtime's own precisely so a stale local
+ *    resolver cannot manufacture a conclusive miss. An inconclusive pass here
+ *    writes nothing but the check time.
+ * 2. **The drift discipline.** Even a conclusive miss is counted rather than
+ *    acted on, through the same {@link assessDomainDrift} the SSO domain sweep
+ *    uses. An unattended sweep is not an admin watching a button: nobody sees
+ *    its verdict, so it needs more evidence than one answer before it costs a
+ *    customer their sending.
+ *
+ * ## Where this diverges from the SSO sweep, and why
+ *
+ * `assessDomainDrift` has no `revoke` — its strongest verdict is `report`,
+ * because revoking an SSO domain locks people out of their own account and
+ * that is a human's call. Here the same verdict DOES change the status, and
+ * the asymmetry is in what the change costs: an un-verified sending domain
+ * makes the site's sends REFUSE, and a refusal is recoverable by publishing
+ * the record and pressing Verify. It never quietly moves the tenant's mail
+ * back onto the shared platform domain, which is the outcome the whole feature
+ * exists to prevent and which no amount of drift would justify.
+ *
+ * ## What it does not do
+ *
+ * It re-checks `verified` domains only. Walking `records-issued` domains to
+ * see whether a customer has published yet is a different job with a different
+ * cadence and a different failure mode (an onboarding poller, not a trust
+ * expiry), and folding the two together would mean one interval serving
+ * neither.
+ */
+import { type DomainProbeStatus } from './sso-drift-logic';
+/**
+ * How stale a verified domain's last check must be before it is re-read.
+ *
+ * Daily. The thing being detected — a customer editing their zone — happens on
+ * a human timescale, and a tighter cadence buys hours of detection for a
+ * multiple of the DNS traffic and the write volume. It also sets the floor on
+ * how long a genuinely removed record keeps sending: three conclusive misses
+ * at a day apart, which the age floor below holds to at least three days.
+ */
+export declare const SENDING_DOMAIN_RECHECK_AFTER_MS: number;
+/**
+ * Conclusive failures in a row before a verified domain is un-verified.
+ *
+ * Three. The evidence for each one is already strong — all three lookups
+ * answered, across pinned public resolvers — so this is not compensating for a
+ * weak probe. It is compensating for the one failure the probe cannot see: the
+ * resolvers agreeing on a wrong answer, which `dns-probe.ts` documents having
+ * happened once already with a stale zone.
+ */
+export declare const SENDING_DOMAIN_FAILURES_BEFORE_REVOKE = 3;
+/**
+ * And the wall-clock floor the same run must clear, independent of the count.
+ *
+ * Both, for the reason the SSO threshold gives: a count alone can be run up in
+ * minutes by a beat firing more often than anyone intended, or by somebody
+ * re-running the sweep by hand, and "we checked three times" then reads as
+ * diligence while meaning nothing.
+ *
+ * Three days is what three daily checks ought to take. It is not a long time
+ * to keep signing for a domain whose records are gone: once the DKIM record is
+ * removed our signature stops validating anyway, so the mail is already
+ * failing — un-verifying is how the product stops PRETENDING otherwise, not
+ * what stops the bad mail.
+ */
+export declare const SENDING_DOMAIN_DRIFT_MIN_AGE_MS: number;
+/** Domains one beat will re-check. The rest are picked up on the next one. */
+export declare const SENDING_DOMAIN_RECHECK_BATCH = 25;
+/** What one pass settled. */
+export interface SendingDomainRecheckSummary {
+    /** Domains probed. */
+    checked: number;
+    /** Probes that established nothing, and changed nothing. */
+    held: number;
+    /** Domains still publishing their records; any failure run ended. */
+    cleared: number;
+    /** Conclusive misses recorded, without acting on them yet. */
+    counted: number;
+    /** Domains moved out of `verified`. */
+    revoked: number;
+}
+/**
+ * A probe verdict as the drift assessor's vocabulary.
+ *
+ * The mapping is the whole safety property of this module written in three
+ * lines, which is why it is a named function rather than a ternary inside the
+ * loop: `inconclusive` becomes `unreachable`, which `assessDomainDrift` holds
+ * on — it neither counts the failure nor clears a run already gathered. An
+ * outage must not manufacture evidence, and must not launder away evidence
+ * either.
+ */
+export declare function driftProbeStatus(verdict: 'verified' | 'failed' | 'inconclusive'): DomainProbeStatus;
+export interface SendingDomainRecheckOptions {
+    nowMs?: number;
+    /** Injectable for tests; defaults to the Admin SDK's Firestore. */
+    firestore?: any;
+    batch?: number;
+    recheckAfterMs?: number;
+    failuresBeforeRevoke?: number;
+    minAgeMs?: number;
+}
+/**
+ * Re-check the verified sending domains whose last check has gone stale.
+ *
+ * Bounded and idempotent, as every handler on the job beat must be: each pass
+ * stamps `lastCheckedAtMs`, which moves the domain to the back of the queue,
+ * so the sweep resumes without carrying a cursor and an overlapping beat
+ * re-checks at worst a domain that was just checked.
+ *
+ * Never throws for one bad zone. A single unresolvable domain must not stop
+ * the platform's other customers from being checked, and the runner's error
+ * isolation is a coarser tool than that — it would lose the rest of the batch.
+ */
+export declare function recheckSendingDomains(options?: SendingDomainRecheckOptions): Promise<SendingDomainRecheckSummary>;
+export default recheckSendingDomains;