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

package/src/lib/server/dns-probe.js

@@ -0,0 +1,184 @@
+/**
+ * @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.
+ */ /**
+ * One DNS lookup, pinned to public resolvers, that can say "I do not know".
+ *
+ * The same shape appeared independently in `/api/domains/verify` (AGL-734) and
+ * in `sso-provisioning.ts` (AGL-1210), and a third copy was about to be
+ * written for sending domains. It is here once instead.
+ *
+ * ## Why the resolvers are pinned
+ *
+ * The runtime's default resolver is not a neutral observer. A stale zone once
+ * made the hosting platform's own resolver return NXDOMAIN for records every
+ * public resolver could see, which reads as "the customer deleted their
+ * record" and is indistinguishable from the real thing. Asking a public
+ * resolver first, and falling back to the runtime's only when the pinned ones
+ * are unreachable, keeps a genuine "no such record" answer conclusive.
+ *
+ * ## Why there are three outcomes and not two
+ *
+ * A boolean cannot tell "the record is gone" from "nobody answered", and the
+ * difference decides whether a customer's working configuration gets marked
+ * broken during someone else's outage. `NXDOMAIN`/`ENOTFOUND`/`ENODATA` are
+ * ANSWERS — that name has no such record — and stay conclusive. Anything else,
+ * from both the pinned resolvers and the fallback, is `unreachable`, and a
+ * caller must treat it as evidence of nothing in either direction.
+ */ import { promises as dns, Resolver as CallbackResolver } from "dns";
+/** Resolvers asked before the runtime's own. */ export const PUBLIC_DNS_RESOLVERS = [
+    '1.1.1.1',
+    '8.8.8.8'
+];
+/** Whether a resolver error code is an answer rather than a failure to get one. */ export function isConclusiveDnsCode(code) {
+    return code === 'ENOTFOUND' || code === 'ENODATA' || code === 'NXDOMAIN';
+}
+/**
+ * TXT records at `host`, each joined from its chunks and trimmed.
+ *
+ * A TXT answer arrives as an array of string CHUNKS per record, because DNS
+ * splits strings longer than 255 bytes. Comparing without joining means a long
+ * value — every DKIM public key, for instance — can never match.
+ */ export async function lookupTxt(host) {
+    const flatten = (records)=>records.map((chunks)=>chunks.join('').trim());
+    try {
+        const resolver = new CallbackResolver();
+        resolver.setServers(PUBLIC_DNS_RESOLVERS);
+        const records = await new Promise((resolve, reject)=>{
+            resolver.resolveTxt(host, (error, addresses)=>error ? reject(error) : resolve(addresses));
+        });
+        return {
+            answered: true,
+            records: flatten(records)
+        };
+    } catch (error) {
+        const code = error == null ? void 0 : error.code;
+        if (isConclusiveDnsCode(code)) return {
+            answered: true,
+            records: []
+        };
+        try {
+            return {
+                answered: true,
+                records: flatten(await dns.resolveTxt(host))
+            };
+        } catch (fallbackError) {
+            const fallbackCode = fallbackError == null ? void 0 : fallbackError.code;
+            if (isConclusiveDnsCode(fallbackCode)) return {
+                answered: true,
+                records: []
+            };
+            return {
+                answered: false,
+                records: []
+            };
+        }
+    }
+}
+/**
+ * CAA records at `host`, as `<flags> <tag> "<value>"` strings.
+ *
+ * NOT walked up the tree. The caller asks about one exact name, because the
+ * question this exists for is "does THIS name publish a policy of its own",
+ * and a walk would answer a different one — a parent's policy is inherited by
+ * resolution, not by publication, and reporting the parent's records as the
+ * child's would say a name restricts issuance when it publishes nothing.
+ */ export async function lookupCaa(host) {
+    const normalize = (records)=>records.map((entry)=>{
+            var _ref, _ref1, _row_issue;
+            const row = entry;
+            const tag = (row == null ? void 0 : row.issue) !== undefined ? 'issue' : (row == null ? void 0 : row.issuewild) !== undefined ? 'issuewild' : (row == null ? void 0 : row.iodef) !== undefined ? 'iodef' : '';
+            if (!tag) return '';
+            const value = String((_ref = (_ref1 = (_row_issue = row.issue) != null ? _row_issue : row.issuewild) != null ? _ref1 : row.iodef) != null ? _ref : '').trim();
+            return `${Number(row == null ? void 0 : row.critical) || 0} ${tag} "${value}"`;
+        }).filter(Boolean);
+    try {
+        const resolver = new CallbackResolver();
+        resolver.setServers(PUBLIC_DNS_RESOLVERS);
+        const records = await new Promise((resolve, reject)=>{
+            resolver.resolveCaa(host, (error, addresses)=>error ? reject(error) : resolve(addresses));
+        });
+        return {
+            answered: true,
+            records: normalize(records)
+        };
+    } catch (error) {
+        const code = error == null ? void 0 : error.code;
+        if (isConclusiveDnsCode(code)) return {
+            answered: true,
+            records: []
+        };
+        try {
+            return {
+                answered: true,
+                records: normalize(await dns.resolveCaa(host))
+            };
+        } catch (fallbackError) {
+            const fallbackCode = fallbackError == null ? void 0 : fallbackError.code;
+            if (isConclusiveDnsCode(fallbackCode)) return {
+                answered: true,
+                records: []
+            };
+            return {
+                answered: false,
+                records: []
+            };
+        }
+    }
+}
+/** MX records at `host`, exchanges lowercased and stripped of a trailing dot. */ export async function lookupMx(host) {
+    const normalize = (records)=>records.map((entry)=>{
+            var _ref;
+            return {
+                exchange: String((_ref = entry == null ? void 0 : entry.exchange) != null ? _ref : '').trim().toLowerCase().replace(/\.$/, ''),
+                priority: Number(entry == null ? void 0 : entry.priority) || 0
+            };
+        });
+    try {
+        const resolver = new CallbackResolver();
+        resolver.setServers(PUBLIC_DNS_RESOLVERS);
+        const records = await new Promise((resolve, reject)=>{
+            resolver.resolveMx(host, (error, addresses)=>error ? reject(error) : resolve(addresses));
+        });
+        return {
+            answered: true,
+            records: normalize(records)
+        };
+    } catch (error) {
+        const code = error == null ? void 0 : error.code;
+        if (isConclusiveDnsCode(code)) return {
+            answered: true,
+            records: []
+        };
+        try {
+            return {
+                answered: true,
+                records: normalize(await dns.resolveMx(host))
+            };
+        } catch (fallbackError) {
+            const fallbackCode = fallbackError == null ? void 0 : fallbackError.code;
+            if (isConclusiveDnsCode(fallbackCode)) return {
+                answered: true,
+                records: []
+            };
+            return {
+                answered: false,
+                records: []
+            };
+        }
+    }
+}
+
+//# sourceMappingURL=dns-probe.js.map

