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

package/src/lib/server/account-addresses.js

@@ -0,0 +1,311 @@
+/**
+ * @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.
+ */ /**
+ * EVERY ADDRESS AN ACCOUNT HOLDS — the one answer, for every consumer.
+ *
+ * ## Why this exists
+ *
+ * Two stores in this product are keyed by ADDRESS rather than by uid:
+ * `emailDeliveries/{sha256(address)}` (the per-recipient delivery log) and
+ * `emailSuppressions/{sha256(address)}`. Everything that reached them passed
+ * ONE address — the Firebase Auth record's current `email` — and an account
+ * is not one address:
+ *
+ *  - A changed primary leaves the old address holding the mail. The new hash
+ *    names an empty document, so the staff card renders a blank table for a
+ *    person we demonstrably emailed. That card's own copy warns that reading
+ *    a blank table as "we never emailed them" is how staff mislead a
+ *    customer; before this module, an email change made the card do exactly
+ *    that.
+ *  - A federated provider carries its own address. `providerData[].email` can
+ *    differ from the primary and is a real mailbox that has received real
+ *    mail.
+ *  - `users/{uid}/emails/{address}` (AGL-2486) holds confirmed aliases and
+ *    every address this account has been moved OFF of.
+ *
+ * Erasure inherited the same single-address assumption, which is the sharp
+ * version of the bug: a prior or secondary address kept its full delivery
+ * history — recipient address, subjects, open and click times — after an
+ * erasure request had been honoured and reported complete.
+ *
+ * ## One resolver, not four call sites
+ *
+ * The delivery-history card, erasure, the audit subject resolution and the
+ * suppression lookups all need the same rule, and four copies of it would
+ * drift apart the way the dead-status set did. So the rule lives here and
+ * every consumer calls in. A caller that wants "the addresses" must not
+ * re-derive them from a record it happens to be holding.
+ *
+ * ## Why `verifiedAccountEmails` is not this function
+ *
+ * `account-emails.ts` already answers a question that reads like this one,
+ * and reusing it here would be a correctness bug in both directions. It is
+ * built for matching an INVITATION, and its three defining choices are all
+ * right for that and wrong for this:
+ *
+ *  - **It returns VERIFIED addresses only.** Correct for an invitation: an
+ *    unverified address must not match one, or adding an address becomes a
+ *    way into somebody else's organization. Wrong here, because unverified
+ *    addresses are precisely where the mail is — a verification message is by
+ *    definition sent to an address that is not yet verified, and it is the
+ *    single most common row in the delivery log. Filtering it out would make
+ *    the card miss the mail a staffer is most often asked about, and would
+ *    make erasure leave it behind.
+ *  - **It reads the subcollection alone.** The primary lives in the Firebase
+ *    Auth record and is mirrored into `users/{uid}/emails` only LAZILY, on
+ *    the account's first read of its own settings. An account that has never
+ *    opened that page has an empty subcollection and a real primary, so this
+ *    would return nothing at all for it.
+ *  - **It `slice`s to `MAX_ACCOUNT_EMAILS`.** A silent truncation is
+ *    tolerable when the cost is an invitation not matching. It is the worst
+ *    available outcome for erasure, which would report success over addresses
+ *    it never swept.
+ *
+ * So this module composes over that one's STORAGE — same subcollection, same
+ * index, and the reverse lookup is delegated to `findAccountByVerifiedAlias`
+ * rather than re-read — and adds the two sources it does not have.
+ *
+ * ⛔ Do not "simplify" this into `verifiedAccountEmails`. The three
+ * differences above are each a defect if collapsed.
+ *
+ * ## THE UNIQUENESS INDEX ONCE HAD A HOLE, AND IT STILL HAS A TAIL
+ *
+ * `emailIdentityIndex` is what stops two accounts holding one address, and it
+ * was claimed in exactly two places: the primary backfill in
+ * `listAccountEmails`, and `confirmAccountEmail`. Neither read `providerData`
+ * — so an address supplied by a federated provider never reached the index,
+ * and two accounts could hold one address without the guard ever seeing them.
+ * The live shape of it is ordinary: an account whose Google provider address
+ * is another account's primary.
+ *
+ * `registerProviderAddresses` now claims for provider-asserted addresses at
+ * the session mint, so this closes going forward and backfills each account
+ * on its next sign-in. Two things follow that this module must keep saying:
+ *
+ *  - **The tail is still open.** An account that has not signed in since is
+ *    still unregistered, and a collision that already exists is not repaired
+ *    by a claim that correctly refuses. `tools/scripts/audit-provider-address-claims.mjs`
+ *    reports both, read-only — resolving a collision means deciding about two
+ *    real accounts, which is not a decision code makes.
+ *  - **A refused claim leaves an address held and unindexed.** That is the
+ *    intended outcome, not a failure, so the reverse direction below is no
+ *    more complete than it was: it still cannot enumerate provider holders.
+ *
+ * The registration writes an account-email row and nothing else. It cannot
+ * reach SSO provisioning — `sso-jit` reads the address the IdP asserted at
+ * sign-in and never consults this store, and
+ * `apps/console/specs/account-emails-never-reach-sso.spec.ts` fails if that
+ * stops being true. That guard is what makes the write safe.
+ *
+ * ## The direction that works, and the one that cannot
+ *
+ * FORWARD (uid → addresses) is complete: all three sources are readable from
+ * the uid. {@link resolveAccountAddresses} is that direction.
+ *
+ * REVERSE (address → uid) is STRUCTURALLY INCOMPLETE and no amount of care
+ * here fixes it. Firebase Auth can look an address up as a primary
+ * (`getUserByEmail`) and `emailIdentityIndex` answers for confirmed aliases,
+ * but there is no query for "which accounts carry this as a provider
+ * address" — that field is only readable once you already have the record.
+ * So {@link findAccountsHoldingAddress} can prove an address is AMBIGUOUS and
+ * can never prove it is unique, and its callers are written to treat a single
+ * answer as "no reason to think otherwise" rather than as a fact.
+ *
+ * That distinction is the whole reason `subjectUid` is omitted rather than
+ * guessed: naming one customer on another customer's data access is worse
+ * than naming nobody.
+ */ import { createHash } from "crypto";
+import { normalizeAccountEmail } from "@aglyn/aglyn/app-utils/account-emails";
+import { ACCOUNT_EMAILS_SUBCOLLECTION, findAccountByVerifiedAlias } from "./account-emails.js";
+import { findUserByEmailAcrossPools } from "./auth-pools.js";
+import firebaseAdmin from "./firebase-admin.js";
+const defaultFirestore = ()=>firebaseAdmin.app().firestore();
+/** `sha256` of the normalized address. */ export function accountAddressKey(address) {
+    return createHash('sha256').update(address).digest('hex');
+}
+/**
+ * Every address `uid` holds, from all three sources.
+ *
+ * `record` is passed in rather than fetched: every caller already has the
+ * Auth record in hand, and re-fetching it would add a pooled lookup to a page
+ * that has already paid for one.
+ *
+ * Best-effort per source. A Firestore outage must not make the delivery card
+ * fall back to the single-address behaviour SILENTLY — it reports
+ * `incomplete` instead, and the callers that destroy data refuse on it.
+ *
+ * @param detectShared consult the reverse direction for each non-primary
+ *        address. One extra lookup per address; skip it where the answer is
+ *        not used.
+ */ export async function resolveAccountAddresses(options) {
+    var _options_firestore, _ref, _ref1, _ref2;
+    const { uid, record } = options;
+    const db = (_options_firestore = options.firestore) != null ? _options_firestore : defaultFirestore();
+    const found = new Map();
+    /** Addresses whose provider-asserted claim was refused. */ const conflicted = new Set();
+    let incomplete = false;
+    const add = (input, source)=>{
+        var _found_get;
+        const address = normalizeAccountEmail(input);
+        if (address === null) return;
+        const sources = (_found_get = found.get(address)) != null ? _found_get : new Set();
+        sources.add(source);
+        found.set(address, sources);
+    };
+    const primary = normalizeAccountEmail((_ref = record == null ? void 0 : record.email) != null ? _ref : null);
+    add((_ref1 = record == null ? void 0 : record.email) != null ? _ref1 : null, 'primary');
+    for (const provider of (_ref2 = record == null ? void 0 : record.providerData) != null ? _ref2 : []){
+        var _ref3;
+        add((_ref3 = provider == null ? void 0 : provider.email) != null ? _ref3 : null, 'provider');
+    }
+    try {
+        const stored = await db.collection('users').doc(uid).collection(ACCOUNT_EMAILS_SUBCOLLECTION).get();
+        for (const doc of stored.docs){
+            var _doc_get;
+            const address = normalizeAccountEmail((_doc_get = doc.get('address')) != null ? _doc_get : doc.id);
+            add(address, 'stored');
+            if (address !== null && doc.get('indexConflict') === true) {
+                conflicted.add(address);
+            }
+        }
+    } catch (error) {
+        // The subcollection is where a FORMER primary lives, so losing it is
+        // precisely how the orphaned-history bug comes back. Never silent.
+        console.error('[account-addresses] stored addresses unreadable', uid, error);
+        incomplete = true;
+    }
+    // Primary first: it is the address staff recognise, and a card that led
+    // with an alias would read as the wrong account.
+    const ordered = [
+        ...found.keys()
+    ].sort((a, b)=>{
+        if (a === primary) return -1;
+        if (b === primary) return 1;
+        return a.localeCompare(b);
+    });
+    const addresses = [];
+    for (const address of ordered){
+        var _found_get;
+        let shared = false;
+        if (options.detectShared === true) {
+            try {
+                const holders = await findAccountsHoldingAddress(address, {
+                    firestore: db
+                });
+                shared = holders.uids.some((holder)=>holder !== uid);
+            } catch (unused) {
+                // Not `incomplete`: a failed sharing probe under-reports a note on a
+                // card. It does not shorten the address list, which is the thing
+                // erasure depends on.
+                shared = false;
+            }
+        }
+        addresses.push({
+            address,
+            sources: [
+                ...(_found_get = found.get(address)) != null ? _found_get : []
+            ],
+            key: accountAddressKey(address),
+            shared,
+            indexConflict: conflicted.has(address)
+        });
+    }
+    return {
+        uid,
+        primary,
+        addresses,
+        incomplete
+    };
+}
+/** Just the addresses, for a caller that needs nothing else. */ export function addressList(set) {
+    return set.addresses.map((entry)=>entry.address);
+}
+/** Just the hashed keys, for a query against a store keyed by them. */ export function addressKeys(set) {
+    return set.addresses.map((entry)=>entry.key);
+}
+/**
+ * Which accounts hold `address`, as far as can be determined.
+ *
+ * ## What it can and cannot see
+ *
+ * It consults the two sources an address can be looked up IN:
+ *
+ *  - Firebase Auth, across pools — the account holding it as its PRIMARY.
+ *  - `emailIdentityIndex/{address}` — the account holding it as a CONFIRMED
+ *    alias.
+ *
+ * It cannot see a `providerData` holder, because Firebase Auth offers no
+ * lookup by provider address; that field is readable only from a record you
+ * already have. This is not a gap that can be closed by trying harder, and
+ * the live shape of it is ordinary: an account whose Google provider address
+ * is another account's primary.
+ *
+ * So the result is sound in ONE direction only. `ambiguous: true` is proof
+ * that more than one account holds the address. `ambiguous: false` is the
+ * absence of evidence, never evidence of absence — a caller must not treat a
+ * single uid as "this address belongs to this person".
+ */ export async function findAccountsHoldingAddress(input, options) {
+    var _ref;
+    const address = normalizeAccountEmail(input);
+    if (address === null) return {
+        address: '',
+        uids: [],
+        ambiguous: false
+    };
+    const db = (_ref = options == null ? void 0 : options.firestore) != null ? _ref : defaultFirestore();
+    const uids = new Set();
+    try {
+        var _pooled_record;
+        const pooled = await findUserByEmailAcrossPools(address);
+        if (pooled == null ? void 0 : (_pooled_record = pooled.record) == null ? void 0 : _pooled_record.uid) uids.add(pooled.record.uid);
+    } catch (unused) {
+    // A pool that would not answer leaves the set smaller, which under-reports
+    // sharing rather than inventing it.
+    }
+    try {
+        // `account-emails.ts`'s own reverse lookup, not a second read of its
+        // index. That function owns what the index means — including that an
+        // unverified row is absent from it by construction — and a private copy
+        // of the read here would be a second place to keep that in step.
+        const alias = await findAccountByVerifiedAlias(address);
+        if (alias == null ? void 0 : alias.uid) uids.add(alias.uid);
+    } catch (unused) {
+    // Same reasoning.
+    }
+    return {
+        address,
+        uids: [
+            ...uids
+        ],
+        ambiguous: uids.size > 1
+    };
+}
+/**
+ * The single account an address can be attributed to, or null.
+ *
+ * Null for BOTH "nobody" and "more than one", deliberately. The caller writes
+ * an audit subject with it, and a row naming the wrong customer is worse than
+ * a row naming none: the collection exists to answer "who at Aglyn read my
+ * data", and an answer that points at an innocent account is not a weaker
+ * answer, it is a false one.
+ */ export async function attributableAccountForAddress(input, options) {
+    var _holders_uids_;
+    const holders = await findAccountsHoldingAddress(input, options);
+    if (holders.ambiguous) return null;
+    return (_holders_uids_ = holders.uids[0]) != null ? _holders_uids_ : null;
+}
+
+//# sourceMappingURL=account-addresses.js.map

