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

package/src/lib/server/token-revocation.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @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.
+ */
+/**
+ * ID-token revocation on every server door (AGL-1881).
+ *
+ * ## The gap this closes
+ *
+ * `verifyIdToken(token)` checks a signature and an expiry. It does not ask
+ * whether the account was locked, disabled, deleted, de-staffed or signed out
+ * five seconds ago — that costs a round trip, so the SDK makes it opt-in via
+ * `checkRevoked`. The pre-launch audit found the flag set on 3 of 175 call
+ * sites: the session MINT, the session EXCHANGE and the device-revoke route.
+ * Everything else — 117 console API routes, plus the marketplace, commerce and
+ * bookings plugin servers — took a bare `verifyIdToken`.
+ *
+ * So `revokeRefreshTokens(uid)` stopped the browser getting a NEW token and
+ * did nothing about the one it already held. After a panic user-lock, a staff
+ * password reset, an SSO offboard, an org-wide lockdown or a "sign out
+ * everywhere", the revoked token kept opening every one of those doors for the
+ * remainder of its hour. `device-revocation.ts` meanwhile promised the effect
+ * was "immediate for everything that goes through our server", which was the
+ * defect worth fixing: the sentence was shipped and it was not true.
+ *
+ * ## Why it is a cached epoch and not just `checkRevoked: true`
+ *
+ * `checkRevoked` costs one `accounts:lookup` per verification. Measured
+ * against production `aglyn-main` (n=40): p50 95.5ms, p95 144ms — statistically
+ * indistinguishable from the p50 85.8ms single Firestore `doc().get()` that
+ * every one of these routes already performs, on the same connection from the
+ * same machine. So the round trip is not expensive; it is just paid too often.
+ * Turned on unconditionally it would multiply Identity Toolkit calls by the
+ * whole console request volume, against a project quota, to re-answer a
+ * question whose answer changes maybe twice a year per account.
+ *
+ * The answer is therefore CACHED, on exactly the terms AGL-1522 already set
+ * for the panic path: `PLATFORM_TTL_MS`, 15 seconds, LRU-bounded, with the
+ * acting process invalidating the uid after its own write. Steady state costs
+ * nothing; a cold entry costs one Firestore-read-equivalent; the honest window
+ * goes from ~3600s to ≤15s, and to zero on the process that did the revoking.
+ * A revocation control whose staleness bound matches the lockdown control it
+ * sits beside is one bound to explain, not two.
+ *
+ * ## What is checked, and in which pool
+ *
+ * Three refusals, mirroring firebase-admin's own `checkRevoked` so the error
+ * codes route handlers already catch keep working unchanged:
+ *
+ *  - `tokensValidAfterTime` after the token's `auth_time` → `id-token-revoked`
+ *  - `disabled` → `user-disabled` (a user-scope panic lock sets this, and it
+ *    is the half that does not depend on clock agreement)
+ *  - the record is GONE → `id-token-revoked` (a deleted account is not a
+ *    signed-in one; the SDK's own check treats this as revoked too)
+ *
+ * The lookup is asked of the auth instance the token was verified with, which
+ * is the AGL-2005 rule made structural rather than remembered: a tenant-aware
+ * auth asks the tenant pool, and a project-pool lookup for an SSO uid — which
+ * would answer "never revoked" about a forged twin — cannot be spelled.
+ *
+ * ## Failure direction
+ *
+ * An unreachable Identity Toolkit is an outage, not a revocation, and refusing
+ * every request in the console during one would be a self-inflicted lockdown.
+ * So a transport failure fails OPEN — and is NOT cached, or a single blip
+ * would blind the check for a full TTL. `user-not-found` is not a transport
+ * failure and fails closed. This is the opposite direction from
+ * `deviceRevocationRefuses`, which refuses an undateable credential, and the
+ * split is deliberate: "we could not reach the service" and "the service told
+ * us this account is gone" are different answers.
+ */
+import type { BaseAuth, DecodedIdToken } from 'firebase-admin/auth';
+/**
+ * Matches `PLATFORM_TTL_MS` in `lockdown.ts`, and deliberately so — see the
+ * module note. One number for how stale a panic action may read.
+ */
+export declare const TOKEN_REVOCATION_TTL_MS = 15000;
+/**
+ * Bounded so a scan of uids cannot balloon a warm serverless process. Past
+ * this many entries the least-recently-USED is evicted; a cache hit refreshes
+ * recency, so an active session is not what a scan pushes out. Same bound and
+ * same reasoning as `USER_LOCKDOWN_CACHE_MAX`.
+ */
+export declare const TOKEN_REVOCATION_CACHE_MAX = 5000;
+/** Thrown for a token the account has invalidated. Code matches the SDK's. */
+export declare class IdTokenRevokedError extends Error {
+    readonly code = "auth/id-token-revoked";
+    constructor(message?: string);
+}
+/** Thrown for a token whose account is disabled. Code matches the SDK's. */
+export declare class UserDisabledError extends Error {
+    readonly code = "auth/user-disabled";
+    constructor(message?: string);
+}
+/**
+ * Drop one account's cached verdict — called by every path that revokes, so
+ * the process that took the action refuses on its very next request instead
+ * of waiting out its own TTL. Called bare, clears everything.
+ */
+export declare function invalidateTokenRevocationCache(uid?: string, tenantId?: string | null): void;
+/** Full reset, for specs. Production code wants the per-uid form above. */
+export declare function resetTokenRevocationCache(): void;
+/**
+ * Does this account's revocation epoch refuse this token?
+ *
+ * Both sides are floored to whole seconds before comparing.
+ * `tokensValidAfterTime` is an RFC-1123 string with second granularity and
+ * `auth_time` is a whole second, so comparing in milliseconds would let a
+ * token minted in the same second as the revoke read as refused on one
+ * process and admitted on the next.
+ *
+ * @param decoded - the verified ID token
+ * @param validAfterMs - epoch ms from `tokensValidAfterTime`, null when never
+ *   revoked
+ */
+export declare function revocationRefuses(decoded: DecodedIdToken, validAfterMs: number | null | undefined): boolean;
+/**
+ * Throw if this verified ID token belongs to an account that has since been
+ * revoked, disabled or deleted. Resolves silently otherwise, including when
+ * the account could not be reached.
+ *
+ * @param pool - the auth handle the token was verified against; the lookup
+ *   MUST go to the same one (AGL-2005), and the parameter is named `pool`
+ *   rather than `auth` because that is the contract — `no-project-level-auth-
+ *   lookup.spec.ts` reads the receiver name and is right to
+ * @param decoded - the token firebase-admin just verified
+ */
+export declare function assertIdTokenNotRevoked(pool: Pick<BaseAuth, 'getUser'>, decoded: DecodedIdToken): Promise<void>;