package/src/lib/server/dns-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/dns-probe.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 * One DNS lookup, pinned to public resolvers, that can say \"I do not know\".\n *\n * The same shape appeared independently in `/api/domains/verify` (AGL-734) and\n * in `sso-provisioning.ts` (AGL-1210), and a third copy was about to be\n * written for sending domains. It is here once instead.\n *\n * ## Why the resolvers are pinned\n *\n * The runtime's default resolver is not a neutral observer. A stale zone once\n * made the hosting platform's own resolver return NXDOMAIN for records every\n * public resolver could see, which reads as \"the customer deleted their\n * record\" and is indistinguishable from the real thing. Asking a public\n * resolver first, and falling back to the runtime's only when the pinned ones\n * are unreachable, keeps a genuine \"no such record\" answer conclusive.\n *\n * ## Why there are three outcomes and not two\n *\n * A boolean cannot tell \"the record is gone\" from \"nobody answered\", and the\n * difference decides whether a customer's working configuration gets marked\n * broken during someone else's outage. `NXDOMAIN`/`ENOTFOUND`/`ENODATA` are\n * ANSWERS — that name has no such record — and stay conclusive. Anything else,\n * from both the pinned resolvers and the fallback, is `unreachable`, and a\n * caller must treat it as evidence of nothing in either direction.\n */\n\nimport { promises as dns, Resolver as CallbackResolver } from 'dns'\n\n/** Resolvers asked before the runtime's own. */\nexport const PUBLIC_DNS_RESOLVERS = ['1.1.1.1', '8.8.8.8']\n\n/** Whether a resolver error code is an answer rather than a failure to get one. */\nexport function isConclusiveDnsCode(code: string | undefined): boolean {\n  return code === 'ENOTFOUND' || code === 'ENODATA' || code === 'NXDOMAIN'\n}\n\nexport interface DnsLookupResult<T> {\n  /**\n   * True when the lookup got an answer, including the answer \"there is\n   * nothing here\". False only when nobody answered.\n   */\n  answered: boolean\n  /** Empty on a conclusive miss and on an unreachable lookup alike. */\n  records: T[]\n}\n\n/**\n * TXT records at `host`, each joined from its chunks and trimmed.\n *\n * A TXT answer arrives as an array of string CHUNKS per record, because DNS\n * splits strings longer than 255 bytes. Comparing without joining means a long\n * value — every DKIM public key, for instance — can never match.\n */\nexport async function lookupTxt(host: string): Promise<DnsLookupResult<string>> {\n  const flatten = (records: string[][]) =>\n    records.map((chunks) => chunks.join('').trim())\n\n  try {\n    const resolver = new CallbackResolver()\n    resolver.setServers(PUBLIC_DNS_RESOLVERS)\n    const records = await new Promise<string[][]>((resolve, reject) => {\n      resolver.resolveTxt(host, (error, addresses) =>\n        error ? reject(error) : resolve(addresses),\n      )\n    })\n    return { answered: true, records: flatten(records) }\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException)?.code\n    if (isConclusiveDnsCode(code)) return { answered: true, records: [] }\n    try {\n      return { answered: true, records: flatten(await dns.resolveTxt(host)) }\n    } catch (fallbackError) {\n      const fallbackCode = (fallbackError as NodeJS.ErrnoException)?.code\n      if (isConclusiveDnsCode(fallbackCode)) return { answered: true, records: [] }\n      return { answered: false, records: [] }\n    }\n  }\n}\n\n/**\n * CAA records at `host`, as `<flags> <tag> \"<value>\"` strings.\n *\n * NOT walked up the tree. The caller asks about one exact name, because the\n * question this exists for is \"does THIS name publish a policy of its own\",\n * and a walk would answer a different one — a parent's policy is inherited by\n * resolution, not by publication, and reporting the parent's records as the\n * child's would say a name restricts issuance when it publishes nothing.\n */\nexport async function lookupCaa(host: string): Promise<DnsLookupResult<string>> {\n  const normalize = (records: unknown[]) =>\n    records\n      .map((entry) => {\n        const row = entry as { critical?: number; issue?: string; issuewild?: string; iodef?: string }\n        const tag = row?.issue !== undefined\n          ? 'issue'\n          : row?.issuewild !== undefined\n            ? 'issuewild'\n            : row?.iodef !== undefined\n              ? 'iodef'\n              : ''\n        if (!tag) return ''\n        const value = String(\n          row.issue ?? row.issuewild ?? row.iodef ?? '',\n        ).trim()\n        return `${Number(row?.critical) || 0} ${tag} \"${value}\"`\n      })\n      .filter(Boolean)\n\n  try {\n    const resolver = new CallbackResolver()\n    resolver.setServers(PUBLIC_DNS_RESOLVERS)\n    const records = await new Promise<unknown[]>((resolve, reject) => {\n      resolver.resolveCaa(host, (error, addresses) =>\n        error ? reject(error) : resolve(addresses as unknown[]),\n      )\n    })\n    return { answered: true, records: normalize(records) }\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException)?.code\n    if (isConclusiveDnsCode(code)) return { answered: true, records: [] }\n    try {\n      return {\n        answered: true,\n        records: normalize((await dns.resolveCaa(host)) as unknown[]),\n      }\n    } catch (fallbackError) {\n      const fallbackCode = (fallbackError as NodeJS.ErrnoException)?.code\n      if (isConclusiveDnsCode(fallbackCode)) return { answered: true, records: [] }\n      return { answered: false, records: [] }\n    }\n  }\n}\n\nexport interface MxRecord {\n  exchange: string\n  priority: number\n}\n\n/** MX records at `host`, exchanges lowercased and stripped of a trailing dot. */\nexport async function lookupMx(host: string): Promise<DnsLookupResult<MxRecord>> {\n  const normalize = (records: { exchange: string; priority: number }[]) =>\n    records.map((entry) => ({\n      exchange: String(entry?.exchange ?? '')\n        .trim()\n        .toLowerCase()\n        .replace(/\\.$/, ''),\n      priority: Number(entry?.priority) || 0,\n    }))\n\n  try {\n    const resolver = new CallbackResolver()\n    resolver.setServers(PUBLIC_DNS_RESOLVERS)\n    const records = await new Promise<{ exchange: string; priority: number }[]>(\n      (resolve, reject) => {\n        resolver.resolveMx(host, (error, addresses) =>\n          error ? reject(error) : resolve(addresses),\n        )\n      },\n    )\n    return { answered: true, records: normalize(records) }\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException)?.code\n    if (isConclusiveDnsCode(code)) return { answered: true, records: [] }\n    try {\n      return { answered: true, records: normalize(await dns.resolveMx(host)) }\n    } catch (fallbackError) {\n      const fallbackCode = (fallbackError as NodeJS.ErrnoException)?.code\n      if (isConclusiveDnsCode(fallbackCode)) return { answered: true, records: [] }\n      return { answered: false, records: [] }\n    }\n  }\n}\n"],"names":["promises","dns","Resolver","CallbackResolver","PUBLIC_DNS_RESOLVERS","isConclusiveDnsCode","code","lookupTxt","host","flatten","records","map","chunks","join","trim","resolver","setServers","Promise","resolve","reject","resolveTxt","error","addresses","answered","fallbackError","fallbackCode","lookupCaa","normalize","entry","row","tag","issue","undefined","issuewild","iodef","value","String","Number","critical","filter","Boolean","resolveCaa","lookupMx","exchange","toLowerCase","replace","priority","resolveMx"],"mappings":"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"}