package/src/lib/server/account-addresses.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/account-addresses.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 * EVERY ADDRESS AN ACCOUNT HOLDS — the one answer, for every consumer.\n *\n * ## Why this exists\n *\n * Two stores in this product are keyed by ADDRESS rather than by uid:\n * `emailDeliveries/{sha256(address)}` (the per-recipient delivery log) and\n * `emailSuppressions/{sha256(address)}`. Everything that reached them passed\n * ONE address — the Firebase Auth record's current `email` — and an account\n * is not one address:\n *\n *  - A changed primary leaves the old address holding the mail. The new hash\n *    names an empty document, so the staff card renders a blank table for a\n *    person we demonstrably emailed. That card's own copy warns that reading\n *    a blank table as \"we never emailed them\" is how staff mislead a\n *    customer; before this module, an email change made the card do exactly\n *    that.\n *  - A federated provider carries its own address. `providerData[].email` can\n *    differ from the primary and is a real mailbox that has received real\n *    mail.\n *  - `users/{uid}/emails/{address}` (AGL-2486) holds confirmed aliases and\n *    every address this account has been moved OFF of.\n *\n * Erasure inherited the same single-address assumption, which is the sharp\n * version of the bug: a prior or secondary address kept its full delivery\n * history — recipient address, subjects, open and click times — after an\n * erasure request had been honoured and reported complete.\n *\n * ## One resolver, not four call sites\n *\n * The delivery-history card, erasure, the audit subject resolution and the\n * suppression lookups all need the same rule, and four copies of it would\n * drift apart the way the dead-status set did. So the rule lives here and\n * every consumer calls in. A caller that wants \"the addresses\" must not\n * re-derive them from a record it happens to be holding.\n *\n * ## Why `verifiedAccountEmails` is not this function\n *\n * `account-emails.ts` already answers a question that reads like this one,\n * and reusing it here would be a correctness bug in both directions. It is\n * built for matching an INVITATION, and its three defining choices are all\n * right for that and wrong for this:\n *\n *  - **It returns VERIFIED addresses only.** Correct for an invitation: an\n *    unverified address must not match one, or adding an address becomes a\n *    way into somebody else's organization. Wrong here, because unverified\n *    addresses are precisely where the mail is — a verification message is by\n *    definition sent to an address that is not yet verified, and it is the\n *    single most common row in the delivery log. Filtering it out would make\n *    the card miss the mail a staffer is most often asked about, and would\n *    make erasure leave it behind.\n *  - **It reads the subcollection alone.** The primary lives in the Firebase\n *    Auth record and is mirrored into `users/{uid}/emails` only LAZILY, on\n *    the account's first read of its own settings. An account that has never\n *    opened that page has an empty subcollection and a real primary, so this\n *    would return nothing at all for it.\n *  - **It `slice`s to `MAX_ACCOUNT_EMAILS`.** A silent truncation is\n *    tolerable when the cost is an invitation not matching. It is the worst\n *    available outcome for erasure, which would report success over addresses\n *    it never swept.\n *\n * So this module composes over that one's STORAGE — same subcollection, same\n * index, and the reverse lookup is delegated to `findAccountByVerifiedAlias`\n * rather than re-read — and adds the two sources it does not have.\n *\n * ⛔ Do not \"simplify\" this into `verifiedAccountEmails`. The three\n * differences above are each a defect if collapsed.\n *\n * ## THE UNIQUENESS INDEX ONCE HAD A HOLE, AND IT STILL HAS A TAIL\n *\n * `emailIdentityIndex` is what stops two accounts holding one address, and it\n * was claimed in exactly two places: the primary backfill in\n * `listAccountEmails`, and `confirmAccountEmail`. Neither read `providerData`\n * — so an address supplied by a federated provider never reached the index,\n * and two accounts could hold one address without the guard ever seeing them.\n * The live shape of it is ordinary: an account whose Google provider address\n * is another account's primary.\n *\n * `registerProviderAddresses` now claims for provider-asserted addresses at\n * the session mint, so this closes going forward and backfills each account\n * on its next sign-in. Two things follow that this module must keep saying:\n *\n *  - **The tail is still open.** An account that has not signed in since is\n *    still unregistered, and a collision that already exists is not repaired\n *    by a claim that correctly refuses. `tools/scripts/audit-provider-address-claims.mjs`\n *    reports both, read-only — resolving a collision means deciding about two\n *    real accounts, which is not a decision code makes.\n *  - **A refused claim leaves an address held and unindexed.** That is the\n *    intended outcome, not a failure, so the reverse direction below is no\n *    more complete than it was: it still cannot enumerate provider holders.\n *\n * The registration writes an account-email row and nothing else. It cannot\n * reach SSO provisioning — `sso-jit` reads the address the IdP asserted at\n * sign-in and never consults this store, and\n * `apps/console/specs/account-emails-never-reach-sso.spec.ts` fails if that\n * stops being true. That guard is what makes the write safe.\n *\n * ## The direction that works, and the one that cannot\n *\n * FORWARD (uid → addresses) is complete: all three sources are readable from\n * the uid. {@link resolveAccountAddresses} is that direction.\n *\n * REVERSE (address → uid) is STRUCTURALLY INCOMPLETE and no amount of care\n * here fixes it. Firebase Auth can look an address up as a primary\n * (`getUserByEmail`) and `emailIdentityIndex` answers for confirmed aliases,\n * but there is no query for \"which accounts carry this as a provider\n * address\" — that field is only readable once you already have the record.\n * So {@link findAccountsHoldingAddress} can prove an address is AMBIGUOUS and\n * can never prove it is unique, and its callers are written to treat a single\n * answer as \"no reason to think otherwise\" rather than as a fact.\n *\n * That distinction is the whole reason `subjectUid` is omitted rather than\n * guessed: naming one customer on another customer's data access is worse\n * than naming nobody.\n */\n\nimport { createHash } from 'crypto'\nimport { normalizeAccountEmail } from '@aglyn/aglyn/app-utils/account-emails'\nimport {\n  ACCOUNT_EMAILS_SUBCOLLECTION,\n  findAccountByVerifiedAlias,\n} from './account-emails'\nimport { findUserByEmailAcrossPools } from './auth-pools'\nimport firebaseAdmin from './firebase-admin'\n\nconst defaultFirestore = () => firebaseAdmin.app().firestore()\n\n/** Where an address came from. An address can have more than one. */\nexport type AccountAddressSource =\n  /** The Firebase Auth record's `email` — what a token carries today. */\n  | 'primary'\n  /** A federated provider's own address, from `providerData[].email`. */\n  | 'provider'\n  /** A row in `users/{uid}/emails` — a confirmed alias, or a former primary. */\n  | 'stored'\n\n/** One address, with everything a consumer needs to decide what to do. */\nexport interface AccountAddress {\n  /** Lowercased and trimmed. The form both hashed stores key on. */\n  address: string\n  /** Every source that named it, so a card can say WHY it is listed. */\n  sources: AccountAddressSource[]\n  /**\n   * `sha256(address)` — the SAME derivation `emailSuppressionKey` uses, so a\n   * consumer never has to re-derive it and the two can never disagree about\n   * which document describes which person.\n   */\n  key: string\n  /**\n   * Another account holds this address too.\n   *\n   * ⚠️ `false` means \"nothing found\", NOT \"nobody else holds it\" — see the\n   * reverse-direction note in this module's header.\n   */\n  shared: boolean\n  /**\n   * A provider asserted this address for this account and the uniqueness\n   * claim was REFUSED, because another account already held it.\n   *\n   * Carried onto the staff surface rather than left in a log line. The\n   * refusal is the whole mechanism: silently skipping the claim is what let\n   * the live collision exist unrecorded, so an account carrying a provider\n   * address it does not own has to be visible on its own page.\n   */\n  indexConflict: boolean\n}\n\n/**\n * ## How big this can get, and why nothing here slices\n *\n * `MAX_ACCOUNT_EMAILS` is 5 and caps the SUBCOLLECTION only; the primary and\n * the provider addresses are additional, so the set can exceed 5. It stays\n * far under Firestore's 30-element `in` limit in every realistic shape, but\n * \"far under\" is not a guarantee and a truncated erasure is the worst outcome\n * available in this whole area — it reports success over addresses it never\n * swept.\n *\n * So the rule is: consumers ITERATE this list, they do not slice it, and any\n * consumer feeding it to an `in` query CHUNKS. No function in this module\n * truncates its result.\n */\nexport interface AccountAddressSet {\n  uid: string\n  /** The Auth record's current address, or null for an addressless account. */\n  primary: string | null\n  /** Primary first, then the rest in a stable order. */\n  addresses: AccountAddress[]\n  /**\n   * A source threw and the set may be SHORT.\n   *\n   * Load-bearing for erasure: erasing \"every address\" from an incomplete set\n   * is not erasing every address, and the caller has to be able to say so\n   * rather than report a complete erasure it did not perform.\n   */\n  incomplete: boolean\n}\n\n/** `sha256` of the normalized address. */\nexport function accountAddressKey(address: string): string {\n  return createHash('sha256').update(address).digest('hex')\n}\n\n/**\n * Every address `uid` holds, from all three sources.\n *\n * `record` is passed in rather than fetched: every caller already has the\n * Auth record in hand, and re-fetching it would add a pooled lookup to a page\n * that has already paid for one.\n *\n * Best-effort per source. A Firestore outage must not make the delivery card\n * fall back to the single-address behaviour SILENTLY — it reports\n * `incomplete` instead, and the callers that destroy data refuse on it.\n *\n * @param detectShared consult the reverse direction for each non-primary\n *        address. One extra lookup per address; skip it where the answer is\n *        not used.\n */\nexport async function resolveAccountAddresses(options: {\n  uid: string\n  /** The Auth record — `email` and `providerData` are read from it. */\n  record?: {\n    email?: string | null\n    providerData?: readonly { email?: string | null }[]\n  } | null\n  detectShared?: boolean\n  firestore?: any\n}): Promise<AccountAddressSet> {\n  const { uid, record } = options\n  const db = options.firestore ?? defaultFirestore()\n  const found = new Map<string, Set<AccountAddressSource>>()\n  /** Addresses whose provider-asserted claim was refused. */\n  const conflicted = new Set<string>()\n  let incomplete = false\n\n  const add = (input: unknown, source: AccountAddressSource) => {\n    const address = normalizeAccountEmail(input)\n    if (address === null) return\n    const sources = found.get(address) ?? new Set<AccountAddressSource>()\n    sources.add(source)\n    found.set(address, sources)\n  }\n\n  const primary = normalizeAccountEmail(record?.email ?? null)\n  add(record?.email ?? null, 'primary')\n  for (const provider of record?.providerData ?? []) {\n    add(provider?.email ?? null, 'provider')\n  }\n\n  try {\n    const stored = await db\n      .collection('users')\n      .doc(uid)\n      .collection(ACCOUNT_EMAILS_SUBCOLLECTION)\n      .get()\n    for (const doc of stored.docs) {\n      const address = normalizeAccountEmail(doc.get('address') ?? doc.id)\n      add(address, 'stored')\n      if (address !== null && doc.get('indexConflict') === true) {\n        conflicted.add(address)\n      }\n    }\n  } catch (error) {\n    // The subcollection is where a FORMER primary lives, so losing it is\n    // precisely how the orphaned-history bug comes back. Never silent.\n    console.error('[account-addresses] stored addresses unreadable', uid, error)\n    incomplete = true\n  }\n\n  // Primary first: it is the address staff recognise, and a card that led\n  // with an alias would read as the wrong account.\n  const ordered = [...found.keys()].sort((a, b) => {\n    if (a === primary) return -1\n    if (b === primary) return 1\n    return a.localeCompare(b)\n  })\n\n  const addresses: AccountAddress[] = []\n  for (const address of ordered) {\n    let shared = false\n    if (options.detectShared === true) {\n      try {\n        const holders = await findAccountsHoldingAddress(address, {\n          firestore: db,\n        })\n        shared = holders.uids.some((holder) => holder !== uid)\n      } catch {\n        // Not `incomplete`: a failed sharing probe under-reports a note on a\n        // card. It does not shorten the address list, which is the thing\n        // erasure depends on.\n        shared = false\n      }\n    }\n    addresses.push({\n      address,\n      sources: [...(found.get(address) ?? [])],\n      key: accountAddressKey(address),\n      shared,\n      indexConflict: conflicted.has(address),\n    })\n  }\n\n  return { uid, primary, addresses, incomplete }\n}\n\n/** Just the addresses, for a caller that needs nothing else. */\nexport function addressList(set: AccountAddressSet): string[] {\n  return set.addresses.map((entry) => entry.address)\n}\n\n/** Just the hashed keys, for a query against a store keyed by them. */\nexport function addressKeys(set: AccountAddressSet): string[] {\n  return set.addresses.map((entry) => entry.key)\n}\n\nexport interface AddressHolders {\n  address: string\n  /** Every uid found to hold it. May be SHORT — see below. */\n  uids: string[]\n  /** More than one distinct account was found. */\n  ambiguous: boolean\n}\n\n/**\n * Which accounts hold `address`, as far as can be determined.\n *\n * ## What it can and cannot see\n *\n * It consults the two sources an address can be looked up IN:\n *\n *  - Firebase Auth, across pools — the account holding it as its PRIMARY.\n *  - `emailIdentityIndex/{address}` — the account holding it as a CONFIRMED\n *    alias.\n *\n * It cannot see a `providerData` holder, because Firebase Auth offers no\n * lookup by provider address; that field is readable only from a record you\n * already have. This is not a gap that can be closed by trying harder, and\n * the live shape of it is ordinary: an account whose Google provider address\n * is another account's primary.\n *\n * So the result is sound in ONE direction only. `ambiguous: true` is proof\n * that more than one account holds the address. `ambiguous: false` is the\n * absence of evidence, never evidence of absence — a caller must not treat a\n * single uid as \"this address belongs to this person\".\n */\nexport async function findAccountsHoldingAddress(\n  input: unknown,\n  options?: { firestore?: any },\n): Promise<AddressHolders> {\n  const address = normalizeAccountEmail(input)\n  if (address === null) return { address: '', uids: [], ambiguous: false }\n  const db = options?.firestore ?? defaultFirestore()\n  const uids = new Set<string>()\n\n  try {\n    const pooled = await findUserByEmailAcrossPools(address)\n    if (pooled?.record?.uid) uids.add(pooled.record.uid)\n  } catch {\n    // A pool that would not answer leaves the set smaller, which under-reports\n    // sharing rather than inventing it.\n  }\n\n  try {\n    // `account-emails.ts`'s own reverse lookup, not a second read of its\n    // index. That function owns what the index means — including that an\n    // unverified row is absent from it by construction — and a private copy\n    // of the read here would be a second place to keep that in step.\n    const alias = await findAccountByVerifiedAlias(address)\n    if (alias?.uid) uids.add(alias.uid)\n  } catch {\n    // Same reasoning.\n  }\n\n  return { address, uids: [...uids], ambiguous: uids.size > 1 }\n}\n\n/**\n * The single account an address can be attributed to, or null.\n *\n * Null for BOTH \"nobody\" and \"more than one\", deliberately. The caller writes\n * an audit subject with it, and a row naming the wrong customer is worse than\n * a row naming none: the collection exists to answer \"who at Aglyn read my\n * data\", and an answer that points at an innocent account is not a weaker\n * answer, it is a false one.\n */\nexport async function attributableAccountForAddress(\n  input: unknown,\n  options?: { firestore?: any },\n): Promise<string | null> {\n  const holders = await findAccountsHoldingAddress(input, options)\n  if (holders.ambiguous) return null\n  return holders.uids[0] ?? null\n}\n"],"names":["createHash","normalizeAccountEmail","ACCOUNT_EMAILS_SUBCOLLECTION","findAccountByVerifiedAlias","findUserByEmailAcrossPools","firebaseAdmin","defaultFirestore","app","firestore","accountAddressKey","address","update","digest","resolveAccountAddresses","options","uid","record","db","found","Map","conflicted","Set","incomplete","add","input","source","sources","get","set","primary","email","provider","providerData","stored","collection","doc","docs","id","error","console","ordered","keys","sort","a","b","localeCompare","addresses","shared","detectShared","holders","findAccountsHoldingAddress","uids","some","holder","push","key","indexConflict","has","addressList","map","entry","addressKeys","ambiguous","pooled","alias","size","attributableAccountForAddress"],"mappings":"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"}

