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

package/src/lib/server/auth-pools.d.ts

@@ -0,0 +1,246 @@
+/**
+ * @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.
+ */
+/**
+ * Cross-pool Firebase Auth lookups (AGL-1122).
+ *
+ * Enterprise SSO (AGL-1101) signs users into a per-org **GCIP tenant**, and a
+ * tenant has its OWN user pool. A project-level `getUserByEmail` /
+ * `listUsers` does not see those users at all — measured on aglyn-main:
+ * the owner of aglyn-org returned `auth/user-not-found` at project level and
+ * was present only under tenant `aglyn-org-y5v14`.
+ *
+ * That silently broke five separate things: staff could not find, view,
+ * disable or grant staff to an SSO user; adding one to an org or a site by
+ * email 404'd into "send them an invite" for an account that already exists;
+ * and `notifyStaff` skipped SSO staff entirely. Fixing those one route at a
+ * time would guarantee the next new route reintroduces the bug, so every
+ * caller goes through here instead.
+ *
+ * Custom claims are per-pool too: `setCustomUserClaims` on the project pool
+ * cannot grant staff to a tenant user. `authForPool` hands back the right
+ * `BaseAuth` so a mutation lands in the pool the user actually lives in.
+ */
+import type { BaseAuth, UserRecord } from 'firebase-admin/auth';
+/** A user plus the pool they were found in (`null` = the project pool). */
+export interface PooledUserRecord {
+    record: UserRecord;
+    /** GCIP tenant id, or null when the user is in the project-level pool. */
+    tenantId: string | null;
+    /**
+     * Other pools that ALSO hold this uid (AGL-1962). Normally absent: a uid is
+     * unique within a pool, and the pools are meant to hold different people.
+     *
+     * It is populated when the same uid turns up in more than one pool, which
+     * means something minted a custom token for one pool's uid against another
+     * pool — `signInWithCustomToken` CREATES the account when the uid is absent,
+     * so the mistake manufactures an empty shadow account rather than failing.
+     * Measured on production: `QQ7fixtureUid0000000000000001` existed in both the
+     * project pool and `aglyn-org-y5v14`, the project copy created by
+     * `/api/presence/token` minting an SSO user's tenant uid at project level.
+     *
+     * This is the marker, not a deletion: `listUsersAcrossPools` still returns
+     * every record, and `collapseCrossPoolUidRows` — which is what a display
+     * uses — keeps this field on the row it keeps, so a collision is still
+     * legible after the rows are merged (AGL-2005).
+     */
+    uidAlsoInPools?: (string | null)[];
+}
+/**
+ * Does this record show that a human ever authenticated as it? (AGL-2005)
+ *
+ * An address or a provider entry is the evidence. `signInWithCustomToken`
+ * mints an account out of nothing when the uid is absent from the pool the
+ * token was minted in, and the record it manufactures has neither: measured
+ * on production, a project-pool twin of a tenant uid had `email: null` and
+ * `providerData: []` while the real SSO record carried both an address and
+ * `saml.aglyn-workspace`.
+ *
+ * `displayName` and custom claims deliberately do NOT count. Both can be
+ * written onto any record after the fact — `updateProfile` and `grantStaff`
+ * in the staff console do exactly that — so a shadow that a staff action had
+ * already landed on would start qualifying as an identity and go on winning
+ * the lookups it should be losing. The bar has to be a signal the forgery
+ * cannot acquire by being acted upon.
+ */
+export declare function isIdentifiedUserRecord(record: UserRecord): boolean;
+/**
+ * How strongly a record identifies its human, for choosing between two that
+ * share a uid (AGL-2005). Ordering only — the numbers have no other meaning.
+ *
+ * Email and provider data lead because they are what `isIdentifiedUserRecord`
+ * trusts; the rest break ties between records that both qualify.
+ */
+export declare function identityStrength(record: UserRecord): number;
+/**
+ * Collapse rows sharing a uid to ONE row apiece (AGL-2005).
+ *
+ * **decided:** "We still have two users list in this list with the
+ * same uid but one without an email attached, this needs fixed we should only
+ * see one user, even if they are sso."
+ *
+ * AGL-1962 deliberately refused to merge, on the grounds that collapsing two
+ * accounts could hide an identity split. That reasoning still stands for two
+ * DISTINCT accounts — which is why this keys on **uid** and never on email.
+ * Two people who happen to share an address are two accounts with two uids
+ * and stay two rows; merging them on email would delete a real user from the
+ * staff console, a worse bug than the one being fixed and an invisible one.
+ *
+ * A repeated uid is different in kind: a uid is unique WITHIN a pool, so the
+ * same uid in two pools is not two people, it is one person plus an artifact
+ * of a cross-pool custom-token mint. Those merge.
+ *
+ * Two rules make the merge safe:
+ *
+ *  - **The identified record wins.** Ranked by `identityStrength`, so an
+ *    emailless, providerless artifact can never be the row staff see — the
+ *    exact inversion that let the shadow win every uid lookup.
+ *  - **The collision is not discarded.** `markCrossPoolUidCollisions` runs
+ *    here rather than being left to the caller, so the surviving row always
+ *    carries `uidAlsoInPools` naming the pools that were folded into it. One
+ *    row, and it still says it was two.
+ *
+ * The survivor takes the FIRST occurrence's position so list ordering does
+ * not shuffle, and ties keep the earlier row so the result is deterministic.
+ */
+export declare function collapseCrossPoolUidRows(users: PooledUserRecord[]): PooledUserRecord[];
+/**
+ * Flag every uid that appears in more than one pool, in place of hiding it.
+ *
+ * Pure and total, so a spec can drive it without Firebase. Callers must pass
+ * the rows they intend to show together — a collision it cannot see is one
+ * it cannot report.
+ */
+export declare function markCrossPoolUidCollisions(users: PooledUserRecord[]): PooledUserRecord[];
+export declare function listAuthTenantIds(): Promise<string[]>;
+/** Test seam — drops the tenant cache so a spec can vary the tenant set. */
+export declare function resetAuthTenantCache(): void;
+/** The `BaseAuth` for a pool: the project pool for null, else the tenant's. */
+export declare function authForPool(tenantId: string | null | undefined): BaseAuth;
+/**
+ * Find a user by email across the project pool and every GCIP tenant.
+ *
+ * The project pool is tried first — it holds every non-SSO user, which is
+ * almost all of them, so the common case stays a single call. Returns null
+ * when no pool has the address, which is the only honest answer for "this
+ * person has no Aglyn account".
+ */
+export declare function findUserByEmailAcrossPools(email: string): Promise<PooledUserRecord | null>;
+/**
+ * Find a user by uid across the project pool and every GCIP tenant. Same
+ * shape as the email lookup — a uid is only unique WITHIN a pool, so the
+ * caller needs to know which pool answered before it mutates anything.
+ *
+ * **First pool to answer is NOT good enough** (AGL-2005). This used to return
+ * the project pool's record the moment it existed, which is how a forged
+ * emailless twin won every uid lookup for a real SSO user: `grantStaff`,
+ * `disable`, `setRole`, `updateProfile`, `revokeRefreshTokens`, impersonate,
+ * usage-email, resolve-people, org-lockdown and erasure all landed on a
+ * record nobody can sign in as. Two of those were caught having happened —
+ * a `revokeRefreshTokens` dated 2026-08-14 sat on the twin while the real
+ * account's `tokensValidAfterTime` never moved, so "sign out everywhere" did
+ * nothing at all.
+ *
+ * So a pool's answer is accepted only when the record it returns actually
+ * identifies someone, and the winner is chosen by the SAME rule the staff
+ * list collapses rows with. That equivalence is the point: the row staff
+ * click is the record the action mutates, by construction rather than by
+ * coincidence.
+ *
+ * The fast path survives intact — a project account with an address or a
+ * provider is returned without any tenant call, which is nearly every
+ * account. Only a record carrying no identity at all pays for the sweep.
+ */
+export declare function findUserByUidAcrossPools(uid: string): Promise<PooledUserRecord | null>;
+export interface PooledUserPage {
+    users: PooledUserRecord[];
+    /** Project-pool cursor; null when the project pool is exhausted. */
+    nextPageToken: string | null;
+    /**
+     * True once the project pool is exhausted and the tenant users have been
+     * appended. Tenant pools are NOT paginated here — enterprise SSO pools are
+     * small, and silently dropping their tail would recreate exactly the
+     * invisibility this module exists to fix. `tenantTruncated` says when that
+     * assumption stopped holding rather than letting it fail quietly.
+     */
+    tenantsIncluded: boolean;
+    /** Tenants whose users hit the cap and were cut short. */
+    tenantTruncated: string[];
+}
+/**
+ * One page of users across every pool: the project pool paginates as before,
+ * and tenant users are appended on the LAST page so they can never be lost
+ * between cursors. Callers render `tenantId` so an SSO account is
+ * recognisable — it is not editable the same way a project user is.
+ */
+export declare function listUsersAcrossPools(pageSize: number, pageToken?: string): Promise<PooledUserPage>;
+/**
+ * Every account across every pool, up to a cap — the only way to FILTER them.
+ *
+ * Firebase Auth's `listUsers` takes a page size and a cursor and nothing else:
+ * no predicate, no ordering, no search. So a staff filter on anything but an
+ * exact email, uid or phone number (which have their own O(1) lookups) can
+ * only be answered by reading the accounts and matching them.
+ *
+ * That is an expensive read, so it happens on an ASK and never on a mount —
+ * the route calls this only when a request carries a filter, and pages the
+ * cheap way otherwise.
+ *
+ * `truncated` is true when the cap was reached, and it must be shown rather
+ * than swallowed: a staff list that searched part of the directory and said
+ * "no matches" is worse than one that admits where it stopped.
+ */
+export declare function scanUsersAcrossPools(cap: number): Promise<{
+    users: PooledUserRecord[];
+    truncated: boolean;
+    tenantTruncated: string[];
+}>;
+/** Where a claim mutation landed, so a caller can audit the POOL as well. */
+export interface StaffClaimWrite {
+    uid: string;
+    /** The pool the claim was written to; null = the project pool. */
+    tenantId: string | null;
+    email: string | null;
+    claims: Record<string, unknown>;
+}
+/**
+ * Write custom claims to the pool the uid ACTUALLY lives in (AGL-1993).
+ *
+ * The hazard this exists to remove: `setCustomUserClaims` is per-pool, and a
+ * grant aimed at the wrong pool does not error — on the project pool it
+ * either throws `user-not-found` (loud, fine) or, when a phantom shadow record
+ * shares the uid, silently succeeds against the WRONG record. That is not
+ * hypothetical: on 2026-08-18 a staff account's uid existed in both the
+ * project pool and `aglyn-org-y5v14` at once. That phantom won every lookup
+ * until AGL-2005 made {@link findUserByUidAcrossPools} rank an IDENTIFIED
+ * record above an unidentified one rather than taking the first pool to
+ * answer.
+ *
+ * So resolution and mutation are bound together here rather than left to each
+ * caller to pair correctly, and the resolved pool is RETURNED so the audit row
+ * can record which pool was written — "granted staff to uid X" is not a
+ * complete record when a uid can name two accounts.
+ *
+ * Never assumes a pool. Staff may live in the project pool, in Aglyn's own
+ * tenant, or in a CUSTOMER org's tenant, and hard-coding any of them would
+ * silently fail the moment a third exists.
+ */
+export declare function setClaimsInOwningPool(uid: string, claims: Record<string, unknown>): Promise<StaffClaimWrite | null>;
+/**
+ * Every uid carrying the `staff` claim, across all pools. Staff is a custom
+ * claim, which is not queryable, so this scans — the caller caches it.
+ */
+export declare function listStaffUidsAcrossPools(): Promise<string[]>;