package/src/lib/server/document-id.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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.
+ */
+/** Firestore's document id ceiling, which the service counts in BYTES. */
+export declare const MAX_DOCUMENT_ID_BYTES = 1500;
+/**
+ * Whether `value` is usable as ONE opaque Firestore document id.
+ *
+ * Every clause is a path escape rather than a style preference: `/` is both
+ * the nesting hazard and the synchronous `.doc()` throw; `.` and `..` are
+ * traversal that Firestore rejects outright; the reserved form throws instead
+ * of reporting absence; and the length is Firestore's own limit, measured in
+ * UTF-8 bytes because that is what the limit counts — 376 emoji are 1504
+ * bytes and would sail through a `.length` check.
+ */
+export declare function isDocumentId(value: unknown): value is string;

package/src/lib/server/document-id.js

@@ -0,0 +1,100 @@
+/**
+ * @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.
+ */ /**
+ * `isDocumentId(value)` — may this value be handed to `.doc()` as ONE opaque
+ * document id (AGL-1771)?
+ *
+ * WHY THE QUESTION EXISTS. `CollectionReference.doc()` appends a
+ * SLASH-SEPARATED path and refuses it only when the resulting component count
+ * comes out odd (`@google-cloud/firestore`, `collection-reference.js`,
+ * measured in `842e72576`). It never treats its argument as one opaque id. So
+ * an unvalidated value taken from a request, a webhook tag, a cookie or a
+ * stored field gives three distinct failures, none of which is "not found":
+ *
+ *  * an ODD component count (`a/b/c`) is a perfectly legal path, so the read
+ *    or write lands beneath a document that does not exist — invisible to
+ *    every console list, because they resolve the parent first;
+ *  * an EVEN one (`half/path`) throws SYNCHRONOUSLY at the line building the
+ *    ref, which is a different failure from a rejected promise and escapes
+ *    any `.catch()` on one. Whether that becomes a clean 500 or rejects out
+ *    of the handler depends entirely on whether the ref is built inside or
+ *    outside the handler's `try`;
+ *  * a reserved `__…__` id answers `INVALID_ARGUMENT` rather than an absent
+ *    snapshot — the trap `542b1023f` hit with `products/__missing__`.
+ *
+ * WHY IT LIVES HERE. This is the third and fourth call site. AGL-1769 wrote
+ * the rule as `isCartId` in `libs/plugins/commerce/src/lib/server/cart-cookie.ts`
+ * and AGL-1768 copied it as a local `isDocumentId` in
+ * `libs/plugins/marketing/src/lib/server/email-events.ts`; AGL-1771's sweep
+ * then found two more handlers that need it. Duplication was the cheaper wait
+ * at two copies and stops being cheaper at four.
+ *
+ * A CORRECTION, since the second copy was made for a stated reason that turns
+ * out to be false: `@nx/enforce-module-boundaries` does NOT refuse an edge
+ * between two feature plugins. Every plugin carries only `aglyn:addons`, and
+ * that tag's rule lists `aglyn:addons` among its permitted targets — indeed
+ * `campaign-send.ts` already imports `@aglyn/plugins-commerce/model` today. The
+ * real objection to marketing importing commerce's cart-cookie module is not
+ * lint but sense: the predicate is not about carts, and reaching it through
+ * `@aglyn/plugins-commerce/server` would pull the whole commerce server graph
+ * — Stripe, the billing webhook — into the marketing plugin for six lines.
+ *
+ * `tenant-data-admin` is the right home instead because it is where Firestore
+ * paths are BUILT, and because {@link updateExisting} — the sibling primitive
+ * answering the same class of question, "must this document already exist?" —
+ * already lives beside it. Both plugins already depend on this library, so no
+ * new edge is created, and this module imports nothing, so none is created
+ * downstream either.
+ *
+ * IMPORT IT FROM THIS ENTRY POINT — `@aglyn/tenant-data-admin/server/document-id`
+ * — and not from the library barrel, which is exported there only for
+ * discoverability beside its siblings. Two reasons, both load-bearing:
+ *
+ *  * this module imports NOTHING, and reaching it through `tenancy.ts` would
+ *    pull ~35 server modules (media CDN, erasure, Next render-cache) into
+ *    callers that today have no such graph. `cart-cookie.ts` imports only
+ *    `crypto`; it should stay that way;
+ *  * nearly every spec touching those callers already does
+ *    `jest.mock('@aglyn/tenant-data-admin', …)` precisely because that graph
+ *    will not load under jest. A barrel import would resolve to whatever the
+ *    mock object happens to contain — `undefined` at best, and at worst a
+ *    permissive stub that turns every path-shaped test value into a false
+ *    green. A leaf entry point is not intercepted, so the predicate under test
+ *    is always the real one.
+ *
+ * WHAT THIS IS NOT. Not an authorization check and not a claim that the
+ * document exists. It bounds a value to one path COMPONENT; whether that
+ * component names anything, and whether this caller may touch it, are separate
+ * questions that only the read, the write, or a gate can answer.
+ */ /**
+ * Firestore reserves ids matching `__…__` and rejects them with
+ * `INVALID_ARGUMENT` rather than returning an absent snapshot.
+ */ const RESERVED_DOCUMENT_ID = /^__.*__$/;
+/** Firestore's document id ceiling, which the service counts in BYTES. */ export const MAX_DOCUMENT_ID_BYTES = 1500;
+/**
+ * Whether `value` is usable as ONE opaque Firestore document id.
+ *
+ * Every clause is a path escape rather than a style preference: `/` is both
+ * the nesting hazard and the synchronous `.doc()` throw; `.` and `..` are
+ * traversal that Firestore rejects outright; the reserved form throws instead
+ * of reporting absence; and the length is Firestore's own limit, measured in
+ * UTF-8 bytes because that is what the limit counts — 376 emoji are 1504
+ * bytes and would sail through a `.length` check.
+ */ export function isDocumentId(value) {
+    return typeof value === 'string' && value.length > 0 && !value.includes('/') && value !== '.' && value !== '..' && !RESERVED_DOCUMENT_ID.test(value) && Buffer.byteLength(value, 'utf8') <= MAX_DOCUMENT_ID_BYTES;
+}
+
+//# sourceMappingURL=document-id.js.map

