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

package/src/lib/server/resolve-people.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @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.
+ */
+/**
+ * Bulk uid → person resolution for staff surfaces (AGL-938).
+ *
+ * A staff page must never show a raw uid where a name or email will do
+ * (AGL-810), but "resolve the uid" is a three-store question:
+ *
+ * 1. **Firebase Auth pools** — the project pool plus every GCIP tenant, via
+ *    `findUserByUidAcrossPools` (AGL-1122). A project-level lookup alone
+ *    would silently miss every SSO account.
+ * 2. **The org member roster**, `orgs/{orgId}/members/{uid}` — the identity
+ *    source for members whose auth record cannot be reached (a deleted
+ *    account whose membership lingers, or a tenant-listing outage while the
+ *    pools fail soft). The roster carries `email`/`displayName` precisely so
+ *    other people stay nameable without an auth read (AGL-1127).
+ * 3. **Nobody** — `system:cron` actors, erased accounts. The uid comes back
+ *    marked unresolved so the caller can render it as itself, with a hint,
+ *    rather than crash or spin.
+ *
+ * Fail-soft by contract: an outage in any store degrades a name back to a
+ * uid. It must never take down the page that asked.
+ */
+import type { PooledUserRecord } from './auth-pools';
+/** Where a uid resolved: an auth pool, the org roster, or nowhere. */
+export type PersonSource = 'auth' | 'roster';
+export interface ResolvedPerson {
+    uid: string;
+    email: string | null;
+    displayName: string | null;
+    /** Null when no store answered — render the uid itself, flagged unknown. */
+    source: PersonSource | null;
+}
+export interface ResolveUidsOptions {
+    /**
+     * Org whose member roster backs up the auth pools. Without it, uids that
+     * miss every pool simply come back unresolved.
+     */
+    orgId?: string;
+    /** Injectable for tests; defaults to the admin app's Firestore. */
+    firestore?: any;
+    /** Injectable for tests; defaults to `findUserByUidAcrossPools`. */
+    findUser?: (uid: string) => Promise<PooledUserRecord | null>;
+}
+/**
+ * Resolve a batch of uids to people, deduplicated, keyed by uid. Every
+ * requested uid is present in the result — unresolvable ones as
+ * `{ email: null, displayName: null, source: null }` — so callers can index
+ * without existence checks.
+ */
+export declare function resolveUidsToPeople(uids: ReadonlyArray<string | null | undefined>, options?: ResolveUidsOptions): Promise<Record<string, ResolvedPerson>>;
+export default resolveUidsToPeople;

package/src/lib/server/resolve-people.js