package/src/lib/server/token-revocation.js

@@ -0,0 +1,255 @@
+/**
+ * @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.
+ */ /**
+ * ID-token revocation on every server door (AGL-1881).
+ *
+ * ## The gap this closes
+ *
+ * `verifyIdToken(token)` checks a signature and an expiry. It does not ask
+ * whether the account was locked, disabled, deleted, de-staffed or signed out
+ * five seconds ago — that costs a round trip, so the SDK makes it opt-in via
+ * `checkRevoked`. The pre-launch audit found the flag set on 3 of 175 call
+ * sites: the session MINT, the session EXCHANGE and the device-revoke route.
+ * Everything else — 117 console API routes, plus the marketplace, commerce and
+ * bookings plugin servers — took a bare `verifyIdToken`.
+ *
+ * So `revokeRefreshTokens(uid)` stopped the browser getting a NEW token and
+ * did nothing about the one it already held. After a panic user-lock, a staff
+ * password reset, an SSO offboard, an org-wide lockdown or a "sign out
+ * everywhere", the revoked token kept opening every one of those doors for the
+ * remainder of its hour. `device-revocation.ts` meanwhile promised the effect
+ * was "immediate for everything that goes through our server", which was the
+ * defect worth fixing: the sentence was shipped and it was not true.
+ *
+ * ## Why it is a cached epoch and not just `checkRevoked: true`
+ *
+ * `checkRevoked` costs one `accounts:lookup` per verification. Measured
+ * against production `aglyn-main` (n=40): p50 95.5ms, p95 144ms — statistically
+ * indistinguishable from the p50 85.8ms single Firestore `doc().get()` that
+ * every one of these routes already performs, on the same connection from the
+ * same machine. So the round trip is not expensive; it is just paid too often.
+ * Turned on unconditionally it would multiply Identity Toolkit calls by the
+ * whole console request volume, against a project quota, to re-answer a
+ * question whose answer changes maybe twice a year per account.
+ *
+ * The answer is therefore CACHED, on exactly the terms AGL-1522 already set
+ * for the panic path: `PLATFORM_TTL_MS`, 15 seconds, LRU-bounded, with the
+ * acting process invalidating the uid after its own write. Steady state costs
+ * nothing; a cold entry costs one Firestore-read-equivalent; the honest window
+ * goes from ~3600s to ≤15s, and to zero on the process that did the revoking.
+ * A revocation control whose staleness bound matches the lockdown control it
+ * sits beside is one bound to explain, not two.
+ *
+ * ## What is checked, and in which pool
+ *
+ * Three refusals, mirroring firebase-admin's own `checkRevoked` so the error
+ * codes route handlers already catch keep working unchanged:
+ *
+ *  - `tokensValidAfterTime` after the token's `auth_time` → `id-token-revoked`
+ *  - `disabled` → `user-disabled` (a user-scope panic lock sets this, and it
+ *    is the half that does not depend on clock agreement)
+ *  - the record is GONE → `id-token-revoked` (a deleted account is not a
+ *    signed-in one; the SDK's own check treats this as revoked too)
+ *
+ * The lookup is asked of the auth instance the token was verified with, which
+ * is the AGL-2005 rule made structural rather than remembered: a tenant-aware
+ * auth asks the tenant pool, and a project-pool lookup for an SSO uid — which
+ * would answer "never revoked" about a forged twin — cannot be spelled.
+ *
+ * ## Failure direction
+ *
+ * An unreachable Identity Toolkit is an outage, not a revocation, and refusing
+ * every request in the console during one would be a self-inflicted lockdown.
+ * So a transport failure fails OPEN — and is NOT cached, or a single blip
+ * would blind the check for a full TTL. `user-not-found` is not a transport
+ * failure and fails closed. This is the opposite direction from
+ * `deviceRevocationRefuses`, which refuses an undateable credential, and the
+ * split is deliberate: "we could not reach the service" and "the service told
+ * us this account is gone" are different answers.
+ */ /**
+ * Matches `PLATFORM_TTL_MS` in `lockdown.ts`, and deliberately so — see the
+ * module note. One number for how stale a panic action may read.
+ */ export const TOKEN_REVOCATION_TTL_MS = 15000;
+/**
+ * Bounded so a scan of uids cannot balloon a warm serverless process. Past
+ * this many entries the least-recently-USED is evicted; a cache hit refreshes
+ * recency, so an active session is not what a scan pushes out. Same bound and
+ * same reasoning as `USER_LOCKDOWN_CACHE_MAX`.
+ */ export const TOKEN_REVOCATION_CACHE_MAX = 5000;
+/** Thrown for a token the account has invalidated. Code matches the SDK's. */ export class IdTokenRevokedError extends Error {
+    constructor(message = 'The ID token has been revoked.'){
+        super(message), this.code = 'auth/id-token-revoked';
+        this.name = 'IdTokenRevokedError';
+    }
+}
+/** Thrown for a token whose account is disabled. Code matches the SDK's. */ export class UserDisabledError extends Error {
+    constructor(message = 'The user record is disabled.'){
+        super(message), this.code = 'auth/user-disabled';
+        this.name = 'UserDisabledError';
+    }
+}
+const cache = new Map();
+const pending = new Map();
+/**
+ * A uid is only unique WITHIN a pool (AGL-2005), so the pool is part of the
+ * key. The separator is a NUL because a tenant id cannot contain one.
+ */ function cacheKey(uid, tenantId) {
+    return `${tenantId != null ? tenantId : ''}\u0000${uid}`;
+}
+/**
+ * Drop one account's cached verdict — called by every path that revokes, so
+ * the process that took the action refuses on its very next request instead
+ * of waiting out its own TTL. Called bare, clears everything.
+ */ export function invalidateTokenRevocationCache(uid, tenantId) {
+    if (uid === undefined) {
+        cache.clear();
+        pending.clear();
+        return;
+    }
+    // A revoke reaches the account, not one pool's view of it: clear the
+    // project-pool key and the named tenant's, so a caller that does not know
+    // which pool answered still gets a fresh read.
+    for (const key of [
+        cacheKey(uid, null),
+        cacheKey(uid, tenantId)
+    ]){
+        cache.delete(key);
+        pending.delete(key);
+    }
+}
+/** Full reset, for specs. Production code wants the per-uid form above. */ export function resetTokenRevocationCache() {
+    cache.clear();
+    pending.clear();
+}
+/**
+ * Does this account's revocation epoch refuse this token?
+ *
+ * Both sides are floored to whole seconds before comparing.
+ * `tokensValidAfterTime` is an RFC-1123 string with second granularity and
+ * `auth_time` is a whole second, so comparing in milliseconds would let a
+ * token minted in the same second as the revoke read as refused on one
+ * process and admitted on the next.
+ *
+ * @param decoded - the verified ID token
+ * @param validAfterMs - epoch ms from `tokensValidAfterTime`, null when never
+ *   revoked
+ */ export function revocationRefuses(decoded, validAfterMs) {
+    var _ref, _ref1;
+    const validAfter = Number(validAfterMs != null ? validAfterMs : 0);
+    if (!Number.isFinite(validAfter) || validAfter <= 0) return false;
+    // `auth_time` moves only on a real authentication, which is what makes it
+    // the right clock: an attacker holding a stolen cookie and refresh token
+    // cannot produce a newer one. `iat` is the fallback for the handful of
+    // custom-token sign-ins that carry no `auth_time`.
+    const issuedSeconds = Number((_ref = (_ref1 = decoded == null ? void 0 : decoded.auth_time) != null ? _ref1 : decoded == null ? void 0 : decoded.iat) != null ? _ref : 0);
+    // An undateable token cannot be shown to postdate the revocation, and the
+    // safe direction for a security control is to refuse it.
+    if (!Number.isFinite(issuedSeconds) || issuedSeconds <= 0) return true;
+    return Math.floor(issuedSeconds) < Math.floor(validAfter / 1000);
+}
+/**
+ * Read (and cache) the account state behind a uid.
+ *
+ * `null` means "could not ask" — an outage, distinct from every answer the
+ * service can give, and never cached.
+ */ async function readAccountState(pool, uid, key) {
+    const cached = cache.get(key);
+    if (cached && Date.now() - cached.at < TOKEN_REVOCATION_TTL_MS) {
+        // Re-insert to refresh recency: eviction is least-recently-used, and an
+        // ACTIVE session must not be what a uid scan evicts.
+        cache.delete(key);
+        cache.set(key, cached);
+        return cached.state;
+    }
+    let inFlight = pending.get(key);
+    if (!inFlight) {
+        inFlight = (async ()=>{
+            // No initializer: every path below either assigns `state` or returns,
+            // so seeding it with `null` would be a value nothing ever reads.
+            let state;
+            try {
+                const record = await pool.getUser(uid);
+                const validAfterRaw = record == null ? void 0 : record.tokensValidAfterTime;
+                const parsed = validAfterRaw ? Date.parse(validAfterRaw) : NaN;
+                state = {
+                    missing: false,
+                    disabled: (record == null ? void 0 : record.disabled) === true,
+                    validAfterMs: Number.isFinite(parsed) ? parsed : null
+                };
+            } catch (error) {
+                var _ref;
+                const code = (_ref = error == null ? void 0 : error.code) != null ? _ref : '';
+                if (code === 'auth/user-not-found') {
+                    state = {
+                        missing: true,
+                        disabled: false,
+                        validAfterMs: null
+                    };
+                } else {
+                    // Outage. Fail open, and do NOT cache — one blip must not blind
+                    // the check for a whole TTL.
+                    return null;
+                }
+            }
+            cache.delete(key);
+            cache.set(key, {
+                at: Date.now(),
+                state
+            });
+            while(cache.size > TOKEN_REVOCATION_CACHE_MAX){
+                const oldest = cache.keys().next().value;
+                if (oldest === undefined) break;
+                cache.delete(oldest);
+            }
+            return state;
+        })().finally(()=>{
+            pending.delete(key);
+        });
+        pending.set(key, inFlight);
+    }
+    return inFlight;
+}
+/**
+ * Throw if this verified ID token belongs to an account that has since been
+ * revoked, disabled or deleted. Resolves silently otherwise, including when
+ * the account could not be reached.
+ *
+ * @param pool - the auth handle the token was verified against; the lookup
+ *   MUST go to the same one (AGL-2005), and the parameter is named `pool`
+ *   rather than `auth` because that is the contract — `no-project-level-auth-
+ *   lookup.spec.ts` reads the receiver name and is right to
+ * @param decoded - the token firebase-admin just verified
+ */ export async function assertIdTokenNotRevoked(pool, decoded) {
+    var _ref;
+    var _decoded_firebase;
+    const uid = decoded == null ? void 0 : decoded.uid;
+    if (!uid) return;
+    const tenantId = (_ref = decoded == null ? void 0 : (_decoded_firebase = decoded.firebase) == null ? void 0 : _decoded_firebase.tenant) != null ? _ref : null;
+    const state = await readAccountState(pool, uid, cacheKey(uid, tenantId));
+    // `=== null`, not `!state`: strictNullChecks is off repo-wide, so the falsy
+    // test would not narrow and would also swallow a real state object one
+    // refactor from now.
+    if (state === null) return;
+    if (state.missing) {
+        throw new IdTokenRevokedError('The user record no longer exists.');
+    }
+    if (state.disabled) throw new UserDisabledError();
+    if (revocationRefuses(decoded, state.validAfterMs)) {
+        throw new IdTokenRevokedError();
+    }
+}
+
+//# sourceMappingURL=token-revocation.js.map

