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

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

@@ -0,0 +1,253 @@
+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.
+ */ /**
+ * 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 { assessDomainDrift } from "./sso-drift-logic.js";
+import firebaseAdmin from "./firebase-admin.js";
+import { probeSendingRecords, readSendingDomainRecord, SENDING_DOMAINS_COLLECTION } from "./sending-domains.js";
+/**
+ * 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 const SENDING_DOMAIN_RECHECK_AFTER_MS = 24 * 60 * 60000;
+/**
+ * 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 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 const SENDING_DOMAIN_DRIFT_MIN_AGE_MS = 3 * 24 * 60 * 60000;
+/** Domains one beat will re-check. The rest are picked up on the next one. */ export const SENDING_DOMAIN_RECHECK_BATCH = 25;
+const EMPTY = {
+    checked: 0,
+    held: 0,
+    cleared: 0,
+    counted: 0,
+    revoked: 0
+};
+/**
+ * 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 function driftProbeStatus(verdict) {
+    if (verdict === 'inconclusive') return 'unreachable';
+    return verdict === 'verified' ? 'proven' : 'missing';
+}
+/**
+ * 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 async function recheckSendingDomains(options = {}) {
+    var _options_nowMs, _options_firestore, _options_recheckAfterMs;
+    const nowMs = (_options_nowMs = options.nowMs) != null ? _options_nowMs : Date.now();
+    const store = (_options_firestore = options.firestore) != null ? _options_firestore : firebaseAdmin.app().firestore();
+    const cutoff = nowMs - ((_options_recheckAfterMs = options.recheckAfterMs) != null ? _options_recheckAfterMs : SENDING_DOMAIN_RECHECK_AFTER_MS);
+    /*
+   * The staleness bound is IN the query, not applied after it. A beat with
+   * nothing due then bills one empty read instead of reading a batch of
+   * freshly-checked documents to discard them — the standing rule about reads
+   * that nobody asked for, on a path that fires unattended forever.
+   *
+   * Ordered by the same field the inequality is on, so the least recently
+   * checked come first and no domain can be starved by a busier neighbour.
+   * Needs the (status, lastCheckedAtMs) collection-group index; without it
+   * this throws and the runner isolates the failure.
+   *
+   * The order also decides which documents are VISIBLE: Firestore drops a
+   * document that has no `lastCheckedAtMs` at all. Nothing writes
+   * `status: 'verified'` except `verifySendingDomain`, which stamps
+   * `lastCheckedAtMs` in the same `set`, so no verified document can lack it —
+   * an invariant `sending-domain-recheck.spec.ts` pins, because a future
+   * second writer of that status would silently make its domains invisible
+   * here rather than failing.
+   */ let due;
+    try {
+        var _options_batch, _ref;
+        const snapshot = await store.collectionGroup(SENDING_DOMAINS_COLLECTION).where('status', '==', 'verified').where('lastCheckedAtMs', '<', cutoff).orderBy('lastCheckedAtMs', 'asc').limit((_options_batch = options.batch) != null ? _options_batch : SENDING_DOMAIN_RECHECK_BATCH).get();
+        due = (_ref = snapshot == null ? void 0 : snapshot.docs) != null ? _ref : [];
+    } catch (error) {
+        // A missing index reads exactly like this. Reported and returned empty
+        // rather than thrown: the runner's isolation would be the same outcome
+        // with a less specific log line.
+        console.error('[sending-domains] re-check query failed', error);
+        return _extends({}, EMPTY);
+    }
+    const summary = _extends({}, EMPTY);
+    for (const doc of due){
+        try {
+            summary.checked += 1;
+            await recheckOneDomain(doc, nowMs, options, summary);
+        } catch (error) {
+            var _ref1;
+            // Counted as checked and not as anything else: the domain keeps its
+            // status and its failure run, and the next beat tries again.
+            console.error(`[sending-domains] re-check failed for ${(_ref1 = doc == null ? void 0 : doc.id) != null ? _ref1 : 'unknown'}`, error);
+        }
+    }
+    return summary;
+}
+async function recheckOneDomain(doc, nowMs, options, summary) {
+    var _ref, _options_failuresBeforeRevoke, _options_minAgeMs;
+    const record = readSendingDomainRecord(doc);
+    if (!record) return;
+    const verdict = await probeSendingRecords(record);
+    const data = (_ref = doc.data == null ? void 0 : doc.data.call(doc)) != null ? _ref : {};
+    const drift = assessDomainDrift({
+        status: driftProbeStatus(verdict.status),
+        records: []
+    }, {
+        consecutiveFailures: Number(data.recheckFailures) || 0,
+        firstFailureAtMs: Number(data.recheckFirstFailureAtMs) || null
+    }, nowMs, (_options_failuresBeforeRevoke = options.failuresBeforeRevoke) != null ? _options_failuresBeforeRevoke : SENDING_DOMAIN_FAILURES_BEFORE_REVOKE, (_options_minAgeMs = options.minAgeMs) != null ? _options_minAgeMs : SENDING_DOMAIN_DRIFT_MIN_AGE_MS);
+    const del = firebaseAdmin.firestore.FieldValue.delete();
+    if (drift.action === 'hold') {
+        // The check happened, so the timestamp moves; nothing else does. Moving it
+        // is what keeps an unreachable domain from monopolizing every batch while
+        // a resolver is down, and it costs at most one delayed re-check.
+        summary.held += 1;
+        await doc.ref.set({
+            lastCheckedAtMs: nowMs
+        }, {
+            merge: true
+        });
+        return;
+    }
+    if (drift.action === 'clear') {
+        summary.cleared += 1;
+        await doc.ref.set({
+            lastCheckedAtMs: nowMs,
+            // A run that ended leaves no trace. Keeping a stale count would make
+            // the NEXT unrelated failure the third one.
+            recheckFailures: del,
+            recheckFirstFailureAtMs: del,
+            lastMissing: del
+        }, {
+            merge: true
+        });
+        return;
+    }
+    if (drift.action === 'count') {
+        summary.counted += 1;
+        await doc.ref.set({
+            lastCheckedAtMs: nowMs,
+            recheckFailures: drift.consecutiveFailures,
+            recheckFirstFailureAtMs: drift.firstFailureAtMs,
+            // Recorded while the domain is still verified and still sending, so
+            // the console can say WHICH record went missing before the deadline
+            // rather than only after it.
+            lastMissing: verdict.missing
+        }, {
+            merge: true
+        });
+        return;
+    }
+    summary.revoked += 1;
+    await doc.ref.set({
+        status: 'failed',
+        lastCheckedAtMs: nowMs,
+        lastMissing: verdict.missing,
+        // The run is spent. A domain that is re-verified and drifts again starts
+        // its own count rather than inheriting this one.
+        recheckFailures: del,
+        recheckFirstFailureAtMs: del
+    }, {
+        merge: true
+    });
+    console.warn(`[sending-domains] un-verified ${record.domain}: ${verdict.missing.join(', ')}`);
+}
+export default recheckSendingDomains;
+
+//# sourceMappingURL=sending-domain-recheck.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/sending-domain-recheck.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 * RE-CHECKING A VERIFIED SENDING DOMAIN.\n *\n * `verifySendingDomain` runs when an admin presses Verify and never again, so\n * a domain that proved itself once was trusted for as long as the record\n * existed. DNS does not hold still: a customer migrates their zone, prunes an\n * unrecognized TXT record, or lets the domain lapse, and the platform keeps\n * signing mail as a name whose owner has withdrawn permission to.\n *\n * ## The failure this must not become\n *\n * The obvious sweep — re-run the check nightly, write what it says — is worse\n * than no sweep. A DNS lookup cannot tell \"the record is gone\" from \"nobody\n * answered\", so the obvious sweep un-verifies every customer at once during a\n * resolver outage and every one of them silently stops being able to mail.\n * That is a platform-wide, self-inflicted outage in exchange for closing a\n * slow leak.\n *\n * Two independent things stop it:\n *\n * 1. **The probe's third outcome.** `assessSendingRecords` answers\n *    `inconclusive` unless all three lookups ANSWERED, and `dns-probe.ts` asks\n *    public resolvers before the runtime's own precisely so a stale local\n *    resolver cannot manufacture a conclusive miss. An inconclusive pass here\n *    writes nothing but the check time.\n * 2. **The drift discipline.** Even a conclusive miss is counted rather than\n *    acted on, through the same {@link assessDomainDrift} the SSO domain sweep\n *    uses. An unattended sweep is not an admin watching a button: nobody sees\n *    its verdict, so it needs more evidence than one answer before it costs a\n *    customer their sending.\n *\n * ## Where this diverges from the SSO sweep, and why\n *\n * `assessDomainDrift` has no `revoke` — its strongest verdict is `report`,\n * because revoking an SSO domain locks people out of their own account and\n * that is a human's call. Here the same verdict DOES change the status, and\n * the asymmetry is in what the change costs: an un-verified sending domain\n * makes the site's sends REFUSE, and a refusal is recoverable by publishing\n * the record and pressing Verify. It never quietly moves the tenant's mail\n * back onto the shared platform domain, which is the outcome the whole feature\n * exists to prevent and which no amount of drift would justify.\n *\n * ## What it does not do\n *\n * It re-checks `verified` domains only. Walking `records-issued` domains to\n * see whether a customer has published yet is a different job with a different\n * cadence and a different failure mode (an onboarding poller, not a trust\n * expiry), and folding the two together would mean one interval serving\n * neither.\n */\n\nimport { assessDomainDrift, type DomainProbeStatus } from './sso-drift-logic'\nimport firebaseAdmin from './firebase-admin'\nimport {\n  probeSendingRecords,\n  readSendingDomainRecord,\n  SENDING_DOMAINS_COLLECTION,\n} from './sending-domains'\n\n/**\n * How stale a verified domain's last check must be before it is re-read.\n *\n * Daily. The thing being detected — a customer editing their zone — happens on\n * a human timescale, and a tighter cadence buys hours of detection for a\n * multiple of the DNS traffic and the write volume. It also sets the floor on\n * how long a genuinely removed record keeps sending: three conclusive misses\n * at a day apart, which the age floor below holds to at least three days.\n */\nexport const SENDING_DOMAIN_RECHECK_AFTER_MS = 24 * 60 * 60_000\n\n/**\n * Conclusive failures in a row before a verified domain is un-verified.\n *\n * Three. The evidence for each one is already strong — all three lookups\n * answered, across pinned public resolvers — so this is not compensating for a\n * weak probe. It is compensating for the one failure the probe cannot see: the\n * resolvers agreeing on a wrong answer, which `dns-probe.ts` documents having\n * happened once already with a stale zone.\n */\nexport const SENDING_DOMAIN_FAILURES_BEFORE_REVOKE = 3\n\n/**\n * And the wall-clock floor the same run must clear, independent of the count.\n *\n * Both, for the reason the SSO threshold gives: a count alone can be run up in\n * minutes by a beat firing more often than anyone intended, or by somebody\n * re-running the sweep by hand, and \"we checked three times\" then reads as\n * diligence while meaning nothing.\n *\n * Three days is what three daily checks ought to take. It is not a long time\n * to keep signing for a domain whose records are gone: once the DKIM record is\n * removed our signature stops validating anyway, so the mail is already\n * failing — un-verifying is how the product stops PRETENDING otherwise, not\n * what stops the bad mail.\n */\nexport const SENDING_DOMAIN_DRIFT_MIN_AGE_MS = 3 * 24 * 60 * 60_000\n\n/** Domains one beat will re-check. The rest are picked up on the next one. */\nexport const SENDING_DOMAIN_RECHECK_BATCH = 25\n\n/** What one pass settled. */\nexport interface SendingDomainRecheckSummary {\n  /** Domains probed. */\n  checked: number\n  /** Probes that established nothing, and changed nothing. */\n  held: number\n  /** Domains still publishing their records; any failure run ended. */\n  cleared: number\n  /** Conclusive misses recorded, without acting on them yet. */\n  counted: number\n  /** Domains moved out of `verified`. */\n  revoked: number\n}\n\nconst EMPTY: SendingDomainRecheckSummary = {\n  checked: 0,\n  held: 0,\n  cleared: 0,\n  counted: 0,\n  revoked: 0,\n}\n\n/**\n * A probe verdict as the drift assessor's vocabulary.\n *\n * The mapping is the whole safety property of this module written in three\n * lines, which is why it is a named function rather than a ternary inside the\n * loop: `inconclusive` becomes `unreachable`, which `assessDomainDrift` holds\n * on — it neither counts the failure nor clears a run already gathered. An\n * outage must not manufacture evidence, and must not launder away evidence\n * either.\n */\nexport function driftProbeStatus(\n  verdict: 'verified' | 'failed' | 'inconclusive',\n): DomainProbeStatus {\n  if (verdict === 'inconclusive') return 'unreachable'\n  return verdict === 'verified' ? 'proven' : 'missing'\n}\n\nexport interface SendingDomainRecheckOptions {\n  nowMs?: number\n  /** Injectable for tests; defaults to the Admin SDK's Firestore. */\n  firestore?: any\n  batch?: number\n  recheckAfterMs?: number\n  failuresBeforeRevoke?: number\n  minAgeMs?: number\n}\n\n/**\n * Re-check the verified sending domains whose last check has gone stale.\n *\n * Bounded and idempotent, as every handler on the job beat must be: each pass\n * stamps `lastCheckedAtMs`, which moves the domain to the back of the queue,\n * so the sweep resumes without carrying a cursor and an overlapping beat\n * re-checks at worst a domain that was just checked.\n *\n * Never throws for one bad zone. A single unresolvable domain must not stop\n * the platform's other customers from being checked, and the runner's error\n * isolation is a coarser tool than that — it would lose the rest of the batch.\n */\nexport async function recheckSendingDomains(\n  options: SendingDomainRecheckOptions = {},\n): Promise<SendingDomainRecheckSummary> {\n  const nowMs = options.nowMs ?? Date.now()\n  const store = options.firestore ?? firebaseAdmin.app().firestore()\n  const cutoff =\n    nowMs - (options.recheckAfterMs ?? SENDING_DOMAIN_RECHECK_AFTER_MS)\n\n  /*\n   * The staleness bound is IN the query, not applied after it. A beat with\n   * nothing due then bills one empty read instead of reading a batch of\n   * freshly-checked documents to discard them — the standing rule about reads\n   * that nobody asked for, on a path that fires unattended forever.\n   *\n   * Ordered by the same field the inequality is on, so the least recently\n   * checked come first and no domain can be starved by a busier neighbour.\n   * Needs the (status, lastCheckedAtMs) collection-group index; without it\n   * this throws and the runner isolates the failure.\n   *\n   * The order also decides which documents are VISIBLE: Firestore drops a\n   * document that has no `lastCheckedAtMs` at all. Nothing writes\n   * `status: 'verified'` except `verifySendingDomain`, which stamps\n   * `lastCheckedAtMs` in the same `set`, so no verified document can lack it —\n   * an invariant `sending-domain-recheck.spec.ts` pins, because a future\n   * second writer of that status would silently make its domains invisible\n   * here rather than failing.\n   */\n  let due: any[]\n  try {\n    const snapshot = await store\n      .collectionGroup(SENDING_DOMAINS_COLLECTION)\n      .where('status', '==', 'verified')\n      .where('lastCheckedAtMs', '<', cutoff)\n      .orderBy('lastCheckedAtMs', 'asc')\n      .limit(options.batch ?? SENDING_DOMAIN_RECHECK_BATCH)\n      .get()\n    due = snapshot?.docs ?? []\n  } catch (error) {\n    // A missing index reads exactly like this. Reported and returned empty\n    // rather than thrown: the runner's isolation would be the same outcome\n    // with a less specific log line.\n    console.error('[sending-domains] re-check query failed', error)\n    return { ...EMPTY }\n  }\n\n  const summary: SendingDomainRecheckSummary = { ...EMPTY }\n  for (const doc of due) {\n    try {\n      summary.checked += 1\n      await recheckOneDomain(doc, nowMs, options, summary)\n    } catch (error) {\n      // Counted as checked and not as anything else: the domain keeps its\n      // status and its failure run, and the next beat tries again.\n      console.error(\n        `[sending-domains] re-check failed for ${doc?.id ?? 'unknown'}`,\n        error,\n      )\n    }\n  }\n  return summary\n}\n\nasync function recheckOneDomain(\n  doc: any,\n  nowMs: number,\n  options: SendingDomainRecheckOptions,\n  summary: SendingDomainRecheckSummary,\n): Promise<void> {\n  const record = readSendingDomainRecord(doc)\n  if (!record) return\n\n  const verdict = await probeSendingRecords(record)\n  const data = doc.data?.() ?? {}\n  const drift = assessDomainDrift(\n    { status: driftProbeStatus(verdict.status), records: [] },\n    {\n      consecutiveFailures: Number(data.recheckFailures) || 0,\n      firstFailureAtMs: Number(data.recheckFirstFailureAtMs) || null,\n    },\n    nowMs,\n    options.failuresBeforeRevoke ?? SENDING_DOMAIN_FAILURES_BEFORE_REVOKE,\n    options.minAgeMs ?? SENDING_DOMAIN_DRIFT_MIN_AGE_MS,\n  )\n\n  const del = firebaseAdmin.firestore.FieldValue.delete()\n\n  if (drift.action === 'hold') {\n    // The check happened, so the timestamp moves; nothing else does. Moving it\n    // is what keeps an unreachable domain from monopolizing every batch while\n    // a resolver is down, and it costs at most one delayed re-check.\n    summary.held += 1\n    await doc.ref.set({ lastCheckedAtMs: nowMs }, { merge: true })\n    return\n  }\n\n  if (drift.action === 'clear') {\n    summary.cleared += 1\n    await doc.ref.set(\n      {\n        lastCheckedAtMs: nowMs,\n        // A run that ended leaves no trace. Keeping a stale count would make\n        // the NEXT unrelated failure the third one.\n        recheckFailures: del,\n        recheckFirstFailureAtMs: del,\n        lastMissing: del,\n      },\n      { merge: true },\n    )\n    return\n  }\n\n  if (drift.action === 'count') {\n    summary.counted += 1\n    await doc.ref.set(\n      {\n        lastCheckedAtMs: nowMs,\n        recheckFailures: drift.consecutiveFailures,\n        recheckFirstFailureAtMs: drift.firstFailureAtMs,\n        // Recorded while the domain is still verified and still sending, so\n        // the console can say WHICH record went missing before the deadline\n        // rather than only after it.\n        lastMissing: verdict.missing,\n      },\n      { merge: true },\n    )\n    return\n  }\n\n  summary.revoked += 1\n  await doc.ref.set(\n    {\n      status: 'failed',\n      lastCheckedAtMs: nowMs,\n      lastMissing: verdict.missing,\n      // The run is spent. A domain that is re-verified and drifts again starts\n      // its own count rather than inheriting this one.\n      recheckFailures: del,\n      recheckFirstFailureAtMs: del,\n    },\n    { merge: true },\n  )\n  console.warn(\n    `[sending-domains] un-verified ${record.domain}: ${verdict.missing.join(', ')}`,\n  )\n}\n\nexport default recheckSendingDomains\n"],"names":["assessDomainDrift","firebaseAdmin","probeSendingRecords","readSendingDomainRecord","SENDING_DOMAINS_COLLECTION","SENDING_DOMAIN_RECHECK_AFTER_MS","SENDING_DOMAIN_FAILURES_BEFORE_REVOKE","SENDING_DOMAIN_DRIFT_MIN_AGE_MS","SENDING_DOMAIN_RECHECK_BATCH","EMPTY","checked","held","cleared","counted","revoked","driftProbeStatus","verdict","recheckSendingDomains","options","nowMs","Date","now","store","firestore","app","cutoff","recheckAfterMs","due","snapshot","collectionGroup","where","orderBy","limit","batch","get","docs","error","console","summary","doc","recheckOneDomain","id","record","data","drift","status","records","consecutiveFailures","Number","recheckFailures","firstFailureAtMs","recheckFirstFailureAtMs","failuresBeforeRevoke","minAgeMs","del","FieldValue","delete","action","ref","set","lastCheckedAtMs","merge","lastMissing","missing","warn","domain","join"],"mappings":"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"}