@@ -0,0 +1,112 @@
+/**
+ * @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.
+ */ /**
+ * Bulk uid → person resolution for staff surfaces (AGL-938).
+ *
+ * A staff page must never show a raw uid where a name or email will do
+ * (AGL-810), but "resolve the uid" is a three-store question:
+ *
+ * 1. **Firebase Auth pools** — the project pool plus every GCIP tenant, via
+ *    `findUserByUidAcrossPools` (AGL-1122). A project-level lookup alone
+ *    would silently miss every SSO account.
+ * 2. **The org member roster**, `orgs/{orgId}/members/{uid}` — the identity
+ *    source for members whose auth record cannot be reached (a deleted
+ *    account whose membership lingers, or a tenant-listing outage while the
+ *    pools fail soft). The roster carries `email`/`displayName` precisely so
+ *    other people stay nameable without an auth read (AGL-1127).
+ * 3. **Nobody** — `system:cron` actors, erased accounts. The uid comes back
+ *    marked unresolved so the caller can render it as itself, with a hint,
+ *    rather than crash or spin.
+ *
+ * Fail-soft by contract: an outage in any store degrades a name back to a
+ * uid. It must never take down the page that asked.
+ */ import { findUserByUidAcrossPools } from "./auth-pools.js";
+import firebaseAdmin from "./firebase-admin.js";
+/**
+ * Resolve a batch of uids to people, deduplicated, keyed by uid. Every
+ * requested uid is present in the result — unresolvable ones as
+ * `{ email: null, displayName: null, source: null }` — so callers can index
+ * without existence checks.
+ */ export async function resolveUidsToPeople(uids, options = {}) {
+    var _options_findUser;
+    const find = (_options_findUser = options.findUser) != null ? _options_findUser : findUserByUidAcrossPools;
+    const unique = [
+        ...new Set(uids.filter((uid)=>typeof uid === 'string' && !!uid))
+    ];
+    const people = {};
+    const missed = [];
+    await Promise.all(unique.map(async (uid)=>{
+        try {
+            const found = await find(uid);
+            if (found) {
+                var _found_record_email, _found_record_displayName;
+                people[uid] = {
+                    uid,
+                    email: (_found_record_email = found.record.email) != null ? _found_record_email : null,
+                    displayName: (_found_record_displayName = found.record.displayName) != null ? _found_record_displayName : null,
+                    source: 'auth'
+                };
+                return;
+            }
+        } catch (unused) {
+        // An auth outage is a miss, not a failure — the roster below may
+        // still name this person.
+        }
+        missed.push(uid);
+    }));
+    if (missed.length && options.orgId) {
+        try {
+            var _options_firestore;
+            const db = (_options_firestore = options.firestore) != null ? _options_firestore : firebaseAdmin.app().firestore();
+            const members = db.collection('orgs').doc(options.orgId).collection('members');
+            const snapshots = await db.getAll(...missed.map((uid)=>members.doc(uid)));
+            snapshots.forEach((snapshot, index)=>{
+                if (!snapshot.exists) return;
+                const email = snapshot.get('email');
+                const displayName = snapshot.get('displayName');
+                // A roster doc with neither field names nobody — that uid stays
+                // unresolved rather than resolving to an empty person.
+                if (typeof email !== 'string' && typeof displayName !== 'string') {
+                    return;
+                }
+                people[missed[index]] = {
+                    uid: missed[index],
+                    email: typeof email === 'string' && email ? email : null,
+                    displayName: typeof displayName === 'string' && displayName ? displayName : null,
+                    source: 'roster'
+                };
+            });
+        } catch (error) {
+            // Roster unreachable: those uids render as themselves. Logged, not
+            // thrown — a labelling nicety must not 500 the page that asked.
+            console.error('roster fallback failed while resolving uids', error);
+        }
+    }
+    for (const uid of unique){
+        if (!people[uid]) {
+            people[uid] = {
+                uid,
+                email: null,
+                displayName: null,
+                source: null
+            };
+        }
+    }
+    return people;
+}
+export default resolveUidsToPeople;
+
+//# sourceMappingURL=resolve-people.js.map