package/src/lib/server/token-revocation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/token-revocation.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 * ID-token revocation on every server door (AGL-1881).\n *\n * ## The gap this closes\n *\n * `verifyIdToken(token)` checks a signature and an expiry. It does not ask\n * whether the account was locked, disabled, deleted, de-staffed or signed out\n * five seconds ago — that costs a round trip, so the SDK makes it opt-in via\n * `checkRevoked`. The pre-launch audit found the flag set on 3 of 175 call\n * sites: the session MINT, the session EXCHANGE and the device-revoke route.\n * Everything else — 117 console API routes, plus the marketplace, commerce and\n * bookings plugin servers — took a bare `verifyIdToken`.\n *\n * So `revokeRefreshTokens(uid)` stopped the browser getting a NEW token and\n * did nothing about the one it already held. After a panic user-lock, a staff\n * password reset, an SSO offboard, an org-wide lockdown or a \"sign out\n * everywhere\", the revoked token kept opening every one of those doors for the\n * remainder of its hour. `device-revocation.ts` meanwhile promised the effect\n * was \"immediate for everything that goes through our server\", which was the\n * defect worth fixing: the sentence was shipped and it was not true.\n *\n * ## Why it is a cached epoch and not just `checkRevoked: true`\n *\n * `checkRevoked` costs one `accounts:lookup` per verification. Measured\n * against production `aglyn-main` (n=40): p50 95.5ms, p95 144ms — statistically\n * indistinguishable from the p50 85.8ms single Firestore `doc().get()` that\n * every one of these routes already performs, on the same connection from the\n * same machine. So the round trip is not expensive; it is just paid too often.\n * Turned on unconditionally it would multiply Identity Toolkit calls by the\n * whole console request volume, against a project quota, to re-answer a\n * question whose answer changes maybe twice a year per account.\n *\n * The answer is therefore CACHED, on exactly the terms AGL-1522 already set\n * for the panic path: `PLATFORM_TTL_MS`, 15 seconds, LRU-bounded, with the\n * acting process invalidating the uid after its own write. Steady state costs\n * nothing; a cold entry costs one Firestore-read-equivalent; the honest window\n * goes from ~3600s to ≤15s, and to zero on the process that did the revoking.\n * A revocation control whose staleness bound matches the lockdown control it\n * sits beside is one bound to explain, not two.\n *\n * ## What is checked, and in which pool\n *\n * Three refusals, mirroring firebase-admin's own `checkRevoked` so the error\n * codes route handlers already catch keep working unchanged:\n *\n *  - `tokensValidAfterTime` after the token's `auth_time` → `id-token-revoked`\n *  - `disabled` → `user-disabled` (a user-scope panic lock sets this, and it\n *    is the half that does not depend on clock agreement)\n *  - the record is GONE → `id-token-revoked` (a deleted account is not a\n *    signed-in one; the SDK's own check treats this as revoked too)\n *\n * The lookup is asked of the auth instance the token was verified with, which\n * is the AGL-2005 rule made structural rather than remembered: a tenant-aware\n * auth asks the tenant pool, and a project-pool lookup for an SSO uid — which\n * would answer \"never revoked\" about a forged twin — cannot be spelled.\n *\n * ## Failure direction\n *\n * An unreachable Identity Toolkit is an outage, not a revocation, and refusing\n * every request in the console during one would be a self-inflicted lockdown.\n * So a transport failure fails OPEN — and is NOT cached, or a single blip\n * would blind the check for a full TTL. `user-not-found` is not a transport\n * failure and fails closed. This is the opposite direction from\n * `deviceRevocationRefuses`, which refuses an undateable credential, and the\n * split is deliberate: \"we could not reach the service\" and \"the service told\n * us this account is gone\" are different answers.\n */\n\nimport type { BaseAuth, DecodedIdToken } from 'firebase-admin/auth'\n\n/**\n * Matches `PLATFORM_TTL_MS` in `lockdown.ts`, and deliberately so — see the\n * module note. One number for how stale a panic action may read.\n */\nexport const TOKEN_REVOCATION_TTL_MS = 15_000\n\n/**\n * Bounded so a scan of uids cannot balloon a warm serverless process. Past\n * this many entries the least-recently-USED is evicted; a cache hit refreshes\n * recency, so an active session is not what a scan pushes out. Same bound and\n * same reasoning as `USER_LOCKDOWN_CACHE_MAX`.\n */\nexport const TOKEN_REVOCATION_CACHE_MAX = 5000\n\n/** Thrown for a token the account has invalidated. Code matches the SDK's. */\nexport class IdTokenRevokedError extends Error {\n  readonly code = 'auth/id-token-revoked'\n  constructor(message = 'The ID token has been revoked.') {\n    super(message)\n    this.name = 'IdTokenRevokedError'\n  }\n}\n\n/** Thrown for a token whose account is disabled. Code matches the SDK's. */\nexport class UserDisabledError extends Error {\n  readonly code = 'auth/user-disabled'\n  constructor(message = 'The user record is disabled.') {\n    super(message)\n    this.name = 'UserDisabledError'\n  }\n}\n\n/** What the check needs off the account record, and nothing else. */\ninterface AccountState {\n  /** `true` when the record could not be found at all. */\n  missing: boolean\n  disabled: boolean\n  /** `tokensValidAfterTime` as epoch ms; null when never revoked. */\n  validAfterMs: number | null\n}\n\nconst cache = new Map<string, { at: number; state: AccountState }>()\nconst pending = new Map<string, Promise<AccountState | null>>()\n\n/**\n * A uid is only unique WITHIN a pool (AGL-2005), so the pool is part of the\n * key. The separator is a NUL because a tenant id cannot contain one.\n */\nfunction cacheKey(uid: string, tenantId: string | null | undefined): string {\n  return `${tenantId ?? ''}\\u0000${uid}`\n}\n\n/**\n * Drop one account's cached verdict — called by every path that revokes, so\n * the process that took the action refuses on its very next request instead\n * of waiting out its own TTL. Called bare, clears everything.\n */\nexport function invalidateTokenRevocationCache(\n  uid?: string,\n  tenantId?: string | null,\n): void {\n  if (uid === undefined) {\n    cache.clear()\n    pending.clear()\n    return\n  }\n  // A revoke reaches the account, not one pool's view of it: clear the\n  // project-pool key and the named tenant's, so a caller that does not know\n  // which pool answered still gets a fresh read.\n  for (const key of [cacheKey(uid, null), cacheKey(uid, tenantId)]) {\n    cache.delete(key)\n    pending.delete(key)\n  }\n}\n\n/** Full reset, for specs. Production code wants the per-uid form above. */\nexport function resetTokenRevocationCache(): void {\n  cache.clear()\n  pending.clear()\n}\n\n/**\n * Does this account's revocation epoch refuse this token?\n *\n * Both sides are floored to whole seconds before comparing.\n * `tokensValidAfterTime` is an RFC-1123 string with second granularity and\n * `auth_time` is a whole second, so comparing in milliseconds would let a\n * token minted in the same second as the revoke read as refused on one\n * process and admitted on the next.\n *\n * @param decoded - the verified ID token\n * @param validAfterMs - epoch ms from `tokensValidAfterTime`, null when never\n *   revoked\n */\nexport function revocationRefuses(\n  decoded: DecodedIdToken,\n  validAfterMs: number | null | undefined,\n): boolean {\n  const validAfter = Number(validAfterMs ?? 0)\n  if (!Number.isFinite(validAfter) || validAfter <= 0) return false\n  // `auth_time` moves only on a real authentication, which is what makes it\n  // the right clock: an attacker holding a stolen cookie and refresh token\n  // cannot produce a newer one. `iat` is the fallback for the handful of\n  // custom-token sign-ins that carry no `auth_time`.\n  const issuedSeconds = Number(decoded?.auth_time ?? decoded?.iat ?? 0)\n  // An undateable token cannot be shown to postdate the revocation, and the\n  // safe direction for a security control is to refuse it.\n  if (!Number.isFinite(issuedSeconds) || issuedSeconds <= 0) return true\n  return Math.floor(issuedSeconds) < Math.floor(validAfter / 1000)\n}\n\n/**\n * Read (and cache) the account state behind a uid.\n *\n * `null` means \"could not ask\" — an outage, distinct from every answer the\n * service can give, and never cached.\n */\nasync function readAccountState(\n  pool: Pick<BaseAuth, 'getUser'>,\n  uid: string,\n  key: string,\n): Promise<AccountState | null> {\n  const cached = cache.get(key)\n  if (cached && Date.now() - cached.at < TOKEN_REVOCATION_TTL_MS) {\n    // Re-insert to refresh recency: eviction is least-recently-used, and an\n    // ACTIVE session must not be what a uid scan evicts.\n    cache.delete(key)\n    cache.set(key, cached)\n    return cached.state\n  }\n  let inFlight = pending.get(key)\n  if (!inFlight) {\n    inFlight = (async () => {\n      // No initializer: every path below either assigns `state` or returns,\n      // so seeding it with `null` would be a value nothing ever reads.\n      let state: AccountState\n      try {\n        const record = await pool.getUser(uid)\n        const validAfterRaw = record?.tokensValidAfterTime\n        const parsed = validAfterRaw ? Date.parse(validAfterRaw) : NaN\n        state = {\n          missing: false,\n          disabled: record?.disabled === true,\n          validAfterMs: Number.isFinite(parsed) ? parsed : null,\n        }\n      } catch (error) {\n        const code = (error as { code?: string })?.code ?? ''\n        if (code === 'auth/user-not-found') {\n          state = { missing: true, disabled: false, validAfterMs: null }\n        } else {\n          // Outage. Fail open, and do NOT cache — one blip must not blind\n          // the check for a whole TTL.\n          return null\n        }\n      }\n      cache.delete(key)\n      cache.set(key, { at: Date.now(), state })\n      while (cache.size > TOKEN_REVOCATION_CACHE_MAX) {\n        const oldest = cache.keys().next().value\n        if (oldest === undefined) break\n        cache.delete(oldest)\n      }\n      return state\n    })().finally(() => {\n      pending.delete(key)\n    })\n    pending.set(key, inFlight)\n  }\n  return inFlight\n}\n\n/**\n * Throw if this verified ID token belongs to an account that has since been\n * revoked, disabled or deleted. Resolves silently otherwise, including when\n * the account could not be reached.\n *\n * @param pool - the auth handle the token was verified against; the lookup\n *   MUST go to the same one (AGL-2005), and the parameter is named `pool`\n *   rather than `auth` because that is the contract — `no-project-level-auth-\n *   lookup.spec.ts` reads the receiver name and is right to\n * @param decoded - the token firebase-admin just verified\n */\nexport async function assertIdTokenNotRevoked(\n  pool: Pick<BaseAuth, 'getUser'>,\n  decoded: DecodedIdToken,\n): Promise<void> {\n  const uid = decoded?.uid\n  if (!uid) return\n  const tenantId = decoded?.firebase?.tenant ?? null\n  const state = await readAccountState(pool, uid, cacheKey(uid, tenantId))\n  // `=== null`, not `!state`: strictNullChecks is off repo-wide, so the falsy\n  // test would not narrow and would also swallow a real state object one\n  // refactor from now.\n  if (state === null) return\n  if (state.missing) {\n    throw new IdTokenRevokedError('The user record no longer exists.')\n  }\n  if (state.disabled) throw new UserDisabledError()\n  if (revocationRefuses(decoded, state.validAfterMs)) {\n    throw new IdTokenRevokedError()\n  }\n}\n"],"names":["TOKEN_REVOCATION_TTL_MS","TOKEN_REVOCATION_CACHE_MAX","IdTokenRevokedError","Error","message","code","name","UserDisabledError","cache","Map","pending","cacheKey","uid","tenantId","invalidateTokenRevocationCache","undefined","clear","key","delete","resetTokenRevocationCache","revocationRefuses","decoded","validAfterMs","validAfter","Number","isFinite","issuedSeconds","auth_time","iat","Math","floor","readAccountState","pool","cached","get","Date","now","at","set","state","inFlight","record","getUser","validAfterRaw","tokensValidAfterTime","parsed","parse","NaN","missing","disabled","error","size","oldest","keys","next","value","finally","assertIdTokenNotRevoked","firebase","tenant"],"mappings":"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"}

