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

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/account-emails.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 * The store behind several email addresses per account (AGL-2486).\n *\n * The policy — which address anything is allowed to READ — lives in\n * `@aglyn/aglyn/app-utils/account-emails`, pure and client-importable. This\n * module is the Admin-SDK half: the writes, the uniqueness guard, and the\n * verification round-trip.\n *\n * ## Storage, and why every bit of it is server-only\n *\n *  - `users/{uid}/emails/{address}` — the rows. SERVER-WRITE ONLY. This is\n *    not a style choice: `users/{uid}` itself is `allow read, write` for its\n *    owner under the rules, with no field validation whatsoever, so anything\n *    stored ON that document is a field its owner can set to whatever they\n *    like. An owner-writable `verified: true` is the entire feature defeated\n *    — claim `ceo@acme.com`, flip the bit, and you hold a sign-in identifier\n *    for an address you have never been able to receive mail at. So the rows\n *    live in a subcollection with `allow write: if false`, exactly like\n *    `passkeys` and `legalAcceptances`, and for exactly the same reason:\n *    a client-writable credential store is an auth bypass.\n *  - `emailIdentityIndex/{address}` — `{ uid }`, deny-all. THE uniqueness\n *    guard. Two accounts holding the same verified address makes the sign-in\n *    identifier ambiguous, which is an account-takeover vector, not a\n *    cosmetic clash. Modelled on `passkeyCredentialIndex`.\n *  - `emailVerifications/{tokenId}` — `{ uid, address, digest, expiresAt }`,\n *    deny-all, single-use. Only the DIGEST is stored, so a database read does\n *    not yield a working confirmation link. Modelled on\n *    `webauthnChallenges`.\n *\n * ## What is deliberately NOT here\n *\n * There is no `domainsFor(uid)`, no `emailsInDomain(domain)`, and no lookup\n * that answers \"which orgs could this account belong to\". Adding one would be\n * the whole hazard: `sso-jit` grants org membership from a verified email's\n * domain, and a helper that handed it this account's OTHER addresses would\n * turn \"add an address\" into \"join an organization\". The SSO paths read the\n * address the IdP asserted at sign-in and nothing else — see\n * `apps/console/specs/account-emails-never-reach-sso.spec.ts`, which fails if\n * that stops being true.\n */\n\nimport { createHash, randomBytes, timingSafeEqual } from 'node:crypto'\nimport {\n  MAX_ACCOUNT_EMAILS,\n  evaluatePrimaryChange,\n  canRemoveAccountEmail,\n  normalizeAccountEmail,\n  type AccountEmail,\n  type PrimaryChangeVerdict,\n} from '@aglyn/aglyn/app-utils/account-emails'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport firebaseAdmin from './firebase-admin'\nimport { authForPool, findUserByEmailAcrossPools } from './auth-pools'\nimport { ssoDomainEnforcementEnabled, ssoRequiredDomains } from './sso-domain-policy'\n\nconst firestore = () => firebaseAdmin.app().firestore()\n\nexport const ACCOUNT_EMAILS_SUBCOLLECTION = 'emails'\nexport const EMAIL_IDENTITY_INDEX_COLLECTION = 'emailIdentityIndex'\nexport const EMAIL_VERIFICATIONS_COLLECTION = 'emailVerifications'\n\n/**\n * Long enough that a confirmation link survives a mail client's queue and a\n * user who reads mail in the evening; short enough that a link sitting in a\n * forwarded thread stops working. Firebase's own action links use one day.\n */\nexport const EMAIL_VERIFICATION_TTL_MS = 24 * 60 * 60 * 1000\n\n/** Stored row shape. `address` mirrors the document id. */\ninterface StoredAccountEmail {\n  address: string\n  verified: boolean\n  primary: boolean\n  createdAt?: unknown\n  verifiedAt?: unknown\n}\n\nexport interface AccountEmailRow extends AccountEmail {\n  /** Null until the round-trip completes. ISO string for the API surface. */\n  verifiedAt: string | null\n}\n\n/** Every refusal this module can produce, as a stable machine-readable code. */\nexport type AccountEmailRefusal =\n  | 'invalid-address'\n  | 'cap-reached'\n  | 'already-on-this-account'\n  | 'claimed-by-another-account'\n  | 'unknown-address'\n  | 'cannot-remove-primary'\n  | 'last-verified-address'\n  | 'token-invalid'\n  | 'token-expired'\n  | PrimaryChangeVerdict\n\nexport interface AccountEmailResult {\n  ok: boolean\n  refusal: AccountEmailRefusal | null\n  message: string | null\n}\n\nconst ok = (): AccountEmailResult => ({ ok: true, refusal: null, message: null })\nconst refuse = (\n  refusal: AccountEmailRefusal,\n  message: string,\n): AccountEmailResult => ({ ok: false, refusal, message })\n\nfunction emailsRef(uid: string) {\n  return firestore().collection('users').doc(uid).collection(ACCOUNT_EMAILS_SUBCOLLECTION)\n}\n\nfunction indexRef(address: string) {\n  return firestore().collection(EMAIL_IDENTITY_INDEX_COLLECTION).doc(address)\n}\n\nfunction toRow(data: StoredAccountEmail): AccountEmailRow {\n  const verifiedAt = data.verifiedAt as { toDate?: () => Date } | undefined\n  return {\n    address: data.address,\n    verified: data.verified === true,\n    primary: data.primary === true,\n    verifiedAt:\n      verifiedAt !== undefined &&\n      verifiedAt !== null &&\n      typeof verifiedAt.toDate === 'function'\n        ? verifiedAt.toDate().toISOString()\n        : null,\n  }\n}\n\n/**\n * Read the account's addresses, seeding the primary row from Firebase Auth on\n * first read.\n *\n * THE BACKFILL IS NOT OPTIONAL. Every account that exists today predates this\n * subcollection, so without the seed an established user opens the card and\n * is told they have no addresses — while `decoded.email` says otherwise — and\n * then \"you cannot remove your last verified address\" would be enforced\n * against an empty set. The Firebase Auth record is the authority for the\n * primary, so the seed is a mirror rather than a new fact.\n *\n * `authEmailVerified` is carried through honestly: an account that has never\n * confirmed its own sign-up address gets an UNVERIFIED primary row, which is\n * the truth and which the card then offers to fix.\n */\nexport async function listAccountEmails(\n  uid: string,\n  authEmail: string | null | undefined,\n  authEmailVerified: boolean,\n): Promise<AccountEmailRow[]> {\n  const snapshot = await emailsRef(uid).get()\n  const rows = snapshot.docs.map((doc) => toRow(doc.data() as StoredAccountEmail))\n\n  const primaryAddress = normalizeAccountEmail(authEmail)\n  if (primaryAddress === null) return rows\n\n  const known = rows.find((row) => row.address === primaryAddress)\n  if (known !== undefined) {\n    // The Auth record is the authority for WHICH address is primary. If they\n    // ever disagree — a staff email change through the admin console, say —\n    // Auth wins and the mirror is corrected, rather than the card showing a\n    // primary the token does not carry.\n    if (known.primary !== true) {\n      await reconcilePrimaryFlag(uid, primaryAddress)\n      return listAccountEmails(uid, authEmail, authEmailVerified)\n    }\n    return rows\n  }\n\n  await emailsRef(uid)\n    .doc(primaryAddress)\n    .set(\n      {\n        address: primaryAddress,\n        verified: authEmailVerified === true,\n        primary: true,\n        createdAt: FieldValue.serverTimestamp(),\n        ...(authEmailVerified === true\n          ? { verifiedAt: FieldValue.serverTimestamp() }\n          : {}),\n      },\n      { merge: true },\n    )\n  /*\n   * CLEAR THE FLAG OFF WHATEVER USED TO HOLD IT.\n   *\n   * This branch runs when Auth's address is not among the stored rows — which\n   * is exactly what a staff email change produces, since it writes the Auth\n   * record directly. Setting the new row primary without clearing the old one\n   * left TWO rows flagged primary, and every reader that takes the first match\n   * then answers with whichever Firestore returned first.\n   *\n   * Only when there were pre-existing rows: a first-ever seed has nothing to\n   * reconcile and must not pay for a second read and a batch commit.\n   */\n  if (rows.length > 0) await reconcilePrimaryFlag(uid, primaryAddress)\n  // Claim the index for it too, but never steal one: an address already\n  // indexed to somebody else is a real conflict that a backfill must not\n  // paper over. Best-effort — a failed claim must not stop someone reading\n  // their own settings page.\n  if (authEmailVerified === true) {\n    try {\n      await claimIndexEntry(primaryAddress, uid)\n    } catch (error) {\n      console.error('[account-emails] primary index backfill failed', error)\n    }\n  }\n  return [\n    ...rows,\n    {\n      address: primaryAddress,\n      verified: authEmailVerified === true,\n      primary: true,\n      verifiedAt: null,\n    },\n  ]\n}\n\nasync function reconcilePrimaryFlag(uid: string, primaryAddress: string): Promise<void> {\n  const snapshot = await emailsRef(uid).get()\n  const batch = firestore().batch()\n  for (const doc of snapshot.docs) {\n    const shouldBePrimary = doc.id === primaryAddress\n    if ((doc.get('primary') === true) !== shouldBePrimary) {\n      batch.set(doc.ref, { primary: shouldBePrimary }, { merge: true })\n    }\n  }\n  await batch.commit()\n}\n\n/**\n * Claim `address` for `uid` in the uniqueness index, transactionally.\n *\n * Returns false when another account already holds it. Re-claiming your own\n * is a no-op success, which is what makes the whole flow idempotent.\n */\nasync function claimIndexEntry(address: string, uid: string): Promise<boolean> {\n  return firestore().runTransaction(async (transaction) => {\n    const ref = indexRef(address)\n    const existing = await transaction.get(ref)\n    if (existing.exists) {\n      const owner = existing.get('uid')\n      if (owner !== uid) return false\n      return true\n    }\n    transaction.set(ref, { uid, address, claimedAt: FieldValue.serverTimestamp() })\n    return true\n  })\n}\n\n/**\n * Is `address` spoken for by an account other than `uid`?\n *\n * Consults BOTH the index and Firebase Auth, and the Auth half is the\n * load-bearing one. The index only knows about addresses that have been\n * through this feature; every account that existed before it has its primary\n * in the Auth record and nowhere else. Checking the index alone would let a\n * brand-new account claim an established user's sign-up address, which is the\n * exact ambiguity the uniqueness rule exists to prevent.\n *\n * `findUserByEmailAcrossPools` rather than a project-pool `getUserByEmail`:\n * an SSO user lives in their org's GCIP tenant and is invisible to\n * project-level lookups (AGL-1122), so the narrow call would report an\n * enterprise customer's address as free.\n */\nasync function addressTakenByAnother(address: string, uid: string): Promise<boolean> {\n  const indexed = await indexRef(address).get()\n  if (indexed.exists && indexed.get('uid') !== uid) return true\n  const pooled = await findUserByEmailAcrossPools(address)\n  if (pooled !== null && pooled !== undefined && pooled.record.uid !== uid) return true\n  return false\n}\n\n/**\n * Stage a new address and return the secret for its confirmation link.\n *\n * The address is stored UNVERIFIED and does nothing until the round-trip\n * completes: it is not a sign-in identifier, it receives no account mail, and\n * — importantly — it does NOT claim the uniqueness index. Claiming on `add`\n * would make this endpoint a squatting tool: anyone could park an address\n * they do not own and lock its real owner out of adding it. The index is\n * claimed by {@link confirmAccountEmail}, so the first account to prove\n * delivery wins, and proving delivery is the only way to win.\n *\n * The pre-flight `addressTakenByAnother` here is a courtesy, not the guard —\n * it turns the common case into an immediate, honest error instead of a\n * confirmation email that fails at the end. The real check runs again inside\n * the confirmation transaction, because anything can change in between.\n */\nexport async function addAccountEmail(\n  uid: string,\n  input: unknown,\n): Promise<AccountEmailResult & { address: string | null; secret: string | null }> {\n  const address = normalizeAccountEmail(input)\n  if (address === null) {\n    return {\n      ...refuse('invalid-address', 'Enter a valid email address.'),\n      address: null,\n      secret: null,\n    }\n  }\n\n  const existing = await emailsRef(uid).get()\n  if (existing.docs.some((doc) => doc.id === address)) {\n    return {\n      ...refuse('already-on-this-account', 'That address is already on this account.'),\n      address,\n      secret: null,\n    }\n  }\n  // THE CAP (see MAX_ACCOUNT_EMAILS). Counted from a server read immediately\n  // before the write — a number read anywhere else is a number that can be\n  // stale by the time it is trusted.\n  if (existing.size >= MAX_ACCOUNT_EMAILS) {\n    return {\n      ...refuse(\n        'cap-reached',\n        `An account can hold ${MAX_ACCOUNT_EMAILS} email addresses. ` +\n          'Remove one before adding another.',\n      ),\n      address,\n      secret: null,\n    }\n  }\n  if (await addressTakenByAnother(address, uid)) {\n    return {\n      ...refuse(\n        'claimed-by-another-account',\n        'That address is already in use on another account.',\n      ),\n      address,\n      secret: null,\n    }\n  }\n\n  await emailsRef(uid).doc(address).set(\n    {\n      address,\n      verified: false,\n      primary: false,\n      createdAt: FieldValue.serverTimestamp(),\n    },\n    { merge: true },\n  )\n\n  const secret = await issueVerificationToken(uid, address)\n  return { ...ok(), address, secret }\n}\n\n/**\n * Mint a single-use confirmation secret and store only its digest.\n *\n * The returned string is `{tokenId}.{secret}`; the caller puts it in the\n * emailed link and never persists it. A reader of the database therefore\n * cannot confirm anybody's address — they hold a SHA-256 of the half that\n * matters.\n */\nexport async function issueVerificationToken(\n  uid: string,\n  address: string,\n): Promise<string> {\n  const tokenId = randomBytes(16).toString('hex')\n  const secret = randomBytes(32).toString('hex')\n  await firestore()\n    .collection(EMAIL_VERIFICATIONS_COLLECTION)\n    .doc(tokenId)\n    .set({\n      uid,\n      address,\n      digest: createHash('sha256').update(secret).digest('hex'),\n      createdAt: FieldValue.serverTimestamp(),\n      expiresAt: Date.now() + EMAIL_VERIFICATION_TTL_MS,\n    })\n  return `${tokenId}.${secret}`\n}\n\n/** Constant-time compare of two hex digests of equal length. */\nfunction digestsMatch(a: unknown, b: string): boolean {\n  if (typeof a !== 'string' || a.length !== b.length) return false\n  return timingSafeEqual(Buffer.from(a, 'hex'), Buffer.from(b, 'hex'))\n}\n\n/**\n * Complete the round-trip: the bearer of this link can receive mail at the\n * address, so the address becomes verified and the account claims it.\n *\n * Deliberately NOT authenticated against the current session. The person\n * clicking the link is whoever opened the mailbox, and requiring them to be\n * signed in as the right account first is how confirmation links strand\n * people who read mail on a different device. The token itself carries the\n * uid, and it can do nothing except verify the one address it was minted for.\n *\n * The uniqueness claim happens HERE and inside the same logical step as the\n * flag flip, so two accounts racing on one address cannot both end up\n * verified.\n */\nexport async function confirmAccountEmail(\n  token: unknown,\n): Promise<AccountEmailResult & { address: string | null; uid: string | null }> {\n  const raw = String(token ?? '')\n  const separator = raw.indexOf('.')\n  if (separator <= 0) {\n    return {\n      ...refuse('token-invalid', 'That confirmation link is not valid.'),\n      address: null,\n      uid: null,\n    }\n  }\n  const tokenId = raw.slice(0, separator)\n  const secret = raw.slice(separator + 1)\n  if (!/^[a-f0-9]{32}$/.test(tokenId) || !/^[a-f0-9]{64}$/.test(secret)) {\n    return {\n      ...refuse('token-invalid', 'That confirmation link is not valid.'),\n      address: null,\n      uid: null,\n    }\n  }\n\n  const tokenRef = firestore().collection(EMAIL_VERIFICATIONS_COLLECTION).doc(tokenId)\n  const snapshot = await tokenRef.get()\n  if (!snapshot.exists) {\n    return {\n      ...refuse('token-invalid', 'That confirmation link has already been used.'),\n      address: null,\n      uid: null,\n    }\n  }\n  if (!digestsMatch(snapshot.get('digest'), createHash('sha256').update(secret).digest('hex'))) {\n    return {\n      ...refuse('token-invalid', 'That confirmation link is not valid.'),\n      address: null,\n      uid: null,\n    }\n  }\n  const expiresAt = Number(snapshot.get('expiresAt') ?? 0)\n  if (!Number.isFinite(expiresAt) || expiresAt < Date.now()) {\n    await tokenRef.delete()\n    return {\n      ...refuse('token-expired', 'That confirmation link has expired — send a new one.'),\n      address: null,\n      uid: null,\n    }\n  }\n\n  const uid = String(snapshot.get('uid') ?? '')\n  const address = String(snapshot.get('address') ?? '')\n  if (!uid || !address) {\n    await tokenRef.delete()\n    return {\n      ...refuse('token-invalid', 'That confirmation link is not valid.'),\n      address: null,\n      uid: null,\n    }\n  }\n\n  // Single-use: burned before the claim, so a link cannot be replayed even if\n  // the claim below fails.\n  await tokenRef.delete()\n\n  if (await addressTakenByAnother(address, uid)) {\n    return {\n      ...refuse(\n        'claimed-by-another-account',\n        'That address has since been confirmed on another account.',\n      ),\n      address,\n      uid,\n    }\n  }\n  const claimed = await claimIndexEntry(address, uid)\n  if (!claimed) {\n    return {\n      ...refuse(\n        'claimed-by-another-account',\n        'That address has since been confirmed on another account.',\n      ),\n      address,\n      uid,\n    }\n  }\n\n  await emailsRef(uid)\n    .doc(address)\n    .set(\n      { address, verified: true, verifiedAt: FieldValue.serverTimestamp() },\n      { merge: true },\n    )\n  return { ...ok(), address, uid }\n}\n\n/**\n * Remove an address, freeing its index entry.\n *\n * The index entry is released so the address can be used again — on this\n * account or another. Leaving it behind would make removal a way to burn an\n * address permanently, including somebody else's if they ever wanted it.\n */\nexport async function removeAccountEmail(\n  uid: string,\n  input: unknown,\n): Promise<AccountEmailResult> {\n  const address = normalizeAccountEmail(input)\n  if (address === null) return refuse('invalid-address', 'Enter a valid email address.')\n\n  const snapshot = await emailsRef(uid).get()\n  const rows: AccountEmail[] = snapshot.docs.map((doc) => ({\n    address: String(doc.get('address') ?? doc.id),\n    verified: doc.get('verified') === true,\n    primary: doc.get('primary') === true,\n  }))\n  const verdict = canRemoveAccountEmail(address, rows)\n  if (!verdict.allowed) {\n    const row = rows.find((entry) => entry.address === address)\n    // Distinct codes so the card can say WHICH floor it hit — \"make another\n    // address primary first\" and \"this is your only confirmed address\" are\n    // different instructions, and a single code would collapse them into one\n    // unhelpful sentence.\n    const code: AccountEmailRefusal =\n      row === undefined\n        ? 'unknown-address'\n        : row.primary === true\n          ? 'cannot-remove-primary'\n          : 'last-verified-address'\n    return refuse(code, String(verdict.message ?? 'That address cannot be removed.'))\n  }\n\n  await emailsRef(uid).doc(address).delete()\n  const indexed = await indexRef(address).get()\n  if (indexed.exists && indexed.get('uid') === uid) {\n    await indexRef(address).delete()\n  }\n  return ok()\n}\n\nexport interface SetPrimaryContext {\n  /** `decoded.firebase?.tenant` — the pool the caller signed in through. */\n  tenantId: string | null\n}\n\n/**\n * Re-designate the primary address.\n *\n * THE MOST SECURITY-SENSITIVE WRITE IN THIS MODULE, because the primary IS\n * the Firebase Auth record's email, which is what `decoded.email` carries,\n * which is what `evaluateSsoDomainPolicy` reads at the session mint and what\n * the invite-accept comparison matches on. Changing it changes an\n * authorization input — so it goes through `evaluatePrimaryChange` first, and\n * that function refuses to move a primary off a domain the deployment\n * requires SSO for. See its docstring for why that refusal ignores the\n * enforcement switch.\n *\n * The Auth record is updated in the account's OWN pool via `authForPool`: a\n * project-level `updateUser` cannot see a GCIP tenant account, so the narrow\n * call would silently fail for exactly the enterprise users this policy is\n * about.\n *\n * `emailVerified: true` is set alongside the address, and it is honest — the\n * only addresses that can reach this point are ones this module verified by\n * an emailed round-trip. Omitting it would flip the account to unverified and\n * lock it out of every route behind `emailUnverifiedResponse()`.\n */\nexport async function setPrimaryAccountEmail(\n  uid: string,\n  input: unknown,\n  context: SetPrimaryContext,\n): Promise<AccountEmailResult> {\n  const address = normalizeAccountEmail(input)\n  if (address === null) return refuse('invalid-address', 'Enter a valid email address.')\n\n  const snapshot = await emailsRef(uid).get()\n  const rows: AccountEmail[] = snapshot.docs.map((doc) => ({\n    address: String(doc.get('address') ?? doc.id),\n    verified: doc.get('verified') === true,\n    primary: doc.get('primary') === true,\n  }))\n  const current = rows.find((row) => row.primary === true) ?? null\n  const next = rows.find((row) => row.address === address) ?? null\n\n  const decision = evaluatePrimaryChange({\n    current,\n    next,\n    requiredDomains: ssoRequiredDomains(),\n    tenantId: context.tenantId ?? null,\n    enforcementEnabled: ssoDomainEnforcementEnabled(),\n  })\n  if (!decision.allowed) {\n    return refuse(decision.verdict, String(decision.message ?? 'That change is not allowed.'))\n  }\n\n  await authForPool(context.tenantId).updateUser(uid, {\n    email: address,\n    emailVerified: true,\n  })\n  await reconcilePrimaryFlag(uid, address)\n  return ok()\n}\n\n/**\n * The account that holds `address` as a VERIFIED alias, or null.\n *\n * ## Read this before calling it\n *\n * This is the one lookup that maps an arbitrary address to an account, and it\n * exists for exactly two callers: resolving a sign-in identifier, and\n * matching an org invitation. Both are safe for the same reason — neither\n * GRANTS anything on the strength of the address:\n *\n *  - a sign-in identifier still has to be followed by the account's password;\n *  - an invitation is an explicit grant the ORG made, and this only decides\n *    which of the recipient's mailboxes it may arrive at.\n *\n * It must never be wired into an SSO path. `sso-jit` resolves the org from\n * the GCIP tenant on a re-verified token and matches the domain the IdP\n * asserted; giving it this function would let a user add an address and be\n * provisioned into the matching organization, which is the escalation this\n * whole feature was designed around.\n *\n * Returns null for an unverified row by construction: the index is only ever\n * written by the confirmation path.\n */\nexport async function findAccountByVerifiedAlias(\n  input: unknown,\n): Promise<{ uid: string; address: string } | null> {\n  const address = normalizeAccountEmail(input)\n  if (address === null) return null\n  const indexed = await indexRef(address).get()\n  if (!indexed.exists) return null\n  const uid = String(indexed.get('uid') ?? '')\n  if (!uid) return null\n  return { uid, address }\n}\n\n/*==========================================\n * PROVIDER-SUPPLIED ADDRESSES.\n *\n * A federated provider asserts its own address, and `providerData[].email`\n * can differ from the primary. Until now nothing registered one: it was\n * absent from `users/{uid}/emails`, held no `emailIdentityIndex` entry, and\n * so lived entirely OUTSIDE the uniqueness guard — while remaining a real\n * mailbox, a working sign-in identifier, and a recipient of real mail.\n *\n * The consequence is a collision the guard was built to prevent and could not\n * see: one address that is one account's primary and another account's Google\n * provider address. Anything mapping address → uid then answers confidently\n * and wrongly.\n *=========================================*/\n\n/** What one {@link registerProviderAddresses} pass did. */\nexport interface ProviderAddressRegistration {\n  /** Addresses newly claimed for this account. */\n  claimed: string[]\n  /** Addresses another account already holds — recorded, never taken. */\n  conflicted: string[]\n}\n\n/**\n * Providers whose asserted address counts as proven.\n *\n * `password` is excluded because its address is the primary, already handled,\n * and its verification state lives on the Auth record rather than in the\n * provider entry. Everything else here is a federated IdP that has itself\n * established control of the mailbox — the same standard\n * {@link confirmAccountEmail} applies, met by a different party.\n */\nfunction isFederatedProvider(providerId: string | null | undefined): boolean {\n  const id = String(providerId ?? '')\n  return id !== '' && id !== 'password' && id !== 'phone' && id !== 'anonymous'\n}\n\n/**\n * Register the addresses a federated provider asserts for this account.\n *\n * Called from the session mint — the one place every interactive sign-in\n * passes through with a verified token — and BEST-EFFORT by contract.\n *\n * ## Three rules, in priority order\n *\n * 1. **Sign-in must not depend on this.** It is bookkeeping. A person locked\n *    out because an index write failed is a worse outcome than the collision\n *    it was preventing, so every failure here is swallowed and logged, and\n *    the caller runs it off the critical path.\n * 2. **A claim never takes an entry another account holds.**\n *    {@link claimIndexEntry} already refuses; what was missing is that the\n *    refusal went nowhere. A conflict now lands on the row as\n *    `indexConflict`, which the staff account page reads — silently skipping\n *    is exactly what produced the live collision.\n * 3. **A conflicted address is stored UNVERIFIED.** This is the conservative\n *    half and it matters: `verifiedAccountEmails` feeds invitation matching,\n *    so marking a contested address verified on both accounts would make one\n *    invitation match two people. Unverified, the row is a record that the\n *    address exists on this account and grants nothing.\n *\n * ⛔ It does not merge, reassign or disable anything. Two real accounts\n * sharing an address is a human decision — the row makes it visible and stops\n * there.\n *\n * ⚠️ Registering here CANNOT reach SSO provisioning. `sso-jit` reads the\n * address the IdP asserted at sign-in and never consults this store;\n * `apps/console/specs/account-emails-never-reach-sso.spec.ts` fails if that\n * stops being true. That guard is what makes this safe to write at all.\n */\nexport async function registerProviderAddresses(\n  uid: string,\n  record: {\n    email?: string | null\n    providerData?: readonly {\n      providerId?: string | null\n      email?: string | null\n    }[]\n  } | null,\n): Promise<ProviderAddressRegistration> {\n  const claimed: string[] = []\n  const conflicted: string[] = []\n  const primary = normalizeAccountEmail(record?.email ?? null)\n\n  const candidates = new Set<string>()\n  for (const provider of record?.providerData ?? []) {\n    if (!isFederatedProvider(provider?.providerId)) continue\n    const address = normalizeAccountEmail(provider?.email ?? null)\n    // The primary is registered by `listAccountEmails`' own backfill, on the\n    // Auth record's authority. Re-doing it here would race that seed.\n    if (address === null || address === primary) continue\n    candidates.add(address)\n  }\n\n  for (const address of candidates) {\n    try {\n      const won = await claimIndexEntry(address, uid)\n      if (won) claimed.push(address)\n      else conflicted.push(address)\n\n      await emailsRef(uid)\n        .doc(address)\n        .set(\n          {\n            address,\n            // Only when the claim was won — see rule 3.\n            verified: won,\n            primary: false,\n            source: 'provider',\n            ...(won\n              ? { verifiedAt: FieldValue.serverTimestamp(), indexConflict: false }\n              : { indexConflict: true, indexConflictAtMs: Date.now() }),\n            createdAt: FieldValue.serverTimestamp(),\n          },\n          { merge: true },\n        )\n    } catch (error) {\n      // Rule 1. Never rethrow: the caller is a sign-in.\n      console.error('[account-emails] provider address registration failed', uid, error)\n    }\n  }\n\n  if (conflicted.length) {\n    // Loud, per rule 2 — a conflict that only ever landed in a document would\n    // be discovered by whoever happened to open the right page.\n    console.error(\n      '[account-emails] provider address already claimed by another account',\n      JSON.stringify({ uid, conflicted: conflicted.length }),\n    )\n  }\n  return { claimed, conflicted }\n}\n\n/**\n * Every VERIFIED address on an account, for matching an invitation.\n *\n * Bounded by {@link MAX_ACCOUNT_EMAILS}, which is what makes it safe to feed\n * straight into a Firestore `in` query (limit 30).\n *\n * ⛔ NOT the answer to \"every address this account holds\" — it is verified-only,\n * subcollection-only and silently truncating, all correct here and all wrong\n * there. `account-addresses.ts` is that resolver and explains why at length.\n */\nexport async function verifiedAccountEmails(uid: string): Promise<string[]> {\n  const snapshot = await emailsRef(uid).get()\n  return snapshot.docs\n    .filter((doc) => doc.get('verified') === true)\n    .map((doc) => String(doc.get('address') ?? doc.id))\n    .slice(0, MAX_ACCOUNT_EMAILS)\n}\n"],"names":["createHash","randomBytes","timingSafeEqual","MAX_ACCOUNT_EMAILS","evaluatePrimaryChange","canRemoveAccountEmail","normalizeAccountEmail","FieldValue","firebaseAdmin","authForPool","findUserByEmailAcrossPools","ssoDomainEnforcementEnabled","ssoRequiredDomains","firestore","app","ACCOUNT_EMAILS_SUBCOLLECTION","EMAIL_IDENTITY_INDEX_COLLECTION","EMAIL_VERIFICATIONS_COLLECTION","EMAIL_VERIFICATION_TTL_MS","ok","refusal","message","refuse","emailsRef","uid","collection","doc","indexRef","address","toRow","data","verifiedAt","verified","primary","undefined","toDate","toISOString","listAccountEmails","authEmail","authEmailVerified","snapshot","get","rows","docs","map","primaryAddress","known","find","row","reconcilePrimaryFlag","set","createdAt","serverTimestamp","merge","length","claimIndexEntry","error","console","batch","shouldBePrimary","id","ref","commit","runTransaction","transaction","existing","exists","owner","claimedAt","addressTakenByAnother","indexed","pooled","record","addAccountEmail","input","secret","some","size","issueVerificationToken","tokenId","toString","digest","update","expiresAt","Date","now","digestsMatch","a","b","Buffer","from","confirmAccountEmail","token","raw","String","separator","indexOf","slice","test","tokenRef","Number","isFinite","delete","claimed","removeAccountEmail","verdict","allowed","entry","code","setPrimaryAccountEmail","context","current","next","decision","requiredDomains","tenantId","enforcementEnabled","updateUser","email","emailVerified","findAccountByVerifiedAlias","isFederatedProvider","providerId","registerProviderAddresses","conflicted","candidates","Set","provider","providerData","add","won","push","source","indexConflict","indexConflictAtMs","JSON","stringify","verifiedAccountEmails","filter"],"mappings":"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"}