package/src/lib/server/sending-domains.d.ts

@@ -0,0 +1,364 @@
+/**
+ * @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 — durable half.
+ *
+ * The record, the DNS lookups and the status transitions. The decisions all
+ * live in `@aglyn/shared-util-email`'s `sending-domain.ts`, which is pure;
+ * this module is the I/O around them, and it holds no policy of its own.
+ *
+ * ## Per-org record, per-host selection
+ *
+ * The record is at `orgs/{orgId}/sendingDomains/{domain}`, alongside
+ * `orgs/{orgId}/ssoDomains/{domain}` and for the same reason: proving control
+ * of a zone is a property of the ORG that proved it, and an agency running
+ * four sites on `client.com` should publish the DKIM record once rather than
+ * four times.
+ *
+ * Which identity a given site SENDS on is a separate per-host field,
+ * `hosts/{hostId}.sendingDomain`. That split is what answers the two halves of
+ * the question at once: per-org verification keeps the DNS chore down, and a
+ * per-host selection is what an agency's client actually wants, because the
+ * `From:` their recipients see belongs to the site, not to the agency.
+ *
+ * ## Reads are cheap on purpose
+ *
+ * `resolveHostSendingIdentity` is on the path of a campaign send, so it reads
+ * the host document the caller already has and at most ONE org subcollection
+ * document. It never scans, never lists, and never touches DNS — the standing
+ * rule against unrequested reads on a hot path applies here more than most,
+ * because a campaign resolves an identity once for thousands of messages.
+ *
+ * ## Why the provider call is not in here
+ *
+ * Issuing a DKIM key means creating a domain at the mail provider, which needs
+ * a credential that can create things — a different one from the send-only
+ * `RESEND_API_KEY`, which is exactly why `email-health.ts` can use the domains
+ * endpoint as a read-only credential probe.
+ *
+ * That credential belongs to the console alone, so the driver that reads it
+ * lives in the console app — `apps/console/utils/server/` — and not here.
+ * **This library is imported by the tenant runtime**, which
+ * serves untrusted published sites; a module it can import is a module whose
+ * environment read is one bug away from being reachable from a site request.
+ * A file in `apps/console` is not importable from the tenant app at all —
+ * there is no path mapping to it and nx's module boundaries forbid app→app —
+ * so the isolation is structural rather than a convention.
+ *
+ * What stays here is the seam: {@link recordIssuedSendingDomain} takes what a
+ * provider returned, and {@link recordSendingDomainIssueFailure} takes what it
+ * refused. `requestSendingDomain` still stops at `requested`, and a domain
+ * stopped there refuses sends, which is the correct behavior for a domain that
+ * has no signing key.
+ */
+import { type DmarcAssessment, type SendingDnsRecord, type SendingDomainRecord, type SendingIdentityPurpose, type SendingIdentityVerdict, type SendingVerification } from '@aglyn/shared-util-email';
+/** Subcollection under the owning org. */
+export declare const SENDING_DOMAINS_COLLECTION = "sendingDomains";
+/**
+ * The DKIM selector issued to one org for one domain.
+ *
+ * Includes the org id so two orgs verifying the same name occupy different
+ * record names. Without that they would share `resend._domainkey.<domain>`,
+ * and whichever verified second would overwrite the first — or, worse, inherit
+ * the first's verification without ever publishing anything.
+ */
+export declare function sendingDkimSelector(orgId: string): string;
+/** Both keys always present, one always null — `strictNullChecks` is off. */
+export interface SendingDomainResult {
+    record: SendingDomainRecord | null;
+    error: string | null;
+    /** The HTTP status a route should answer with. */
+    status: number;
+}
+/**
+ * One stored document as a record.
+ *
+ * Exported so the re-check sweep, which reaches these documents through a
+ * collection-group query rather than by org and name, shapes them the same way
+ * every other reader here does — a second reader with its own defaults is how
+ * two callers come to disagree about what an absent field means.
+ */
+export declare function readSendingDomainRecord(snapshot: FirebaseFirestore.DocumentSnapshot): SendingDomainRecord | null;
+/**
+ * Start (or re-read) a claim on a sending domain.
+ *
+ * Idempotent, and deliberately non-destructive on a re-request: an existing
+ * record keeps its selector and its key, because reissuing either would
+ * invalidate a record the customer may already have published and turn a
+ * working setup into a mysterious failure. This mirrors `issueDomainClaim`.
+ */
+export declare function requestSendingDomain(options: {
+    orgId: string;
+    domain: string;
+}): Promise<SendingDomainResult>;
+/**
+ * Record the key the mail provider issued, moving the domain to
+ * `records-issued` so the customer has something to publish.
+ *
+ * Separated from {@link requestSendingDomain} because it needs a credential
+ * that may not exist. Nothing here calls the provider: the caller supplies
+ * what it was given, so a deployment whose key cannot create domains still has
+ * a working path — an operator can complete this step by hand — and this
+ * module never grows a dependency on a credential it cannot assume. The
+ * console holds the credential and the driver that uses it; this library,
+ * which the tenant runtime also imports, holds neither.
+ *
+ * ## `records-issued` is a promise that records exist
+ *
+ * The write is refused unless the resulting record actually yields a DKIM
+ * record with a value. The alternative is the failure this whole feature is
+ * arranged against: a status saying the customer has records to publish, next
+ * to a records table with an empty DKIM row, which cannot ever verify and
+ * reads to the customer as our bug.
+ *
+ * ## An issued key is never overwritten
+ *
+ * A second call carrying a DIFFERENT key is refused rather than applied. The
+ * customer may already have published the first one, and replacing it turns a
+ * finished setup into a domain that silently stops signing. Re-recording the
+ * SAME key is a no-op and succeeds, so a retried request is safe.
+ *
+ * The SELECTOR, by contrast, comes from the provider when it supplies one:
+ * the record a customer publishes has to be the name the provider will sign
+ * under, and `sendingDkimSelector` only proposes it.
+ */
+export declare function recordIssuedSendingDomain(options: {
+    orgId: string;
+    domain: string;
+    dkimPublicKey: string;
+    /** The selector the provider issued, when it chose its own. */
+    dkimSelector?: string;
+    returnPathHost?: string;
+    providerDomainId?: string;
+    /**
+     * The provider's tracking host, when it issued one — see
+     * `SendingDomainRecord.trackingTarget`. Absent leaves the domain sending
+     * and unmeasured rather than unsent.
+     */
+    trackingTarget?: string | null;
+}): Promise<SendingDomainResult>;
+/**
+ * Record that the provider did not issue anything, WITHOUT moving the status.
+ *
+ * The point of a separate function is that there is no path from a provider
+ * failure to `records-issued`. A `4xx` or `5xx` means no key exists, so the
+ * domain stays `requested` — where it refuses sends, which is correct for a
+ * domain that cannot sign — and carries a reason an admin can act on instead
+ * of appearing to have finished.
+ *
+ * `detail` is a short code the caller built from a fixed vocabulary, never a
+ * provider's response body. {@link safeProviderDetail} is the second line:
+ * an `Authorization` header echoed back by a provider must not become a
+ * Firestore document.
+ */
+export declare function recordSendingDomainIssueFailure(options: {
+    orgId: string;
+    domain: string;
+    detail: string;
+}): Promise<void>;
+export interface SendingDomainView {
+    record: SendingDomainRecord;
+    /** Exactly what the customer must publish. */
+    records: SendingDnsRecord[];
+    /** Their DMARC policy, read and never written. */
+    dmarc: DmarcAssessment | null;
+}
+/** One domain plus the records it needs, for a surface that shows both. */
+export declare function getSendingDomain(orgId: string, rawDomain: string): Promise<SendingDomainView | null>;
+export declare function listSendingDomains(orgId: string): Promise<SendingDomainRecord[]>;
+/**
+ * Read the customer's DMARC policy.
+ *
+ * Advisory in both directions: it never blocks verification and it is never
+ * written. A domain under `p=reject` with our DKIM unpublished hard-fails
+ * every message, and a customer deserves to be told that before they wonder
+ * why their campaign vanished.
+ */
+export declare function readDmarcPolicy(rawDomain: string): Promise<DmarcAssessment | null>;
+/**
+ * Start (or read) the hold that keeps a tracked domain's links alive.
+ *
+ * Stamped on FIRST sighting rather than computed from an orphan timestamp,
+ * because there is no reliable one: a label reassignment leaves no record of
+ * when it happened, and the reaper re-infers the orphan on every pass. The
+ * stamp is the record of when the hold began, so a domain cannot be held
+ * forever by a sweep that keeps starting the clock over.
+ *
+ * @returns the instant the domain may be released, or `null` when there is
+ *          nothing to stamp it on — a domain with no org record cannot be
+ *          held, and refusing to release it on the strength of a hold nobody
+ *          can see would strand a provider slot permanently.
+ */
+export declare function holdTrackedSendingDomain(options: {
+    orgId: string | null;
+    domain: string;
+    nowMs: number;
+    windowMs: number;
+}): Promise<number | null>;
+/**
+ * Whether this domain publishes a CAA policy that would REFUSE the tracking
+ * host's certificate.
+ *
+ * The question decides whether a customer is shown a CAA record at all, and
+ * asking it is the difference between guidance and a footgun. CAA restricts
+ * which authorities may issue, and the lookup stops at the first name in the
+ * tree publishing any record — so:
+ *
+ *  - A domain publishing NOTHING needs nothing. Any authority may already
+ *    issue, and handing over a CAA record to paste would be the change that
+ *    STARTS restricting them, breaking whatever else renews on that name.
+ *  - A domain that publishes some, none of which name our authority, has to
+ *    add one ALONGSIDE what it has.
+ *  - A domain that already names our authority is done.
+ *
+ * Walks up from the tracking host exactly as a certificate authority does,
+ * and stops where a real lookup stops: at the first name with any record.
+ *
+ * @returns `null` when DNS could not be reached, which is not "they publish
+ *          none" — telling a customer to add a CAA on the strength of an
+ *          unanswered lookup is how a working zone gets narrowed by mistake.
+ */
+export declare function readTrackingCaaNeed(rawDomain: string, authority: string): Promise<'not-needed' | 'must-add' | 'satisfied' | null>;
+/**
+ * Read the live DNS for one record and say what it establishes. Writes
+ * nothing.
+ *
+ * Split out so the two callers that need this answer ask the SAME question of
+ * the SAME resolvers: {@link verifySendingDomain}, which acts on it
+ * immediately, and the unattended re-check sweep, which counts conclusive
+ * failures before it acts. A sweep that assessed the records its own way would
+ * be a second opinion on "are these published", and the customer would meet
+ * whichever one happened to run last.
+ *
+ * The three lookups run together because they are independent and the caller
+ * is waiting on the slowest either way.
+ */
+export declare function probeSendingRecords(record: SendingDomainRecord): Promise<SendingVerification>;
+/**
+ * Check the live DNS and move the record to `verified` or `failed`.
+ *
+ * Never throws: a sweep across every org must not stop at the first bad zone.
+ *
+ * An INCONCLUSIVE result writes nothing but the check time. A resolver outage
+ * must not un-verify a working domain — which would silently stop that
+ * tenant's mail — and must not fail a customer who is midway through
+ * publishing either. This is the `hold` arm the SSO drift sweep uses, and the
+ * reason `assessSendingRecords` has three outcomes rather than two.
+ *
+ * Acts on ONE conclusive answer, and that is right for this caller: an admin
+ * pressed Verify and is watching the result, so the check is attended and its
+ * outcome is immediately visible and immediately retryable. The unattended
+ * sweep over already-verified domains is the caller that cannot say that, and
+ * `sending-domain-recheck.ts` is where the extra evidence it needs is
+ * gathered.
+ */
+export declare function verifySendingDomain(orgId: string, rawDomain: string): Promise<{
+    record: SendingDomainRecord | null;
+    missing: string[];
+    inconclusive: boolean;
+    error: string | null;
+}>;
+/**
+ * Drop a claim.
+ *
+ * The host selections pointing at it are NOT rewritten to the platform
+ * identity. A site that was sending as its own domain and now has no verified
+ * one must refuse, not quietly revert — silently moving a tenant's mail back
+ * onto the shared domain is the exact fallback this feature exists to prevent,
+ * and doing it during a delete would be no better than doing it during a send.
+ */
+export declare function releaseSendingDomain(orgId: string, rawDomain: string): Promise<void>;
+/**
+ * The identity one host sends on, ready to hand to `sendEmail`.
+ *
+ * Two document reads at most, and none at all for a host that has no
+ * selection. The host document is passed in rather than re-fetched because
+ * every caller already holds it.
+ *
+ * ## This function cannot return an `aglyn.com` address, and that is the point
+ *
+ * Every caller here is resolving mail FOR A SITE — that is what "host" in the
+ * name means — so every verdict it produces is tenant mail by construction.
+ * `audience: 'tenant'` is therefore passed unconditionally and is not a
+ * parameter: a caller that could choose would eventually choose wrong, and the
+ * wrong choice puts a merchant's list quality onto the domain the platform's
+ * own invoices and password resets leave on.
+ *
+ * A site that has selected NOTHING does not reach `USAGE_EMAIL_FROM` either.
+ * All of its mail goes on the shared pool member `hostSharedFrom` assigns it,
+ * marketing included. What keeps the pool usable is measurement rather than
+ * prohibition: a pooled campaign is graded against the stricter reputation
+ * thresholds, so the site earning complaints is the one that stops.
+ */
+export declare function resolveHostSendingIdentity(options: {
+    orgId: string | null | undefined;
+    /** `hosts/{hostId}.sendingDomain`, the site's selection. */
+    selectedDomain: string | null | undefined;
+    /** `hosts/{hostId}.sendingLocalPart`, defaulted when unset. */
+    selectedLocalPart?: string | null;
+    platformFrom?: string | null;
+    /**
+     * The site, so an unselected host can be assigned a pool member.
+     *
+     * Optional because two of the three callers resolve an identity for a host
+     * they are already holding and one — the console's identity view — is asking
+     * about a specific site by id. A caller that omits it gets no shared
+     * identity, which is the honest answer: the pool assignment is per site, and
+     * "some pool member" is not a thing to send a receipt from.
+     */
+    hostId?: string | null;
+    /**
+     * A pool member this host is pinned to, overriding the hash.
+     *
+     * `hosts/{hostId}.sendingPoolMember`. The QUARANTINE lever: a site whose
+     * transactional mail is generating complaints can be moved onto a member set
+     * aside for it, without disturbing any of the other sites that hash to the
+     * member it was on. Ignored unless it names a real member of the current
+     * pool, so a stale or hand-edited value degrades to the ordinary assignment
+     * rather than to an address nothing signs for.
+     */
+    poolMember?: string | null;
+    /** See `SendingIdentityPurpose`. Defaults to transactional. */
+    purpose?: SendingIdentityPurpose;
+}): Promise<SendingIdentityVerdict>;
+/**
+ * The identity one site sends on, from a `hostId` alone.
+ *
+ * The door every tenant sender uses. {@link resolveHostSendingIdentity} needs
+ * the org id and the host's two selection fields, and a survey of the tenant
+ * send sites found that all of them hold a `hostId` while only three hold an
+ * org id and half never read the host document at all. Asking nineteen call
+ * sites to each assemble the same three values is the shape that produces a
+ * twentieth which does not — and the cost of forgetting here is a message
+ * leaving on the platform's own domain.
+ *
+ * ## The cache is per-call-graph, not per-process
+ *
+ * Passed a `cache`, repeated resolutions for one host cost one pair of reads.
+ * A sweep that mails two hundred abandoned carts across a dozen sites, or a
+ * webhook that sends a receipt and a seller notice for the same order, holds
+ * one map for the run and pays for each site once.
+ *
+ * Deliberately NOT a module-level cache. Verification status is exactly the
+ * thing that changes underneath a long-lived process — the re-check sweep
+ * un-verifies a domain whose records have gone — and a stale entry would keep
+ * a site sending on a domain that no longer authenticates. A caller that
+ * declares a cache has also declared how long it may be trusted.
+ */
+export declare function hostSendingIdentity(hostId: string | null | undefined, cache?: Map<string, SendingIdentityVerdict>): Promise<SendingIdentityVerdict>;
+/** The record keys a surface highlights as outstanding. */
+export declare function outstandingSendingRecords(record: SendingDomainRecord): SendingDnsRecord[];