package/src/lib/server/account-emails.d.ts

@@ -0,0 +1,219 @@
+/**
+ * @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 AccountEmail, type PrimaryChangeVerdict } from '@aglyn/aglyn/app-utils/account-emails';
+export declare const ACCOUNT_EMAILS_SUBCOLLECTION = "emails";
+export declare const EMAIL_IDENTITY_INDEX_COLLECTION = "emailIdentityIndex";
+export declare const EMAIL_VERIFICATIONS_COLLECTION = "emailVerifications";
+/**
+ * Long enough that a confirmation link survives a mail client's queue and a
+ * user who reads mail in the evening; short enough that a link sitting in a
+ * forwarded thread stops working. Firebase's own action links use one day.
+ */
+export declare const EMAIL_VERIFICATION_TTL_MS: number;
+export interface AccountEmailRow extends AccountEmail {
+    /** Null until the round-trip completes. ISO string for the API surface. */
+    verifiedAt: string | null;
+}
+/** Every refusal this module can produce, as a stable machine-readable code. */
+export type AccountEmailRefusal = 'invalid-address' | 'cap-reached' | 'already-on-this-account' | 'claimed-by-another-account' | 'unknown-address' | 'cannot-remove-primary' | 'last-verified-address' | 'token-invalid' | 'token-expired' | PrimaryChangeVerdict;
+export interface AccountEmailResult {
+    ok: boolean;
+    refusal: AccountEmailRefusal | null;
+    message: string | null;
+}
+/**
+ * Read the account's addresses, seeding the primary row from Firebase Auth on
+ * first read.
+ *
+ * THE BACKFILL IS NOT OPTIONAL. Every account that exists today predates this
+ * subcollection, so without the seed an established user opens the card and
+ * is told they have no addresses — while `decoded.email` says otherwise — and
+ * then "you cannot remove your last verified address" would be enforced
+ * against an empty set. The Firebase Auth record is the authority for the
+ * primary, so the seed is a mirror rather than a new fact.
+ *
+ * `authEmailVerified` is carried through honestly: an account that has never
+ * confirmed its own sign-up address gets an UNVERIFIED primary row, which is
+ * the truth and which the card then offers to fix.
+ */
+export declare function listAccountEmails(uid: string, authEmail: string | null | undefined, authEmailVerified: boolean): Promise<AccountEmailRow[]>;
+/**
+ * Stage a new address and return the secret for its confirmation link.
+ *
+ * The address is stored UNVERIFIED and does nothing until the round-trip
+ * completes: it is not a sign-in identifier, it receives no account mail, and
+ * — importantly — it does NOT claim the uniqueness index. Claiming on `add`
+ * would make this endpoint a squatting tool: anyone could park an address
+ * they do not own and lock its real owner out of adding it. The index is
+ * claimed by {@link confirmAccountEmail}, so the first account to prove
+ * delivery wins, and proving delivery is the only way to win.
+ *
+ * The pre-flight `addressTakenByAnother` here is a courtesy, not the guard —
+ * it turns the common case into an immediate, honest error instead of a
+ * confirmation email that fails at the end. The real check runs again inside
+ * the confirmation transaction, because anything can change in between.
+ */
+export declare function addAccountEmail(uid: string, input: unknown): Promise<AccountEmailResult & {
+    address: string | null;
+    secret: string | null;
+}>;
+/**
+ * Mint a single-use confirmation secret and store only its digest.
+ *
+ * The returned string is `{tokenId}.{secret}`; the caller puts it in the
+ * emailed link and never persists it. A reader of the database therefore
+ * cannot confirm anybody's address — they hold a SHA-256 of the half that
+ * matters.
+ */
+export declare function issueVerificationToken(uid: string, address: string): Promise<string>;
+/**
+ * Complete the round-trip: the bearer of this link can receive mail at the
+ * address, so the address becomes verified and the account claims it.
+ *
+ * Deliberately NOT authenticated against the current session. The person
+ * clicking the link is whoever opened the mailbox, and requiring them to be
+ * signed in as the right account first is how confirmation links strand
+ * people who read mail on a different device. The token itself carries the
+ * uid, and it can do nothing except verify the one address it was minted for.
+ *
+ * The uniqueness claim happens HERE and inside the same logical step as the
+ * flag flip, so two accounts racing on one address cannot both end up
+ * verified.
+ */
+export declare function confirmAccountEmail(token: unknown): Promise<AccountEmailResult & {
+    address: string | null;
+    uid: string | null;
+}>;
+/**
+ * Remove an address, freeing its index entry.
+ *
+ * The index entry is released so the address can be used again — on this
+ * account or another. Leaving it behind would make removal a way to burn an
+ * address permanently, including somebody else's if they ever wanted it.
+ */
+export declare function removeAccountEmail(uid: string, input: unknown): Promise<AccountEmailResult>;
+export interface SetPrimaryContext {
+    /** `decoded.firebase?.tenant` — the pool the caller signed in through. */
+    tenantId: string | null;
+}
+/**
+ * Re-designate the primary address.
+ *
+ * THE MOST SECURITY-SENSITIVE WRITE IN THIS MODULE, because the primary IS
+ * the Firebase Auth record's email, which is what `decoded.email` carries,
+ * which is what `evaluateSsoDomainPolicy` reads at the session mint and what
+ * the invite-accept comparison matches on. Changing it changes an
+ * authorization input — so it goes through `evaluatePrimaryChange` first, and
+ * that function refuses to move a primary off a domain the deployment
+ * requires SSO for. See its docstring for why that refusal ignores the
+ * enforcement switch.
+ *
+ * The Auth record is updated in the account's OWN pool via `authForPool`: a
+ * project-level `updateUser` cannot see a GCIP tenant account, so the narrow
+ * call would silently fail for exactly the enterprise users this policy is
+ * about.
+ *
+ * `emailVerified: true` is set alongside the address, and it is honest — the
+ * only addresses that can reach this point are ones this module verified by
+ * an emailed round-trip. Omitting it would flip the account to unverified and
+ * lock it out of every route behind `emailUnverifiedResponse()`.
+ */
+export declare function setPrimaryAccountEmail(uid: string, input: unknown, context: SetPrimaryContext): Promise<AccountEmailResult>;
+/**
+ * The account that holds `address` as a VERIFIED alias, or null.
+ *
+ * ## Read this before calling it
+ *
+ * This is the one lookup that maps an arbitrary address to an account, and it
+ * exists for exactly two callers: resolving a sign-in identifier, and
+ * matching an org invitation. Both are safe for the same reason — neither
+ * GRANTS anything on the strength of the address:
+ *
+ *  - a sign-in identifier still has to be followed by the account's password;
+ *  - an invitation is an explicit grant the ORG made, and this only decides
+ *    which of the recipient's mailboxes it may arrive at.
+ *
+ * It must never be wired into an SSO path. `sso-jit` resolves the org from
+ * the GCIP tenant on a re-verified token and matches the domain the IdP
+ * asserted; giving it this function would let a user add an address and be
+ * provisioned into the matching organization, which is the escalation this
+ * whole feature was designed around.
+ *
+ * Returns null for an unverified row by construction: the index is only ever
+ * written by the confirmation path.
+ */
+export declare function findAccountByVerifiedAlias(input: unknown): Promise<{
+    uid: string;
+    address: string;
+} | null>;
+/** What one {@link registerProviderAddresses} pass did. */
+export interface ProviderAddressRegistration {
+    /** Addresses newly claimed for this account. */
+    claimed: string[];
+    /** Addresses another account already holds — recorded, never taken. */
+    conflicted: string[];
+}
+/**
+ * Register the addresses a federated provider asserts for this account.
+ *
+ * Called from the session mint — the one place every interactive sign-in
+ * passes through with a verified token — and BEST-EFFORT by contract.
+ *
+ * ## Three rules, in priority order
+ *
+ * 1. **Sign-in must not depend on this.** It is bookkeeping. A person locked
+ *    out because an index write failed is a worse outcome than the collision
+ *    it was preventing, so every failure here is swallowed and logged, and
+ *    the caller runs it off the critical path.
+ * 2. **A claim never takes an entry another account holds.**
+ *    {@link claimIndexEntry} already refuses; what was missing is that the
+ *    refusal went nowhere. A conflict now lands on the row as
+ *    `indexConflict`, which the staff account page reads — silently skipping
+ *    is exactly what produced the live collision.
+ * 3. **A conflicted address is stored UNVERIFIED.** This is the conservative
+ *    half and it matters: `verifiedAccountEmails` feeds invitation matching,
+ *    so marking a contested address verified on both accounts would make one
+ *    invitation match two people. Unverified, the row is a record that the
+ *    address exists on this account and grants nothing.
+ *
+ * ⛔ It does not merge, reassign or disable anything. Two real accounts
+ * sharing an address is a human decision — the row makes it visible and stops
+ * there.
+ *
+ * ⚠️ Registering here CANNOT reach SSO provisioning. `sso-jit` reads the
+ * address the IdP asserted at sign-in and never consults this store;
+ * `apps/console/specs/account-emails-never-reach-sso.spec.ts` fails if that
+ * stops being true. That guard is what makes this safe to write at all.
+ */
+export declare function registerProviderAddresses(uid: string, record: {
+    email?: string | null;
+    providerData?: readonly {
+        providerId?: string | null;
+        email?: string | null;
+    }[];
+} | null): Promise<ProviderAddressRegistration>;
+/**
+ * Every VERIFIED address on an account, for matching an invitation.
+ *
+ * Bounded by {@link MAX_ACCOUNT_EMAILS}, which is what makes it safe to feed
+ * straight into a Firestore `in` query (limit 30).
+ *
+ * ⛔ NOT the answer to "every address this account holds" — it is verified-only,
+ * subcollection-only and silently truncating, all correct here and all wrong
+ * there. `account-addresses.ts` is that resolver and explains why at length.
+ */
+export declare function verifiedAccountEmails(uid: string): Promise<string[]>;