package/src/lib/server/admin-audit.d.ts

@@ -0,0 +1,180 @@
+/**
+ * @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 STAFF AUDIT TRAIL: WHO A ROW IS ABOUT, AND HOW MANY TIMES IT HAPPENED.
+ *
+ * `adminAudit` is not a convenience log. Firestore rules close
+ * `emailDeliveries` to EVERYONE, staff included, and the console route is
+ * allowed to read it only because it establishes a staff claim and records
+ * who looked. The row this module writes is that compensating control, so
+ * the two properties it exists to provide are:
+ *
+ *  1. **No access is lost.** Two views minutes apart are two accesses. A
+ *     collapse that dropped one would answer "nobody read your mail" about a
+ *     read that happened, which is the single failure this collection cannot
+ *     have.
+ *  2. **The subject is answerable.** `target` names the THING acted on; it
+ *     cannot also name the person, because a message id is not a user path.
+ *     `subjectUid` is the separate fact, and it is what makes "who at Aglyn
+ *     read my email" a query rather than a manual trawl.
+ */
+export declare const ADMIN_AUDIT_COLLECTION = "adminAudit";
+/**
+ * How close together two identical acts must be to count as ONE act
+ * recorded twice.
+ *
+ * A single click can reach this writer more than once — a re-run effect, a
+ * retried request, a double submit — and each arrival is the same access.
+ * Ten seconds sits an order of magnitude above that (the observed re-entry
+ * was one second apart) and well below a person deliberately re-opening a
+ * record (observed at fifty-three seconds). Nothing a human does twice on
+ * purpose lands inside it.
+ *
+ * ⚠️ A collapse still RECORDS the repeat: `repeatCount` and `lastAt` carry
+ * it, and the console renders both. Widening this window trades away the
+ * separateness of two accesses, so it must stay far shorter than the
+ * interval at which a second look is a second decision.
+ */
+export declare const ADMIN_AUDIT_DEDUPE_WINDOW_MS = 10000;
+/** Access looked at data; change altered something or acted on someone. */
+export type AdminAuditKind = 'access' | 'change';
+/**
+ * An access when the platform or a plugin declares the action a read — a
+ * plugin's staff card opening on an org or an account names its own read
+ * actions through its activity group (AGL-2939) — and a change otherwise.
+ */
+export declare function adminAuditKind(action: string | null | undefined): AdminAuditKind;
+export interface AdminAuditWrite {
+    /** The staff account performing the act. */
+    actorUid: string;
+    action: string;
+    /** The THING acted on, as a path or a stable identifier. */
+    target: string;
+    /**
+     * The person the act is ABOUT, when one can be resolved.
+     *
+     * Absent is a correct answer, not a failure: a recipient may be a site
+     * member, a prospect or a bare address with no platform account behind it,
+     * and inventing a uid for one of those would put an act on an innocent
+     * person's page.
+     */
+    subjectUid?: string | null;
+    /**
+     * `sha256` of the recipient address the act was about, when it had one.
+     *
+     * ## Why a hash and not the address
+     *
+     * The SAME derivation `emailSuppressionKey` uses, so this joins the
+     * delivery log without a second key space. It is hashed for the reason
+     * {@link maskEmailAddress} exists: `adminAudit` is readable by any staff
+     * role, and a dump of it must not yield a mailing list.
+     *
+     * ## Why it exists at all, next to `subjectUid`
+     *
+     * `subjectUid` can only be written when the address resolves to exactly one
+     * account, and an address is not reliably resolvable to one — a
+     * provider-supplied address may be held by a second account with nothing
+     * recording it. So the subject is now OMITTED whenever the answer is
+     * ambiguous, and omitting it alone would make the access invisible on every
+     * page, which is worse than the guess it replaced.
+     *
+     * This is the fact that needs no guess. The account page queries it with
+     * the keys of every address that account holds, so one access appears on
+     * the page of each account holding the address — which is the honest answer
+     * when the mail went to a mailbox rather than to a uid.
+     *
+     * ## It opens no tier side-door
+     *
+     * `adminAudit` is `allow read, create: if isStaff()` with NO tier gate, so
+     * anything written here is readable by every staff session whatever its
+     * role — which makes an audit row a way around a tier restriction on the
+     * surface the value came from. Checked, and it is not one here: the writer
+     * is the message route, which gates on `staff` alone and nothing finer, so
+     * this field is no more widely readable than its source.
+     *
+     * The hash adds no reach of its own either. It is the document id
+     * `emailDeliveries` is already filed under, so any staff session that can
+     * read this row could already derive the same value from an address it
+     * guessed. A field whose source DID restrict by tier would not belong here.
+     */
+    subjectAddressKey?: string | null;
+    /** Human-readable context. ⚠️ Never a raw address — see `maskEmailAddress`. */
+    note?: string | null;
+}
+/**
+ * Write one audit row, collapsing an immediate repeat of the same act onto
+ * the row already there.
+ *
+ * The candidate is the MOST RECENT row on the same target, which the live
+ * `target ASC, at DESC` index already answers — so this costs one indexed
+ * single-document read and needs no index of its own. Anything else landing
+ * on that target in between ends the run, which is the conservative
+ * direction: an interleaved act means the two views were not one action.
+ *
+ * The read and the write are one TRANSACTION because the duplicates this
+ * exists to catch are CONCURRENT. Two requests from one click race each
+ * other; a plain read-then-write would let both see "nothing recent" and
+ * both insert, defeating the collapse exactly when it is needed.
+ */
+export declare function recordAdminAudit(entry: AdminAuditWrite): Promise<void>;
+/**
+ * An address a human can recognize without the log holding the address.
+ *
+ * `emailDeliveries` is keyed by `sha256(address)` precisely so we do not keep
+ * a readable list of who we mail. An audit row echoing the address in the
+ * clear made this collection the less careful of the two for the same data,
+ * and `adminAudit` is readable by any staff role.
+ *
+ * The first character and the domain survive because an audit entry a human
+ * cannot read is a weaker control: a staffer checking their own access, or an
+ * investigator confirming which of a shortlist was opened, needs to recognize
+ * the row. What does not survive is the harvestable part — a dump of this
+ * collection yields no mailing list.
+ */
+export declare function maskEmailAddress(address: string | null | undefined): string;
+/** Every recipient, masked, in one note-sized string. */
+export declare function maskEmailAddresses(addresses: readonly string[] | null | undefined): string;
+/**
+ * The uid behind a recipient address, or null when there is not one.
+ *
+ * Across POOLS, not the project pool alone: an enterprise account signing in
+ * through GCIP lives in a tenant, and a project-pool `getUserByEmail` would
+ * report the customer most in need of this record as "not a user".
+ *
+ * Null is a real answer. Most addresses we send to belong to site members,
+ * prospects and plain contacts with no platform account, and this must never
+ * guess one for them.
+ */
+export declare function resolveSubjectUidByEmail(address: string | null | undefined): Promise<string | null>;
+/**
+ * The hashed recipient for {@link AdminAuditWrite.subjectAddressKey}.
+ *
+ * The FIRST recipient, matching `resolveSubjectUidForRecipients` — one scalar
+ * cannot represent a multi-recipient message, and the masked note carries the
+ * full list either way.
+ */
+export declare function subjectAddressKeyForRecipients(addresses: readonly string[] | null | undefined): string | null;
+/**
+ * The first recipient with a platform account.
+ *
+ * A single scalar subject cannot represent a message sent to several people,
+ * and multi-recipient system mail is rare enough that an array field plus its
+ * own `array-contains` index would be carried by every writer to serve almost
+ * no rows. The full (masked) recipient list stays on the note, so a row for a
+ * multi-recipient message still shows that the others were involved.
+ */
+export declare function resolveSubjectUidForRecipients(addresses: readonly string[] | null | undefined): Promise<string | null>;