package/src/lib/server/update-existing.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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 slice of `DocumentReference` this needs. Typed structurally so a caller
+ * holding a `DocumentReference<T>` from any of the SDK's generic positions
+ * passes without a cast, and so specs can drive it with an in-memory double.
+ */
+export interface UpdatableDocumentRef {
+    update(data: Record<string, unknown>): Promise<unknown>;
+    readonly path?: string;
+}
+/**
+ * Applies `data` to `ref` only if the document exists.
+ *
+ * @returns `true` when the update landed, `false` when the document was
+ *   absent. Any other failure rethrows.
+ */
+export declare function updateExisting(ref: UpdatableDocumentRef, data: Record<string, unknown>): Promise<boolean>;

package/src/lib/server/update-existing.js

@@ -0,0 +1,73 @@
+/**
+ * @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.
+ */ /**
+ * `updateExisting(ref, data)` — write to a document that must ALREADY exist,
+ * and say plainly whether it did (AGL-1763).
+ *
+ * `set(ref, data, { merge: true })` reads as "update if present" and means
+ * "create if absent". When the document id came from a caller, a webhook, or a
+ * cached list, that gap mints a phantom: a real document holding only the
+ * fields of this one patch, which then satisfies every query that filters on
+ * them and nothing else. AGL-1755 (a stub booking), AGL-1760 (a stub
+ * reservation) and AGL-1763's `orgs/{orgId}` finding are all the same shape.
+ *
+ * The codebase already carried the correct idiom and even documented the
+ * hazard — `apps/tenant/app/api/analytics/collect/route.ts:101`:
+ *
+ *   "update(), not set(): beacons from stale cached pages must not resurrect a
+ *   deleted overlay as a stats-only stray doc."
+ *
+ * `update()` IS the existence check: atomic, no second read, and it rejects on
+ * a missing document. AGL-1763 measured a lint rule for this and rejected it
+ * (14% precision, 57% recall — "this document must already exist" is a
+ * property of the caller's intent, not of the syntax). A named call is the
+ * remedy instead: it makes the intent explicit and greppable at the site.
+ *
+ * WHAT THIS ADDS OVER A BARE `.update()`. The tempting shorthand,
+ * `ref.update(data).catch(() => false)`, is wrong in a way that is invisible
+ * until it matters: it reports "the document was absent" for a permission
+ * denial, an App Check rejection, a transport failure, and — the trap that
+ * actually bites here — an `INVALID_ARGUMENT` from a delete sentinel below the
+ * top level, which `set({ merge: true })` accepts at any depth but `update()`
+ * accepts only at the root (`@google-cloud/firestore` serializer,
+ * `allowDeletes: 'root'`). Only gRPC `NOT_FOUND` means absent. Everything else
+ * rethrows, so a caller that maps `false` onto a 404 cannot turn an outage
+ * into a confident lie about the data.
+ *
+ * WHAT IT DOES NOT DECIDE. Refusing is not automatically right — AGL-1760's
+ * lesson is that a refusal must not discard money or work that already
+ * happened. The caller still chooses between refusing, refusing-and-recording,
+ * and creating deliberately with every required field. This only makes the
+ * question unavoidable by handing back the answer.
+ */ /** gRPC `Status.NOT_FOUND`. Firestore's "no entity to update" surfaces here. */ const GRPC_NOT_FOUND = 5;
+/**
+ * Applies `data` to `ref` only if the document exists.
+ *
+ * @returns `true` when the update landed, `false` when the document was
+ *   absent. Any other failure rethrows.
+ */ export async function updateExisting(ref, data) {
+    try {
+        await ref.update(data);
+        return true;
+    } catch (error) {
+        if ((error == null ? void 0 : error.code) === GRPC_NOT_FOUND) {
+            return false;
+        }
+        throw error;
+    }
+}
+
+//# sourceMappingURL=update-existing.js.map