package/src/lib/server/document-id.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/document-id.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 * `isDocumentId(value)` — may this value be handed to `.doc()` as ONE opaque\n * document id (AGL-1771)?\n *\n * WHY THE QUESTION EXISTS. `CollectionReference.doc()` appends a\n * SLASH-SEPARATED path and refuses it only when the resulting component count\n * comes out odd (`@google-cloud/firestore`, `collection-reference.js`,\n * measured in `842e72576`). It never treats its argument as one opaque id. So\n * an unvalidated value taken from a request, a webhook tag, a cookie or a\n * stored field gives three distinct failures, none of which is \"not found\":\n *\n *  * an ODD component count (`a/b/c`) is a perfectly legal path, so the read\n *    or write lands beneath a document that does not exist — invisible to\n *    every console list, because they resolve the parent first;\n *  * an EVEN one (`half/path`) throws SYNCHRONOUSLY at the line building the\n *    ref, which is a different failure from a rejected promise and escapes\n *    any `.catch()` on one. Whether that becomes a clean 500 or rejects out\n *    of the handler depends entirely on whether the ref is built inside or\n *    outside the handler's `try`;\n *  * a reserved `__…__` id answers `INVALID_ARGUMENT` rather than an absent\n *    snapshot — the trap `542b1023f` hit with `products/__missing__`.\n *\n * WHY IT LIVES HERE. This is the third and fourth call site. AGL-1769 wrote\n * the rule as `isCartId` in `libs/plugins/commerce/src/lib/server/cart-cookie.ts`\n * and AGL-1768 copied it as a local `isDocumentId` in\n * `libs/plugins/marketing/src/lib/server/email-events.ts`; AGL-1771's sweep\n * then found two more handlers that need it. Duplication was the cheaper wait\n * at two copies and stops being cheaper at four.\n *\n * A CORRECTION, since the second copy was made for a stated reason that turns\n * out to be false: `@nx/enforce-module-boundaries` does NOT refuse an edge\n * between two feature plugins. Every plugin carries only `aglyn:addons`, and\n * that tag's rule lists `aglyn:addons` among its permitted targets — indeed\n * `campaign-send.ts` already imports `@aglyn/plugins-commerce/model` today. The\n * real objection to marketing importing commerce's cart-cookie module is not\n * lint but sense: the predicate is not about carts, and reaching it through\n * `@aglyn/plugins-commerce/server` would pull the whole commerce server graph\n * — Stripe, the billing webhook — into the marketing plugin for six lines.\n *\n * `tenant-data-admin` is the right home instead because it is where Firestore\n * paths are BUILT, and because {@link updateExisting} — the sibling primitive\n * answering the same class of question, \"must this document already exist?\" —\n * already lives beside it. Both plugins already depend on this library, so no\n * new edge is created, and this module imports nothing, so none is created\n * downstream either.\n *\n * IMPORT IT FROM THIS ENTRY POINT — `@aglyn/tenant-data-admin/server/document-id`\n * — and not from the library barrel, which is exported there only for\n * discoverability beside its siblings. Two reasons, both load-bearing:\n *\n *  * this module imports NOTHING, and reaching it through `tenancy.ts` would\n *    pull ~35 server modules (media CDN, erasure, Next render-cache) into\n *    callers that today have no such graph. `cart-cookie.ts` imports only\n *    `crypto`; it should stay that way;\n *  * nearly every spec touching those callers already does\n *    `jest.mock('@aglyn/tenant-data-admin', …)` precisely because that graph\n *    will not load under jest. A barrel import would resolve to whatever the\n *    mock object happens to contain — `undefined` at best, and at worst a\n *    permissive stub that turns every path-shaped test value into a false\n *    green. A leaf entry point is not intercepted, so the predicate under test\n *    is always the real one.\n *\n * WHAT THIS IS NOT. Not an authorization check and not a claim that the\n * document exists. It bounds a value to one path COMPONENT; whether that\n * component names anything, and whether this caller may touch it, are separate\n * questions that only the read, the write, or a gate can answer.\n */\n\n/**\n * Firestore reserves ids matching `__…__` and rejects them with\n * `INVALID_ARGUMENT` rather than returning an absent snapshot.\n */\nconst RESERVED_DOCUMENT_ID = /^__.*__$/\n\n/** Firestore's document id ceiling, which the service counts in BYTES. */\nexport const MAX_DOCUMENT_ID_BYTES = 1500\n\n/**\n * Whether `value` is usable as ONE opaque Firestore document id.\n *\n * Every clause is a path escape rather than a style preference: `/` is both\n * the nesting hazard and the synchronous `.doc()` throw; `.` and `..` are\n * traversal that Firestore rejects outright; the reserved form throws instead\n * of reporting absence; and the length is Firestore's own limit, measured in\n * UTF-8 bytes because that is what the limit counts — 376 emoji are 1504\n * bytes and would sail through a `.length` check.\n */\nexport function isDocumentId(value: unknown): value is string {\n  return (\n    typeof value === 'string' &&\n    value.length > 0 &&\n    !value.includes('/') &&\n    value !== '.' &&\n    value !== '..' &&\n    !RESERVED_DOCUMENT_ID.test(value) &&\n    Buffer.byteLength(value, 'utf8') <= MAX_DOCUMENT_ID_BYTES\n  )\n}\n"],"names":["RESERVED_DOCUMENT_ID","MAX_DOCUMENT_ID_BYTES","isDocumentId","value","length","includes","test","Buffer","byteLength"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkEC,GAED;;;CAGC,GACD,MAAMA,uBAAuB;AAE7B,wEAAwE,GACxE,OAAO,MAAMC,wBAAwB,KAAI;AAEzC;;;;;;;;;CASC,GACD,OAAO,SAASC,aAAaC,KAAc;IACzC,OACE,OAAOA,UAAU,YACjBA,MAAMC,MAAM,GAAG,KACf,CAACD,MAAME,QAAQ,CAAC,QAChBF,UAAU,OACVA,UAAU,QACV,CAACH,qBAAqBM,IAAI,CAACH,UAC3BI,OAAOC,UAAU,CAACL,OAAO,WAAWF;AAExC"}

package/src/lib/server/domain-provider-vercel.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @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 Vercel driver — how Aglyn's own hosting registers a name.
+ *
+ * One implementation of the call, one deadline, one never-throws contract. It
+ * was five copies before this file existed: `workspace-domains.ts`, three
+ * console routes and `subdomain-redirect.ts` each held their own `fetch` to
+ * `api.vercel.com`, which is how two copies of a constant drift apart — the
+ * bug AGL-1135 was, one layer down.
+ *
+ * ## The two projects
+ *
+ * The console and the tenant runtime are separate Vercel projects, so the
+ * scope picks the id. One token and one team serve both: a second variable for
+ * the same token is the drift this file exists to prevent.
+ */
+import { type DomainProvider } from './domain-provider';
+export declare const VERCEL_DOMAIN_PROVIDER: DomainProvider;