package/src/lib/server/admin-audit.js

@@ -0,0 +1,233 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { isPluginStaffAuditAccess } from "@aglyn/aglyn/plugin-manager/plugin-activity-actions";
+import { attributableAccountForAddress } from "./account-addresses.js";
+import { emailSuppressionKey } from "./email-suppression.js";
+import { firebaseAdmin } from "./firebase-admin.js";
+/**
+ * THE STAFF AUDIT TRAIL: WHO A ROW IS ABOUT, AND HOW MANY TIMES IT HAPPENED.
+ *
+ * `adminAudit` is not a convenience log. Firestore rules close
+ * `emailDeliveries` to EVERYONE, staff included, and the console route is
+ * allowed to read it only because it establishes a staff claim and records
+ * who looked. The row this module writes is that compensating control, so
+ * the two properties it exists to provide are:
+ *
+ *  1. **No access is lost.** Two views minutes apart are two accesses. A
+ *     collapse that dropped one would answer "nobody read your mail" about a
+ *     read that happened, which is the single failure this collection cannot
+ *     have.
+ *  2. **The subject is answerable.** `target` names the THING acted on; it
+ *     cannot also name the person, because a message id is not a user path.
+ *     `subjectUid` is the separate fact, and it is what makes "who at Aglyn
+ *     read my email" a query rather than a manual trawl.
+ */ export const ADMIN_AUDIT_COLLECTION = 'adminAudit';
+/**
+ * How close together two identical acts must be to count as ONE act
+ * recorded twice.
+ *
+ * A single click can reach this writer more than once — a re-run effect, a
+ * retried request, a double submit — and each arrival is the same access.
+ * Ten seconds sits an order of magnitude above that (the observed re-entry
+ * was one second apart) and well below a person deliberately re-opening a
+ * record (observed at fifty-three seconds). Nothing a human does twice on
+ * purpose lands inside it.
+ *
+ * ⚠️ A collapse still RECORDS the repeat: `repeatCount` and `lastAt` carry
+ * it, and the console renders both. Widening this window trades away the
+ * separateness of two accesses, so it must stay far shorter than the
+ * interval at which a second look is a second decision.
+ */ export const ADMIN_AUDIT_DEDUPE_WINDOW_MS = 10000;
+/**
+ * The actions that only LOOKED.
+ *
+ * An exception list, not a classification of everything, and the default
+ * matters more than the membership: anything absent is a `change`. A change
+ * is the louder half of the console's audit card, so an action nobody has
+ * classified yet gets the MORE prominent treatment rather than the quieter
+ * one. The failure mode of the opposite default is an unclassified
+ * impersonation rendering as routine browsing.
+ *
+ * An export is deliberately NOT here. Data leaving the platform is a
+ * high-consequence act even though it mutates nothing, and it belongs beside
+ * the impersonations rather than beside the record views.
+ */ const ADMIN_AUDIT_ACCESS_ACTIONS = new Set([
+    'email.message-viewed'
+]);
+/**
+ * An access when the platform or a plugin declares the action a read — a
+ * plugin's staff card opening on an org or an account names its own read
+ * actions through its activity group (AGL-2939) — and a change otherwise.
+ */ export function adminAuditKind(action) {
+    return action && (ADMIN_AUDIT_ACCESS_ACTIONS.has(action) || isPluginStaffAuditAccess(action)) ? 'access' : 'change';
+}
+function toDate(value) {
+    var _value_toDate;
+    const converted = value == null ? void 0 : (_value_toDate = value.toDate) == null ? void 0 : _value_toDate.call(value);
+    if (converted instanceof Date) return converted;
+    return value instanceof Date ? value : null;
+}
+/**
+ * Write one audit row, collapsing an immediate repeat of the same act onto
+ * the row already there.
+ *
+ * The candidate is the MOST RECENT row on the same target, which the live
+ * `target ASC, at DESC` index already answers — so this costs one indexed
+ * single-document read and needs no index of its own. Anything else landing
+ * on that target in between ends the run, which is the conservative
+ * direction: an interleaved act means the two views were not one action.
+ *
+ * The read and the write are one TRANSACTION because the duplicates this
+ * exists to catch are CONCURRENT. Two requests from one click race each
+ * other; a plain read-then-write would let both see "nothing recent" and
+ * both insert, defeating the collapse exactly when it is needed.
+ */ export async function recordAdminAudit(entry) {
+    const firestore = firebaseAdmin.app().firestore();
+    const collection = firestore.collection(ADMIN_AUDIT_COLLECTION);
+    const now = new Date();
+    const mostRecentOnTarget = collection.where('target', '==', entry.target).orderBy('at', 'desc').limit(1);
+    await firestore.runTransaction(async (transaction)=>{
+        var _toDate, _entry_note;
+        const previous = (await transaction.get(mostRecentOnTarget)).docs[0];
+        const previousAt = previous ? (_toDate = toDate(previous.get('lastAt'))) != null ? _toDate : toDate(previous.get('at')) : null;
+        const sameAct = !!previous && previous.get('actorUid') === entry.actorUid && previous.get('action') === entry.action;
+        /*
+     * Absolute distance, because the rows this compares against are not all
+     * written with the same clock: most writers use a server timestamp and
+     * this one uses the request's own instant, so a neighboring row can
+     * carry a moment slightly ahead of `now`. A signed comparison would read
+     * that as "not recent" and stop collapsing.
+     */ const withinWindow = !!previousAt && Math.abs(now.getTime() - previousAt.getTime()) <= ADMIN_AUDIT_DEDUPE_WINDOW_MS;
+        if (previous && sameAct && withinWindow) {
+            transaction.update(previous.ref, {
+                repeatCount: (Number(previous.get('repeatCount')) || 1) + 1,
+                lastAt: now
+            });
+            return;
+        }
+        transaction.create(collection.doc(), _extends({
+            actorUid: entry.actorUid,
+            action: entry.action,
+            target: entry.target
+        }, entry.subjectUid ? {
+            subjectUid: entry.subjectUid
+        } : {}, entry.subjectAddressKey ? {
+            subjectAddressKey: entry.subjectAddressKey
+        } : {}, {
+            note: (_entry_note = entry.note) != null ? _entry_note : null,
+            at: now,
+            /*
+       * `lastAt` and `repeatCount` are set on the FIRST write, not added on
+       * the first repeat. A reader that has to treat a missing field as "one,
+       * at `at`" will eventually forget to, and the row it gets wrong is the
+       * row that says how often somebody looked.
+       */ lastAt: now,
+            repeatCount: 1
+        }));
+    });
+}
+/**
+ * An address a human can recognize without the log holding the address.
+ *
+ * `emailDeliveries` is keyed by `sha256(address)` precisely so we do not keep
+ * a readable list of who we mail. An audit row echoing the address in the
+ * clear made this collection the less careful of the two for the same data,
+ * and `adminAudit` is readable by any staff role.
+ *
+ * The first character and the domain survive because an audit entry a human
+ * cannot read is a weaker control: a staffer checking their own access, or an
+ * investigator confirming which of a shortlist was opened, needs to recognize
+ * the row. What does not survive is the harvestable part — a dump of this
+ * collection yields no mailing list.
+ */ export function maskEmailAddress(address) {
+    const trimmed = String(address != null ? address : '').trim();
+    const at = trimmed.lastIndexOf('@');
+    if (at <= 0 || at === trimmed.length - 1) return '***';
+    return `${trimmed.slice(0, 1)}***@${trimmed.slice(at + 1)}`;
+}
+/** Every recipient, masked, in one note-sized string. */ export function maskEmailAddresses(addresses) {
+    return (addresses != null ? addresses : []).map(maskEmailAddress).join(', ');
+}
+/**
+ * The uid behind a recipient address, or null when there is not one.
+ *
+ * Across POOLS, not the project pool alone: an enterprise account signing in
+ * through GCIP lives in a tenant, and a project-pool `getUserByEmail` would
+ * report the customer most in need of this record as "not a user".
+ *
+ * Null is a real answer. Most addresses we send to belong to site members,
+ * prospects and plain contacts with no platform account, and this must never
+ * guess one for them.
+ */ export async function resolveSubjectUidByEmail(address) {
+    const email = String(address != null ? address : '').trim();
+    if (!email) return null;
+    try {
+        /*
+     * AMBIGUITY RESOLVES TO NOBODY.
+     *
+     * This was `findUserByEmailAcrossPools(...).uid` — the first account
+     * whose PRIMARY matched. That is a guess whenever a second account holds
+     * the same address, which is a real shape: a federated provider's address
+     * never entered the uniqueness index, so an account can hold one that is
+     * also somebody else's primary with nothing recording the clash.
+     *
+     * `attributableAccountForAddress` returns null for "more than one" as
+     * well as for "nobody". Both are the same instruction to this writer:
+     * name no subject. A row naming the wrong customer is not a weaker answer
+     * to "who read my data" — it is a false one, and it puts one customer's
+     * name on another's data access.
+     *
+     * The access is still reachable: `subjectAddressKey` carries the hashed
+     * recipient, and the account page finds it from the addresses it holds.
+     */ return await attributableAccountForAddress(email);
+    } catch (unused) {
+        // A lookup that could not run leaves the row without a subject, which is
+        // the same answer as "no account" and is safe: it under-reports rather
+        // than attributing an access to the wrong person.
+        return null;
+    }
+}
+/**
+ * The hashed recipient for {@link AdminAuditWrite.subjectAddressKey}.
+ *
+ * The FIRST recipient, matching `resolveSubjectUidForRecipients` — one scalar
+ * cannot represent a multi-recipient message, and the masked note carries the
+ * full list either way.
+ */ export function subjectAddressKeyForRecipients(addresses) {
+    for (const address of addresses != null ? addresses : []){
+        const key = emailSuppressionKey(address);
+        if (key) return key;
+    }
+    return null;
+}
+/**
+ * The first recipient with a platform account.
+ *
+ * A single scalar subject cannot represent a message sent to several people,
+ * and multi-recipient system mail is rare enough that an array field plus its
+ * own `array-contains` index would be carried by every writer to serve almost
+ * no rows. The full (masked) recipient list stays on the note, so a row for a
+ * multi-recipient message still shows that the others were involved.
+ */ export async function resolveSubjectUidForRecipients(addresses) {
+    for (const address of addresses != null ? addresses : []){
+        const uid = await resolveSubjectUidByEmail(address);
+        if (uid) return uid;
+    }
+    return null;
+}
+
+//# sourceMappingURL=admin-audit.js.map