package/src/lib/server/update-existing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/update-existing.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 * `updateExisting(ref, data)` — write to a document that must ALREADY exist,\n * and say plainly whether it did (AGL-1763).\n *\n * `set(ref, data, { merge: true })` reads as \"update if present\" and means\n * \"create if absent\". When the document id came from a caller, a webhook, or a\n * cached list, that gap mints a phantom: a real document holding only the\n * fields of this one patch, which then satisfies every query that filters on\n * them and nothing else. AGL-1755 (a stub booking), AGL-1760 (a stub\n * reservation) and AGL-1763's `orgs/{orgId}` finding are all the same shape.\n *\n * The codebase already carried the correct idiom and even documented the\n * hazard — `apps/tenant/app/api/analytics/collect/route.ts:101`:\n *\n *   \"update(), not set(): beacons from stale cached pages must not resurrect a\n *   deleted overlay as a stats-only stray doc.\"\n *\n * `update()` IS the existence check: atomic, no second read, and it rejects on\n * a missing document. AGL-1763 measured a lint rule for this and rejected it\n * (14% precision, 57% recall — \"this document must already exist\" is a\n * property of the caller's intent, not of the syntax). A named call is the\n * remedy instead: it makes the intent explicit and greppable at the site.\n *\n * WHAT THIS ADDS OVER A BARE `.update()`. The tempting shorthand,\n * `ref.update(data).catch(() => false)`, is wrong in a way that is invisible\n * until it matters: it reports \"the document was absent\" for a permission\n * denial, an App Check rejection, a transport failure, and — the trap that\n * actually bites here — an `INVALID_ARGUMENT` from a delete sentinel below the\n * top level, which `set({ merge: true })` accepts at any depth but `update()`\n * accepts only at the root (`@google-cloud/firestore` serializer,\n * `allowDeletes: 'root'`). Only gRPC `NOT_FOUND` means absent. Everything else\n * rethrows, so a caller that maps `false` onto a 404 cannot turn an outage\n * into a confident lie about the data.\n *\n * WHAT IT DOES NOT DECIDE. Refusing is not automatically right — AGL-1760's\n * lesson is that a refusal must not discard money or work that already\n * happened. The caller still chooses between refusing, refusing-and-recording,\n * and creating deliberately with every required field. This only makes the\n * question unavoidable by handing back the answer.\n */\n\n/** gRPC `Status.NOT_FOUND`. Firestore's \"no entity to update\" surfaces here. */\nconst GRPC_NOT_FOUND = 5\n\n/**\n * The slice of `DocumentReference` this needs. Typed structurally so a caller\n * holding a `DocumentReference<T>` from any of the SDK's generic positions\n * passes without a cast, and so specs can drive it with an in-memory double.\n */\nexport interface UpdatableDocumentRef {\n  update(data: Record<string, unknown>): Promise<unknown>\n  readonly path?: string\n}\n\n/**\n * Applies `data` to `ref` only if the document exists.\n *\n * @returns `true` when the update landed, `false` when the document was\n *   absent. Any other failure rethrows.\n */\nexport async function updateExisting(\n  ref: UpdatableDocumentRef,\n  data: Record<string, unknown>,\n): Promise<boolean> {\n  try {\n    await ref.update(data)\n    return true\n  } catch (error) {\n    if ((error as { code?: unknown } | null)?.code === GRPC_NOT_FOUND) {\n      return false\n    }\n    throw error\n  }\n}\n"],"names":["GRPC_NOT_FOUND","updateExisting","ref","data","update","error","code"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCC,GAED,8EAA8E,GAC9E,MAAMA,iBAAiB;AAYvB;;;;;CAKC,GACD,OAAO,eAAeC,eACpBC,GAAyB,EACzBC,IAA6B;IAE7B,IAAI;QACF,MAAMD,IAAIE,MAAM,CAACD;QACjB,OAAO;IACT,EAAE,OAAOE,OAAO;QACd,IAAI,CAACA,yBAAD,AAACA,MAAqCC,IAAI,MAAKN,gBAAgB;YACjE,OAAO;QACT;QACA,MAAMK;IACR;AACF"}