package/src/lib/server/resolve-people.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/resolve-people.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 * Bulk uid → person resolution for staff surfaces (AGL-938).\n *\n * A staff page must never show a raw uid where a name or email will do\n * (AGL-810), but \"resolve the uid\" is a three-store question:\n *\n * 1. **Firebase Auth pools** — the project pool plus every GCIP tenant, via\n *    `findUserByUidAcrossPools` (AGL-1122). A project-level lookup alone\n *    would silently miss every SSO account.\n * 2. **The org member roster**, `orgs/{orgId}/members/{uid}` — the identity\n *    source for members whose auth record cannot be reached (a deleted\n *    account whose membership lingers, or a tenant-listing outage while the\n *    pools fail soft). The roster carries `email`/`displayName` precisely so\n *    other people stay nameable without an auth read (AGL-1127).\n * 3. **Nobody** — `system:cron` actors, erased accounts. The uid comes back\n *    marked unresolved so the caller can render it as itself, with a hint,\n *    rather than crash or spin.\n *\n * Fail-soft by contract: an outage in any store degrades a name back to a\n * uid. It must never take down the page that asked.\n */\n\nimport type { PooledUserRecord } from './auth-pools'\nimport { findUserByUidAcrossPools } from './auth-pools'\nimport firebaseAdmin from './firebase-admin'\n\n/** Where a uid resolved: an auth pool, the org roster, or nowhere. */\nexport type PersonSource = 'auth' | 'roster'\n\nexport interface ResolvedPerson {\n  uid: string\n  email: string | null\n  displayName: string | null\n  /** Null when no store answered — render the uid itself, flagged unknown. */\n  source: PersonSource | null\n}\n\nexport interface ResolveUidsOptions {\n  /**\n   * Org whose member roster backs up the auth pools. Without it, uids that\n   * miss every pool simply come back unresolved.\n   */\n  orgId?: string\n  /** Injectable for tests; defaults to the admin app's Firestore. */\n  firestore?: any\n  /** Injectable for tests; defaults to `findUserByUidAcrossPools`. */\n  findUser?: (uid: string) => Promise<PooledUserRecord | null>\n}\n\n/**\n * Resolve a batch of uids to people, deduplicated, keyed by uid. Every\n * requested uid is present in the result — unresolvable ones as\n * `{ email: null, displayName: null, source: null }` — so callers can index\n * without existence checks.\n */\nexport async function resolveUidsToPeople(\n  uids: ReadonlyArray<string | null | undefined>,\n  options: ResolveUidsOptions = {},\n): Promise<Record<string, ResolvedPerson>> {\n  const find = options.findUser ?? findUserByUidAcrossPools\n  const unique = [\n    ...new Set(\n      uids.filter((uid): uid is string => typeof uid === 'string' && !!uid),\n    ),\n  ]\n  const people: Record<string, ResolvedPerson> = {}\n  const missed: string[] = []\n\n  await Promise.all(\n    unique.map(async (uid) => {\n      try {\n        const found = await find(uid)\n        if (found) {\n          people[uid] = {\n            uid,\n            email: found.record.email ?? null,\n            displayName: found.record.displayName ?? null,\n            source: 'auth',\n          }\n          return\n        }\n      } catch {\n        // An auth outage is a miss, not a failure — the roster below may\n        // still name this person.\n      }\n      missed.push(uid)\n    }),\n  )\n\n  if (missed.length && options.orgId) {\n    try {\n      const db = options.firestore ?? firebaseAdmin.app().firestore()\n      const members = db\n        .collection('orgs')\n        .doc(options.orgId)\n        .collection('members')\n      const snapshots = await db.getAll(\n        ...missed.map((uid: string) => members.doc(uid)),\n      )\n      snapshots.forEach((snapshot: any, index: number) => {\n        if (!snapshot.exists) return\n        const email = snapshot.get('email')\n        const displayName = snapshot.get('displayName')\n        // A roster doc with neither field names nobody — that uid stays\n        // unresolved rather than resolving to an empty person.\n        if (typeof email !== 'string' && typeof displayName !== 'string') {\n          return\n        }\n        people[missed[index]] = {\n          uid: missed[index],\n          email: typeof email === 'string' && email ? email : null,\n          displayName:\n            typeof displayName === 'string' && displayName\n              ? displayName\n              : null,\n          source: 'roster',\n        }\n      })\n    } catch (error) {\n      // Roster unreachable: those uids render as themselves. Logged, not\n      // thrown — a labelling nicety must not 500 the page that asked.\n      console.error('roster fallback failed while resolving uids', error)\n    }\n  }\n\n  for (const uid of unique) {\n    if (!people[uid]) {\n      people[uid] = { uid, email: null, displayName: null, source: null }\n    }\n  }\n  return people\n}\n\nexport default resolveUidsToPeople\n"],"names":["findUserByUidAcrossPools","firebaseAdmin","resolveUidsToPeople","uids","options","find","findUser","unique","Set","filter","uid","people","missed","Promise","all","map","found","email","record","displayName","source","push","length","orgId","db","firestore","app","members","collection","doc","snapshots","getAll","forEach","snapshot","index","exists","get","error","console"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;CAoBC,GAGD,SAASA,wBAAwB,QAAQ,kBAAc;AACvD,OAAOC,mBAAmB,sBAAkB;AAyB5C;;;;;CAKC,GACD,OAAO,eAAeC,oBACpBC,IAA8C,EAC9CC,UAA8B,CAAC,CAAC;QAEnBA;IAAb,MAAMC,QAAOD,oBAAAA,QAAQE,QAAQ,YAAhBF,oBAAoBJ;IACjC,MAAMO,SAAS;WACV,IAAIC,IACLL,KAAKM,MAAM,CAAC,CAACC,MAAuB,OAAOA,QAAQ,YAAY,CAAC,CAACA;KAEpE;IACD,MAAMC,SAAyC,CAAC;IAChD,MAAMC,SAAmB,EAAE;IAE3B,MAAMC,QAAQC,GAAG,CACfP,OAAOQ,GAAG,CAAC,OAAOL;QAChB,IAAI;YACF,MAAMM,QAAQ,MAAMX,KAAKK;YACzB,IAAIM,OAAO;oBAGAA,qBACMA;gBAHfL,MAAM,CAACD,IAAI,GAAG;oBACZA;oBACAO,KAAK,GAAED,sBAAAA,MAAME,MAAM,CAACD,KAAK,YAAlBD,sBAAsB;oBAC7BG,WAAW,GAAEH,4BAAAA,MAAME,MAAM,CAACC,WAAW,YAAxBH,4BAA4B;oBACzCI,QAAQ;gBACV;gBACA;YACF;QACF,EAAE,eAAM;QACN,iEAAiE;QACjE,0BAA0B;QAC5B;QACAR,OAAOS,IAAI,CAACX;IACd;IAGF,IAAIE,OAAOU,MAAM,IAAIlB,QAAQmB,KAAK,EAAE;QAClC,IAAI;gBACSnB;YAAX,MAAMoB,MAAKpB,qBAAAA,QAAQqB,SAAS,YAAjBrB,qBAAqBH,cAAcyB,GAAG,GAAGD,SAAS;YAC7D,MAAME,UAAUH,GACbI,UAAU,CAAC,QACXC,GAAG,CAACzB,QAAQmB,KAAK,EACjBK,UAAU,CAAC;YACd,MAAME,YAAY,MAAMN,GAAGO,MAAM,IAC5BnB,OAAOG,GAAG,CAAC,CAACL,MAAgBiB,QAAQE,GAAG,CAACnB;YAE7CoB,UAAUE,OAAO,CAAC,CAACC,UAAeC;gBAChC,IAAI,CAACD,SAASE,MAAM,EAAE;gBACtB,MAAMlB,QAAQgB,SAASG,GAAG,CAAC;gBAC3B,MAAMjB,cAAcc,SAASG,GAAG,CAAC;gBACjC,gEAAgE;gBAChE,uDAAuD;gBACvD,IAAI,OAAOnB,UAAU,YAAY,OAAOE,gBAAgB,UAAU;oBAChE;gBACF;gBACAR,MAAM,CAACC,MAAM,CAACsB,MAAM,CAAC,GAAG;oBACtBxB,KAAKE,MAAM,CAACsB,MAAM;oBAClBjB,OAAO,OAAOA,UAAU,YAAYA,QAAQA,QAAQ;oBACpDE,aACE,OAAOA,gBAAgB,YAAYA,cAC/BA,cACA;oBACNC,QAAQ;gBACV;YACF;QACF,EAAE,OAAOiB,OAAO;YACd,mEAAmE;YACnE,gEAAgE;YAChEC,QAAQD,KAAK,CAAC,+CAA+CA;QAC/D;IACF;IAEA,KAAK,MAAM3B,OAAOH,OAAQ;QACxB,IAAI,CAACI,MAAM,CAACD,IAAI,EAAE;YAChBC,MAAM,CAACD,IAAI,GAAG;gBAAEA;gBAAKO,OAAO;gBAAME,aAAa;gBAAMC,QAAQ;YAAK;QACpE;IACF;IACA,OAAOT;AACT;AAEA,eAAeT,oBAAmB"}

package/src/lib/server/safe-equal.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @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.
+ */
+/**
+ * Constant-time string comparison that tolerates a length mismatch
+ * (AGL-1353 D8, extraction 2).
+ *
+ * The length-check-then-`timingSafeEqual` dance was hand-written in six files:
+ * `media-signing.ts`, `edit-access-token.ts`, commerce `download.ts`,
+ * `membership.ts`, `workflows/server.ts` and `apps/console/utils/cron-auth.ts`.
+ * Every one of them carries its own note explaining the same hazard, which is
+ * the shape of a helper that has not been written yet.
+ *
+ * **The length check is the load-bearing half.** `timingSafeEqual` THROWS on
+ * buffers of different lengths, and in every one of those call sites the
+ * length is attacker-controlled — a presented signature, a token segment, a
+ * header. Forgetting it turns a `401`/`403` into an unhandled `500`, which is
+ * both an outage and an oracle: a thrown request and a refused one are
+ * distinguishable from outside.
+ *
+ * **What this does and does not hide.** The comparison itself is constant-time
+ * for equal-length inputs. The length is compared first and in variable time,
+ * so this leaks whether the candidate was the right LENGTH and nothing else —
+ * the same property every hand-written copy had, and an acceptable one when
+ * the expected length is a public constant (a hex digest, a base64url secret)
+ * rather than a secret.
+ *
+ * Byte length, not code points: both sides are encoded as UTF-8 before
+ * comparison, so a multi-byte candidate cannot slip past the length check and
+ * reach the throwing call.
+ */
+export declare function safeEqual(presented: string | null | undefined, expected: string | null | undefined): boolean;

package/src/lib/server/safe-equal.js

@@ -0,0 +1,58 @@
+/**
+ * @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.
+ */ import { timingSafeEqual } from "crypto";
+/**
+ * Constant-time string comparison that tolerates a length mismatch
+ * (AGL-1353 D8, extraction 2).
+ *
+ * The length-check-then-`timingSafeEqual` dance was hand-written in six files:
+ * `media-signing.ts`, `edit-access-token.ts`, commerce `download.ts`,
+ * `membership.ts`, `workflows/server.ts` and `apps/console/utils/cron-auth.ts`.
+ * Every one of them carries its own note explaining the same hazard, which is
+ * the shape of a helper that has not been written yet.
+ *
+ * **The length check is the load-bearing half.** `timingSafeEqual` THROWS on
+ * buffers of different lengths, and in every one of those call sites the
+ * length is attacker-controlled — a presented signature, a token segment, a
+ * header. Forgetting it turns a `401`/`403` into an unhandled `500`, which is
+ * both an outage and an oracle: a thrown request and a refused one are
+ * distinguishable from outside.
+ *
+ * **What this does and does not hide.** The comparison itself is constant-time
+ * for equal-length inputs. The length is compared first and in variable time,
+ * so this leaks whether the candidate was the right LENGTH and nothing else —
+ * the same property every hand-written copy had, and an acceptable one when
+ * the expected length is a public constant (a hex digest, a base64url secret)
+ * rather than a secret.
+ *
+ * Byte length, not code points: both sides are encoded as UTF-8 before
+ * comparison, so a multi-byte candidate cannot slip past the length check and
+ * reach the throwing call.
+ */ export function safeEqual(presented, expected) {
+    if (typeof presented !== 'string' || typeof expected !== 'string') {
+        return false;
+    }
+    const a = Buffer.from(presented, 'utf8');
+    const b = Buffer.from(expected, 'utf8');
+    // Both empty is a match only in the vacuous sense, and every caller here is
+    // comparing against a value that must exist. An empty expectation means a
+    // secret was not configured, so refusing is the fail-closed answer.
+    if (a.length === 0 || b.length === 0) return false;
+    if (a.length !== b.length) return false;
+    return timingSafeEqual(new Uint8Array(a), new Uint8Array(b));
+}
+
+//# sourceMappingURL=safe-equal.js.map

package/src/lib/server/safe-equal.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/safe-equal.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\nimport { timingSafeEqual } from 'crypto'\n\n/**\n * Constant-time string comparison that tolerates a length mismatch\n * (AGL-1353 D8, extraction 2).\n *\n * The length-check-then-`timingSafeEqual` dance was hand-written in six files:\n * `media-signing.ts`, `edit-access-token.ts`, commerce `download.ts`,\n * `membership.ts`, `workflows/server.ts` and `apps/console/utils/cron-auth.ts`.\n * Every one of them carries its own note explaining the same hazard, which is\n * the shape of a helper that has not been written yet.\n *\n * **The length check is the load-bearing half.** `timingSafeEqual` THROWS on\n * buffers of different lengths, and in every one of those call sites the\n * length is attacker-controlled — a presented signature, a token segment, a\n * header. Forgetting it turns a `401`/`403` into an unhandled `500`, which is\n * both an outage and an oracle: a thrown request and a refused one are\n * distinguishable from outside.\n *\n * **What this does and does not hide.** The comparison itself is constant-time\n * for equal-length inputs. The length is compared first and in variable time,\n * so this leaks whether the candidate was the right LENGTH and nothing else —\n * the same property every hand-written copy had, and an acceptable one when\n * the expected length is a public constant (a hex digest, a base64url secret)\n * rather than a secret.\n *\n * Byte length, not code points: both sides are encoded as UTF-8 before\n * comparison, so a multi-byte candidate cannot slip past the length check and\n * reach the throwing call.\n */\nexport function safeEqual(\n  presented: string | null | undefined,\n  expected: string | null | undefined,\n): boolean {\n  if (typeof presented !== 'string' || typeof expected !== 'string') {\n    return false\n  }\n  const a = Buffer.from(presented, 'utf8')\n  const b = Buffer.from(expected, 'utf8')\n  // Both empty is a match only in the vacuous sense, and every caller here is\n  // comparing against a value that must exist. An empty expectation means a\n  // secret was not configured, so refusing is the fail-closed answer.\n  if (a.length === 0 || b.length === 0) return false\n  if (a.length !== b.length) return false\n  return timingSafeEqual(new Uint8Array(a), new Uint8Array(b))\n}\n"],"names":["timingSafeEqual","safeEqual","presented","expected","a","Buffer","from","b","length","Uint8Array"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,eAAe,QAAQ,SAAQ;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BC,GACD,OAAO,SAASC,UACdC,SAAoC,EACpCC,QAAmC;IAEnC,IAAI,OAAOD,cAAc,YAAY,OAAOC,aAAa,UAAU;QACjE,OAAO;IACT;IACA,MAAMC,IAAIC,OAAOC,IAAI,CAACJ,WAAW;IACjC,MAAMK,IAAIF,OAAOC,IAAI,CAACH,UAAU;IAChC,4EAA4E;IAC5E,0EAA0E;IAC1E,oEAAoE;IACpE,IAAIC,EAAEI,MAAM,KAAK,KAAKD,EAAEC,MAAM,KAAK,GAAG,OAAO;IAC7C,IAAIJ,EAAEI,MAAM,KAAKD,EAAEC,MAAM,EAAE,OAAO;IAClC,OAAOR,gBAAgB,IAAIS,WAAWL,IAAI,IAAIK,WAAWF;AAC3D"}

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

@@ -0,0 +1,127 @@
+/**
+ * @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.
+ */
+import { type HostSendingDomainTeardown } from './host-sending-domain';
+/**
+ * The console-side teardown, injected rather than imported.
+ *
+ * Releasing the provider's domain object needs a full-access mail credential
+ * and removing the zone records needs a DNS token, and neither may be
+ * reachable from the tenant runtime — which is what makes them live in
+ * `apps/console` and makes this library structurally unable to import them
+ * (`sending-domain-credential-isolation.spec.ts` sweeps the tree for it).
+ *
+ * A caller that HAS those credentials passes the driver in and the domain is
+ * released inline. A caller that does not — the tenant runtime, an operator
+ * script, a self-host with no provider configured — records the debt and the
+ * console's reaper settles it. Both are correct; only the latency differs.
+ */
+export type TeardownSendingDomainDriver = (teardown: HostSendingDomainTeardown) => Promise<{
+    outcome: 'removed' | 'skipped' | 'failed';
+    detail: string | null;
+}>;
+/** What became of one site's dedicated sending domain. */
+export type SendingDomainDisposition = 
+/** The site had no dedicated domain of its own. Nothing to release. */
+'none'
+/** Provider slot freed, zone records removed, our records dropped. */
+ | 'released'
+/** The debt is recorded on the label claim; the reaper owes it a visit. */
+ | 'deferred'
+/** A shared pool member. Never torn down, by anything, ever. */
+ | 'protected';
+export interface SendingDomainDebtRecord {
+    /** The claimed label, and the id of the claim document. */
+    label: string;
+    hostId: string | null;
+    orgId: string | null;
+    domain: string | null;
+    claimedAtMs: number | null;
+    /** Set when a teardown could not be completed. Null on a healthy claim. */
+    orphanedAtMs: number | null;
+    /** A short code naming what refused, safe to store, log and show. */
+    teardownDetail: string | null;
+    /** How many passes have tried and failed to settle this. */
+    teardownAttempts: number;
+    providerDomainId: string | null;
+    dkimSelector: string | null;
+}
+/** One claim document as a debt record. */
+export declare function readSendingDomainDebt(snapshot: FirebaseFirestore.DocumentSnapshot): SendingDomainDebtRecord | 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 declare function readSendingDomainTeardownByLabel(label: string | null | undefined): Promise<HostSendingDomainTeardown | null>;
+/**
+ * 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 declare function recordSendingDomainDebt(teardown: HostSendingDomainTeardown, detail: string | null): Promise<void>;
+/**
+ * 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 declare function disposeHostSendingDomain(options: {
+    /** The site being destroyed. Its `sendingLabel` is read before it goes. */
+    hostId?: string | null;
+    /** Pre-read teardown, for a caller that has already lost the host document. */
+    teardown?: HostSendingDomainTeardown | null;
+    tearDown?: TeardownSendingDomainDriver | null;
+}): Promise<SendingDomainDisposition>;
+/**
+ * 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 declare function listSendingLabelClaims(options: {
+    limit: number;
+    after?: string | null;
+}): Promise<SendingDomainDebtRecord[]>;