package/src/lib/server/admin-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/admin-audit.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 { isPluginStaffAuditAccess } from '@aglyn/aglyn/plugin-manager/plugin-activity-actions'\nimport { attributableAccountForAddress } from './account-addresses'\nimport { emailSuppressionKey } from './email-suppression'\nimport { firebaseAdmin } from './firebase-admin'\n\n/**\n * THE STAFF AUDIT TRAIL: WHO A ROW IS ABOUT, AND HOW MANY TIMES IT HAPPENED.\n *\n * `adminAudit` is not a convenience log. Firestore rules close\n * `emailDeliveries` to EVERYONE, staff included, and the console route is\n * allowed to read it only because it establishes a staff claim and records\n * who looked. The row this module writes is that compensating control, so\n * the two properties it exists to provide are:\n *\n *  1. **No access is lost.** Two views minutes apart are two accesses. A\n *     collapse that dropped one would answer \"nobody read your mail\" about a\n *     read that happened, which is the single failure this collection cannot\n *     have.\n *  2. **The subject is answerable.** `target` names the THING acted on; it\n *     cannot also name the person, because a message id is not a user path.\n *     `subjectUid` is the separate fact, and it is what makes \"who at Aglyn\n *     read my email\" a query rather than a manual trawl.\n */\n\nexport const ADMIN_AUDIT_COLLECTION = 'adminAudit'\n\n/**\n * How close together two identical acts must be to count as ONE act\n * recorded twice.\n *\n * A single click can reach this writer more than once — a re-run effect, a\n * retried request, a double submit — and each arrival is the same access.\n * Ten seconds sits an order of magnitude above that (the observed re-entry\n * was one second apart) and well below a person deliberately re-opening a\n * record (observed at fifty-three seconds). Nothing a human does twice on\n * purpose lands inside it.\n *\n * ⚠️ A collapse still RECORDS the repeat: `repeatCount` and `lastAt` carry\n * it, and the console renders both. Widening this window trades away the\n * separateness of two accesses, so it must stay far shorter than the\n * interval at which a second look is a second decision.\n */\nexport const ADMIN_AUDIT_DEDUPE_WINDOW_MS = 10_000\n\n/** Access looked at data; change altered something or acted on someone. */\nexport type AdminAuditKind = 'access' | 'change'\n\n/**\n * The actions that only LOOKED.\n *\n * An exception list, not a classification of everything, and the default\n * matters more than the membership: anything absent is a `change`. A change\n * is the louder half of the console's audit card, so an action nobody has\n * classified yet gets the MORE prominent treatment rather than the quieter\n * one. The failure mode of the opposite default is an unclassified\n * impersonation rendering as routine browsing.\n *\n * An export is deliberately NOT here. Data leaving the platform is a\n * high-consequence act even though it mutates nothing, and it belongs beside\n * the impersonations rather than beside the record views.\n */\nconst ADMIN_AUDIT_ACCESS_ACTIONS: ReadonlySet<string> = new Set([\n  'email.message-viewed',\n])\n\n/**\n * An access when the platform or a plugin declares the action a read — a\n * plugin's staff card opening on an org or an account names its own read\n * actions through its activity group (AGL-2939) — and a change otherwise.\n */\nexport function adminAuditKind(\n  action: string | null | undefined,\n): AdminAuditKind {\n  return action && (ADMIN_AUDIT_ACCESS_ACTIONS.has(action) || isPluginStaffAuditAccess(action))\n    ? 'access'\n    : 'change'\n}\n\nexport interface AdminAuditWrite {\n  /** The staff account performing the act. */\n  actorUid: string\n  action: string\n  /** The THING acted on, as a path or a stable identifier. */\n  target: string\n  /**\n   * The person the act is ABOUT, when one can be resolved.\n   *\n   * Absent is a correct answer, not a failure: a recipient may be a site\n   * member, a prospect or a bare address with no platform account behind it,\n   * and inventing a uid for one of those would put an act on an innocent\n   * person's page.\n   */\n  subjectUid?: string | null\n  /**\n   * `sha256` of the recipient address the act was about, when it had one.\n   *\n   * ## Why a hash and not the address\n   *\n   * The SAME derivation `emailSuppressionKey` uses, so this joins the\n   * delivery log without a second key space. It is hashed for the reason\n   * {@link maskEmailAddress} exists: `adminAudit` is readable by any staff\n   * role, and a dump of it must not yield a mailing list.\n   *\n   * ## Why it exists at all, next to `subjectUid`\n   *\n   * `subjectUid` can only be written when the address resolves to exactly one\n   * account, and an address is not reliably resolvable to one — a\n   * provider-supplied address may be held by a second account with nothing\n   * recording it. So the subject is now OMITTED whenever the answer is\n   * ambiguous, and omitting it alone would make the access invisible on every\n   * page, which is worse than the guess it replaced.\n   *\n   * This is the fact that needs no guess. The account page queries it with\n   * the keys of every address that account holds, so one access appears on\n   * the page of each account holding the address — which is the honest answer\n   * when the mail went to a mailbox rather than to a uid.\n   *\n   * ## It opens no tier side-door\n   *\n   * `adminAudit` is `allow read, create: if isStaff()` with NO tier gate, so\n   * anything written here is readable by every staff session whatever its\n   * role — which makes an audit row a way around a tier restriction on the\n   * surface the value came from. Checked, and it is not one here: the writer\n   * is the message route, which gates on `staff` alone and nothing finer, so\n   * this field is no more widely readable than its source.\n   *\n   * The hash adds no reach of its own either. It is the document id\n   * `emailDeliveries` is already filed under, so any staff session that can\n   * read this row could already derive the same value from an address it\n   * guessed. A field whose source DID restrict by tier would not belong here.\n   */\n  subjectAddressKey?: string | null\n  /** Human-readable context. ⚠️ Never a raw address — see `maskEmailAddress`. */\n  note?: string | null\n}\n\nfunction toDate(value: unknown): Date | null {\n  const converted = (value as { toDate?: () => Date } | null)?.toDate?.()\n  if (converted instanceof Date) return converted\n  return value instanceof Date ? value : null\n}\n\n/**\n * Write one audit row, collapsing an immediate repeat of the same act onto\n * the row already there.\n *\n * The candidate is the MOST RECENT row on the same target, which the live\n * `target ASC, at DESC` index already answers — so this costs one indexed\n * single-document read and needs no index of its own. Anything else landing\n * on that target in between ends the run, which is the conservative\n * direction: an interleaved act means the two views were not one action.\n *\n * The read and the write are one TRANSACTION because the duplicates this\n * exists to catch are CONCURRENT. Two requests from one click race each\n * other; a plain read-then-write would let both see \"nothing recent\" and\n * both insert, defeating the collapse exactly when it is needed.\n */\nexport async function recordAdminAudit(entry: AdminAuditWrite): Promise<void> {\n  const firestore = firebaseAdmin.app().firestore()\n  const collection = firestore.collection(ADMIN_AUDIT_COLLECTION)\n  const now = new Date()\n  const mostRecentOnTarget = collection\n    .where('target', '==', entry.target)\n    .orderBy('at', 'desc')\n    .limit(1)\n\n  await firestore.runTransaction(async (transaction) => {\n    const previous = (await transaction.get(mostRecentOnTarget)).docs[0]\n    const previousAt = previous\n      ? (toDate(previous.get('lastAt')) ?? toDate(previous.get('at')))\n      : null\n    const sameAct =\n      !!previous &&\n      previous.get('actorUid') === entry.actorUid &&\n      previous.get('action') === entry.action\n    /*\n     * Absolute distance, because the rows this compares against are not all\n     * written with the same clock: most writers use a server timestamp and\n     * this one uses the request's own instant, so a neighboring row can\n     * carry a moment slightly ahead of `now`. A signed comparison would read\n     * that as \"not recent\" and stop collapsing.\n     */\n    const withinWindow =\n      !!previousAt &&\n      Math.abs(now.getTime() - previousAt.getTime()) <=\n        ADMIN_AUDIT_DEDUPE_WINDOW_MS\n\n    if (previous && sameAct && withinWindow) {\n      transaction.update(previous.ref, {\n        repeatCount: (Number(previous.get('repeatCount')) || 1) + 1,\n        lastAt: now,\n      })\n      return\n    }\n\n    transaction.create(collection.doc(), {\n      actorUid: entry.actorUid,\n      action: entry.action,\n      target: entry.target,\n      /*\n       * OMITTED rather than null when there is nobody to name. The subject\n       * query is `where('subjectUid','==',uid).orderBy('at','desc')`, which\n       * matches only documents that HAVE the field — so leaving it out keeps\n       * the index to the rows that can actually answer a subject question.\n       */\n      ...(entry.subjectUid ? { subjectUid: entry.subjectUid } : {}),\n      // Omitted rather than null on the same reasoning as `subjectUid`: the\n      // address query matches only documents that HAVE the field.\n      ...(entry.subjectAddressKey\n        ? { subjectAddressKey: entry.subjectAddressKey }\n        : {}),\n      note: entry.note ?? null,\n      at: now,\n      /*\n       * `lastAt` and `repeatCount` are set on the FIRST write, not added on\n       * the first repeat. A reader that has to treat a missing field as \"one,\n       * at `at`\" will eventually forget to, and the row it gets wrong is the\n       * row that says how often somebody looked.\n       */\n      lastAt: now,\n      repeatCount: 1,\n    })\n  })\n}\n\n/**\n * An address a human can recognize without the log holding the address.\n *\n * `emailDeliveries` is keyed by `sha256(address)` precisely so we do not keep\n * a readable list of who we mail. An audit row echoing the address in the\n * clear made this collection the less careful of the two for the same data,\n * and `adminAudit` is readable by any staff role.\n *\n * The first character and the domain survive because an audit entry a human\n * cannot read is a weaker control: a staffer checking their own access, or an\n * investigator confirming which of a shortlist was opened, needs to recognize\n * the row. What does not survive is the harvestable part — a dump of this\n * collection yields no mailing list.\n */\nexport function maskEmailAddress(address: string | null | undefined): string {\n  const trimmed = String(address ?? '').trim()\n  const at = trimmed.lastIndexOf('@')\n  if (at <= 0 || at === trimmed.length - 1) return '***'\n  return `${trimmed.slice(0, 1)}***@${trimmed.slice(at + 1)}`\n}\n\n/** Every recipient, masked, in one note-sized string. */\nexport function maskEmailAddresses(\n  addresses: readonly string[] | null | undefined,\n): string {\n  return (addresses ?? []).map(maskEmailAddress).join(', ')\n}\n\n/**\n * The uid behind a recipient address, or null when there is not one.\n *\n * Across POOLS, not the project pool alone: an enterprise account signing in\n * through GCIP lives in a tenant, and a project-pool `getUserByEmail` would\n * report the customer most in need of this record as \"not a user\".\n *\n * Null is a real answer. Most addresses we send to belong to site members,\n * prospects and plain contacts with no platform account, and this must never\n * guess one for them.\n */\nexport async function resolveSubjectUidByEmail(\n  address: string | null | undefined,\n): Promise<string | null> {\n  const email = String(address ?? '').trim()\n  if (!email) return null\n  try {\n    /*\n     * AMBIGUITY RESOLVES TO NOBODY.\n     *\n     * This was `findUserByEmailAcrossPools(...).uid` — the first account\n     * whose PRIMARY matched. That is a guess whenever a second account holds\n     * the same address, which is a real shape: a federated provider's address\n     * never entered the uniqueness index, so an account can hold one that is\n     * also somebody else's primary with nothing recording the clash.\n     *\n     * `attributableAccountForAddress` returns null for \"more than one\" as\n     * well as for \"nobody\". Both are the same instruction to this writer:\n     * name no subject. A row naming the wrong customer is not a weaker answer\n     * to \"who read my data\" — it is a false one, and it puts one customer's\n     * name on another's data access.\n     *\n     * The access is still reachable: `subjectAddressKey` carries the hashed\n     * recipient, and the account page finds it from the addresses it holds.\n     */\n    return await attributableAccountForAddress(email)\n  } catch {\n    // A lookup that could not run leaves the row without a subject, which is\n    // the same answer as \"no account\" and is safe: it under-reports rather\n    // than attributing an access to the wrong person.\n    return null\n  }\n}\n\n/**\n * The hashed recipient for {@link AdminAuditWrite.subjectAddressKey}.\n *\n * The FIRST recipient, matching `resolveSubjectUidForRecipients` — one scalar\n * cannot represent a multi-recipient message, and the masked note carries the\n * full list either way.\n */\nexport function subjectAddressKeyForRecipients(\n  addresses: readonly string[] | null | undefined,\n): string | null {\n  for (const address of addresses ?? []) {\n    const key = emailSuppressionKey(address)\n    if (key) return key\n  }\n  return null\n}\n\n/**\n * The first recipient with a platform account.\n *\n * A single scalar subject cannot represent a message sent to several people,\n * and multi-recipient system mail is rare enough that an array field plus its\n * own `array-contains` index would be carried by every writer to serve almost\n * no rows. The full (masked) recipient list stays on the note, so a row for a\n * multi-recipient message still shows that the others were involved.\n */\nexport async function resolveSubjectUidForRecipients(\n  addresses: readonly string[] | null | undefined,\n): Promise<string | null> {\n  for (const address of addresses ?? []) {\n    const uid = await resolveSubjectUidByEmail(address)\n    if (uid) return uid\n  }\n  return null\n}\n"],"names":["isPluginStaffAuditAccess","attributableAccountForAddress","emailSuppressionKey","firebaseAdmin","ADMIN_AUDIT_COLLECTION","ADMIN_AUDIT_DEDUPE_WINDOW_MS","ADMIN_AUDIT_ACCESS_ACTIONS","Set","adminAuditKind","action","has","toDate","value","converted","Date","recordAdminAudit","entry","firestore","app","collection","now","mostRecentOnTarget","where","target","orderBy","limit","runTransaction","transaction","previous","get","docs","previousAt","sameAct","actorUid","withinWindow","Math","abs","getTime","update","ref","repeatCount","Number","lastAt","create","doc","subjectUid","subjectAddressKey","note","at","maskEmailAddress","address","trimmed","String","trim","lastIndexOf","length","slice","maskEmailAddresses","addresses","map","join","resolveSubjectUidByEmail","email","subjectAddressKeyForRecipients","key","resolveSubjectUidForRecipients","uid"],"mappings":"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"}

package/src/lib/server/analytics-retention.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @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.
+ */
+/**
+ * Retention for the AGL-82 analytics day docs (AGL-1844).
+ *
+ * Day docs accumulated forever: every pageview, media serve and redirect hit
+ * left a `{hosts|orgs}/{id}/analytics/{YYYY-MM-DD}` (or
+ * `hosts/{id}/screenAnalytics/{screenId}:{day}`) document behind, and
+ * nothing ever deleted one. Every WRITER now stamps `expiresAt`, and a
+ * Firestore TTL policy on that field (declared as `fieldOverrides` in
+ * `cloud/firebase-firestore.indexes.json`, on the `analytics` and
+ * `screenAnalytics` collection groups) sweeps the old ones.
+ *
+ * ## Why 400 days
+ *
+ * Long enough that every reader's window closes with room to spare:
+ *
+ * - the console's widest range is 90 days;
+ * - /api/billing/report-usage meters `analytics/{day}.total` for the CURRENT
+ *   period — an invoice dispute a year later still finds its days;
+ * - a year-over-year comparison (no surface does one yet) would still have
+ *   both years.
+ *
+ * Short enough that storage is bounded: ~400 docs per host (plus per-screen
+ * and per-org docs) at steady state, instead of unbounded growth.
+ *
+ * ## Why TTL and NOT monthly rollups (the AGL-1844 decision)
+ *
+ * Rollups were considered and deliberately not built: no console surface
+ * reads more than 90 dailies (bounded, and blunted by the AGL-1440 cache),
+ * so a monthly doc would be written by a scheduled job — new moving part,
+ * new failure mode — to serve a view nothing renders. If a >90-day console
+ * range ever ships, rollups become that feature's first commit.
+ *
+ * TTL deletion is Firestore's own sweeper: typically within 24h of expiry,
+ * no code of ours runs. Docs written BEFORE this shipped carry no
+ * `expiresAt` and are never swept — the trickle of writes to a live site
+ * stamps its recent days naturally, and old unstamped days are exactly the
+ * ones nothing reads.
+ */
+/** See the module doc for why 400. */
+export declare const ANALYTICS_DAY_RETENTION_DAYS = 400;
+/**
+ * When the day doc named `day` (YYYY-MM-DD, UTC) may be swept. Anchored on
+ * the day itself, not the write clock, so every write to one doc agrees on
+ * one expiry. An unparsable day anchors on "now", which only ever shortens
+ * retention.
+ */
+export declare function analyticsDayExpiresAt(day: string): Date;