@oxy.so/core 7.15.1 → 7.17.0

package/src/server/middleware.ts

@@ -2,7 +2,8 @@ import { hasBoundedServiceTokenLifetime } from './serviceTokenLifetime';
 /**
  * The Express and Socket.IO middleware `OxyServer` mounts
  * (`server.middleware.auth()`, `.socket()`, `.service()`, `.requireScope()`,
- * `.requireAppPermission()`),
+ * `.requireAppPermission()`, `.requireAccountAccess()`,
+ * `.requireApplicationAccess()`),
  * and the Ed25519 service-token and account-event verification they share.
  *
  * Node only; reachable solely from `@oxy.so/core/server`.
@@ -18,6 +19,13 @@ import {
   type OxyAppPermissions,
   type RequireAppPermissionOptions,
 } from './appPermissions';
+import {
+  accessErrorStatus,
+  authorityErrorBody,
+  OxyAccessError,
+  type OxyAccessDenyStatus,
+} from './callerAuthority';
+import type { CallerAccessOptions, OxyAccountAccess, OxyApplicationAccess } from './callerAccess';
 import {
   accountActorChainSchema,
   type AccountActorChain,
@@ -309,7 +317,8 @@ export interface AuthMiddlewareOptions {
    * Own product receivers use their SDK's canonical `oxy-service:<appId>` audience.
    * First-party tokens must name that recipient exactly. External scoped tokens
    * also retain the legacy `oxy-api` audience. Other audience overrides remain exact.
-   * Oxy API defaults to `oxy-api`.
+   * Defaults to `OxyServerConfig.expectedAudience` when the server sets one,
+   * else `oxy-api`.
    */
   expectedAudience?: string;
 }
@@ -321,6 +330,8 @@ export interface AuthMiddlewareOptions {
  */
 export interface OxyMiddlewareHost {
   readonly baseURL: string;
+  /** `OxyServerConfig.expectedAudience`: the audience `auth()` accepts when a mount names none. */
+  readonly defaultAudience?: string;
   readonly jwksCache: ServiceTokenJwksCache;
   validateSession(
     sessionId: string,
@@ -353,6 +364,36 @@ export interface OxyMiddlewareHost {
     req: AppPermissionsRequest,
     options?: AppPermissionsOptions,
   ): Promise<OxyAppPermissions>;
+  /** `OxyServer.accountAccessFor`. */
+  accountAccessFor(
+    req: AuthReq,
+    accountId: string,
+    options?: CallerAccessOptions,
+  ): Promise<OxyAccountAccess>;
+  /** `OxyServer.applicationAccessFor`. */
+  applicationAccessFor(
+    req: AuthReq,
+    applicationId: string,
+    options?: CallerAccessOptions,
+  ): Promise<OxyApplicationAccess>;
+}
+
+/** Options of `middleware.requireAccountAccess` / `requireApplicationAccess`. */
+export interface RequireAccessOptions extends CallerAccessOptions {
+  /** The route parameter that names the account or application (`':appId'` → `'appId'`). */
+  param: string;
+  /**
+   * What a refusal is answered: `403` (default; `401` without a session) or
+   * `404` (`404` without a session too), for a surface that must not reveal
+   * what exists. Oxy unreachable is always `503`.
+   */
+  deny?: OxyAccessDenyStatus;
+  /**
+   * `false` hands the {@link OxyAccessError} to `next(error)` instead of
+   * answering; `accessErrorStatus(error, deny)` gives the status the
+   * middleware would have used.
+   */
+  respond?: boolean;
 }
 
 /** Build the middleware set for one server. See `OxyServer.middleware`. */
@@ -443,7 +484,7 @@ export function createOxyMiddleware(host: OxyMiddlewareHost) {
       optional = false,
       serviceTokenJwksUrl = new URL('/.well-known/jwks.json', host.baseURL).toString(),
       expectedIssuer = OXY_JWT_ISSUER,
-      expectedAudience = OXY_JWT_AUDIENCE,
+      expectedAudience = host.defaultAudience ?? OXY_JWT_AUDIENCE,
     } = options;
     const strictPresentedBearer = Boolean(
       options.supervisedAction || options.strictOptionalBearer || options.liveSession,
@@ -1587,7 +1628,130 @@ export function createOxyMiddleware(host: OxyMiddlewareHost) {
     };
   }
 
-  return { auth, socket, service, requireScope, requireAppPermission };
+  /**
+   * One gate for both caller-access readers: read the id from the route
+   * parameter, ask, admit on `permission`, answer a refusal by its outcome.
+   */
+  function requireCallerAccess<T extends { has(permission: string): boolean }>(
+    method: 'requireAccountAccess' | 'requireApplicationAccess',
+    permission: string,
+    options: RequireAccessOptions,
+    read: (req: AuthReq, id: string, lookup: CallerAccessOptions) => Promise<T>,
+    admit: (req: AuthReq, access: T) => void,
+  ) {
+    const { param, deny = 403, respond = true, ...lookup } = options;
+    if (typeof permission !== 'string' || permission.trim() === '') {
+      throw new Error(`${method}: permission must be a non-empty string`);
+    }
+    if (typeof param !== 'string' || param.trim() === '') {
+      throw new Error(`${method}: param must name the route parameter that holds the id`);
+    }
+    if (deny !== 403 && deny !== 404) {
+      throw new Error(`${method}: deny must be 403 or 404`);
+    }
+
+    return async (req: AuthReq, res: AuthRes, next: AuthNext): Promise<void> => {
+      let refusal: OxyAccessError;
+      const id = req.params?.[param];
+      try {
+        if (typeof id !== 'string' || id === '') {
+          throw new OxyAccessError('ACCESS_DENIED', `No ${param} on this route`);
+        }
+        const access = await read(req, id, lookup);
+        if (access.has(permission)) {
+          admit(req, access);
+          next();
+          return;
+        }
+        refusal = new OxyAccessError('ACCESS_DENIED', `Missing permission ${permission}`, {
+          permission,
+        });
+      } catch (error) {
+        if (!(error instanceof OxyAccessError)) {
+          next(error);
+          return;
+        }
+        refusal = new OxyAccessError(error.code, error.message, {
+          permission,
+          cause: error.cause ?? error,
+        });
+      }
+
+      if (refusal.code === 'ACCESS_UNAVAILABLE') {
+        logger.warn(`[oxy.auth] ${method} could not ask Oxy`, {
+          component: 'auth',
+          method,
+          permission,
+          path: req.path,
+        });
+      }
+      if (!respond) {
+        next(refusal);
+        return;
+      }
+      const status = accessErrorStatus(refusal, deny);
+      res.status(status).json(authorityErrorBody(status));
+    };
+  }
+
+  /**
+   * Express middleware: the person behind the request must hold `permission`
+   * in the Oxy ACCOUNT named by the route parameter `param` (an organization,
+   * store, channel). Mount after `auth()`. On success the answer is on
+   * `req.oxyAccountAccess`. See `OxyServer.accountAccessFor`.
+   *
+   * @example
+   * ```typescript
+   * router.patch('/stores/:storeId', oxy.middleware.requireAccountAccess('account:update', { param: 'storeId', fresh: true }), handler);
+   * ```
+   */
+  function requireAccountAccess(permission: string, options: RequireAccessOptions) {
+    return requireCallerAccess(
+      'requireAccountAccess',
+      permission,
+      options,
+      (req, id, lookup) => host.accountAccessFor(req, id, lookup),
+      (req, access) => {
+        req.oxyAccountAccess = access;
+      },
+    );
+  }
+
+  /**
+   * Express middleware: the person behind the request must hold the
+   * application permission `permission` (`app:read`, `app:update`,
+   * `webhooks:update`, …) over the APPLICATION named by the route parameter
+   * `param`, through the account that owns it. Mount after `auth()`. On
+   * success the answer is on `req.oxyApplicationAccess`. See
+   * `OxyServer.applicationAccessFor`; for THIS backend's own operator keys use
+   * `requireAppPermission` instead.
+   *
+   * @example
+   * ```typescript
+   * router.get('/apps/:appId/payments', oxy.middleware.requireApplicationAccess('app:read', { param: 'appId' }), handler);
+   * ```
+   */
+  function requireApplicationAccess(permission: string, options: RequireAccessOptions) {
+    return requireCallerAccess(
+      'requireApplicationAccess',
+      permission,
+      options,
+      (req, id, lookup) => host.applicationAccessFor(req, id, lookup),
+      (req, access) => {
+        req.oxyApplicationAccess = access;
+      },
+    );
+  }
+
+  return {
+    auth,
+    socket,
+    service,
+    requireScope,
+    requireAppPermission,
+    requireAccountAccess,
+    requireApplicationAccess,
+  };
 }
 
 /** The middleware set `OxyServer.middleware` exposes. */
@@ -1891,6 +2055,9 @@ interface AuthReq {
   oxyActor?: AccountActorChain | null;
   oxyAuthRefusal?: OxyAuthRefusal;
   oxyAppPermissions?: OxyAppPermissions;
+  oxyAccountAccess?: OxyAccountAccess;
+  oxyApplicationAccess?: OxyApplicationAccess;
+  params?: Record<string, string | string[] | undefined>;
 }
 
 interface AuthRes {

package/src/server/namespaces.ts

@@ -142,6 +142,29 @@ const HEADER_SAFE_PATTERN = /^[\x20-\x7e]*$/;
 export type ServiceUploadBody = Uint8Array | ArrayBuffer | Blob;
 
 /** What `uploadAppFile` and `uploadUserMedia` may say about the bytes besides their type. */
+/**
+ * Per-call transport options for a service call, overriding the server's
+ * `requestTimeout` / `enableRetry` for that one call — so one `OxyServer` can
+ * make a short, single-shot write and a patient read side by side.
+ */
+export interface ServiceCallOptions {
+  /** Abort the call. */
+  signal?: AbortSignal;
+  /** Per-attempt timeout in ms. */
+  timeout?: number;
+  /** `false` sends the call once; a transient failure is the caller's to retry (an outbox). */
+  retry?: boolean;
+}
+
+/** The `RequestOptions` half of {@link ServiceCallOptions}, only the fields that were set. */
+function serviceCallRequestOptions(options: ServiceCallOptions): RequestOptions {
+  return {
+    ...(options.signal ? { signal: options.signal } : {}),
+    ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
+    ...(options.retry !== undefined ? { retry: options.retry } : {}),
+  };
+}
+
 export interface ServiceUploadDescription {
   /**
    * Stored as the file's original name. Sent as a header, so only printable
@@ -305,12 +328,19 @@ export class ServerAssetsApi extends AssetsApi {
    *   changes the file's visibility.
    * - `remove`: only references this application holds. Never trashes or
    *   deletes the file.
+   *
+   * Both take {@link ServiceCallOptions} for each request they send — e.g.
+   * `{ retry: false, timeout: 5000 }` from an outbox that retries by itself.
    */
   readonly references = {
-    add: (references: ServiceFileReference[]): Promise<ServiceFileReferenceResult[]> =>
-      this.sendReferences('POST', references),
-    remove: (references: ServiceFileReference[]): Promise<ServiceFileReferenceResult[]> =>
-      this.sendReferences('DELETE', references),
+    add: (
+      references: ServiceFileReference[],
+      options: ServiceCallOptions = {},
+    ): Promise<ServiceFileReferenceResult[]> => this.sendReferences('POST', references, options),
+    remove: (
+      references: ServiceFileReference[],
+      options: ServiceCallOptions = {},
+    ): Promise<ServiceFileReferenceResult[]> => this.sendReferences('DELETE', references, options),
     /**
      * Reconcile this application's references of ONE entity type with its
      * real inventory (ADR 0043 D6) — the safety net for a reference a crash or
@@ -516,6 +546,7 @@ export class ServerAssetsApi extends AssetsApi {
   private async sendReferences(
     method: 'POST' | 'DELETE',
     references: ServiceFileReference[],
+    options: ServiceCallOptions,
   ): Promise<ServiceFileReferenceResult[]> {
     const results: ServiceFileReferenceResult[] = [];
     for (let start = 0; start < references.length; start += SERVICE_REFERENCES_CHUNK_SIZE) {
@@ -526,7 +557,7 @@ export class ServerAssetsApi extends AssetsApi {
         method,
         '/assets/service/references',
         { references: chunk },
-        { cache: false },
+        { ...serviceCallRequestOptions(options), cache: false },
       );
       results.push(...res.results);
     }

package/src/server/safeFetch.ts

@@ -28,6 +28,16 @@
  *    response; without one, a server that sends its headers and stalls holds
  *    any other reader open.
  *
+ * NOT FOR OXY'S OWN HOSTS
+ * -----------------------
+ * `safeFetch` is for UNTRUSTED or caller-influenced URLs only. Never use it to
+ * reach a first-party host (`api.oxy.so`, any `*.oxy.so`, an Oxy product's
+ * API): inside the VPC those names resolve to the internal load balancer
+ * (split-horizon DNS), a private address this module refuses by design. Call
+ * Oxy through `OxyServer` — its namespaces, `serviceRequest`, or
+ * `createServiceClient({ baseURL, audience }).fetch` for another Oxy product.
+ * A refusal of such a host says so in its message.
+ *
  * Node-only: this module imports `node:http`/`node:https`/`node:dns` and is
  * exported solely from `@oxy.so/core/server`. It MUST NOT be reachable from the
  * browser `@oxy.so/core` entry.
@@ -40,6 +50,7 @@ import type { LookupAddress, LookupAllOptions, LookupOneOptions } from 'node:dns
 import type { LookupFunction } from 'node:net';
 import { isIP } from 'node:net';
 import { URL } from 'node:url';
+import { isLoopbackOrigin, isOfficialWebOrigin } from '../utils/officialOrigins';
 import { withDeadline } from './deadline';
 import { extractEmbeddedIpv4, ipv4InCidr, ipv6InCidr } from './ipCidr';
 
@@ -297,6 +308,23 @@ export async function assertSafePublicUrl(
   };
 }
 
+/** What a refusal of a first-party Oxy host adds to its reason. */
+const FIRST_PARTY_HOST_HINT =
+  'first-party Oxy host: inside the VPC it resolves to a private address, which safeFetch refuses by design; call it through OxyServer (its namespaces, serviceRequest, or createServiceClient().fetch), not safeFetch';
+
+/** `reason`, plus the first-party hint when `rawUrl` names an official Oxy host. */
+function rejectionReason(rawUrl: string, reason: string): string {
+  let origin: string;
+  try {
+    origin = new URL(rawUrl).origin;
+  } catch {
+    return reason;
+  }
+  return isOfficialWebOrigin(origin) && !isLoopbackOrigin(origin)
+    ? `${reason} (${FIRST_PARTY_HOST_HINT})`
+    : reason;
+}
+
 /** Marker error for a blocked SSRF target (map to 403 at the route layer). */
 export class SsrfRejection extends Error {
   constructor(reason: string) {
@@ -484,7 +512,9 @@ export async function safeFetch(
       signal,
     });
     if (!guard.ok) {
-      throw guard.incomplete ? new UpstreamError(guard.reason) : new SsrfRejection(guard.reason);
+      throw guard.incomplete
+        ? new UpstreamError(guard.reason)
+        : new SsrfRejection(rejectionReason(currentUrl, guard.reason));
     }
 
     const target = new URL(currentUrl);

package/src/server/userClient.ts

@@ -0,0 +1,147 @@
+/**
+ * Calling Oxy AS the person behind a request.
+ *
+ * A backend's `OxyServer` is a process singleton authenticated as the backend
+ * itself; a user's bearer must never be planted on it (`setTokens`,
+ * `session.setAccessToken`), because every concurrent request would then speak
+ * as that user. A read that must be answered for the person — their own
+ * account graph, an application they manage, their profile — goes through an
+ * {@link OxyUserClient}: every namespace of `OxyServices`, bound to that one
+ * bearer, sharing no mutable state with the server.
+ *
+ * ```ts
+ * // Express, after oxy.middleware.auth():
+ * const node = await oxy.withUser(req, (user) => user.accounts.get(accountId));
+ * ```
+ *
+ * What makes it safe to create one per request:
+ *
+ * - **No response cache.** The client is built with `enableCache: false`, so
+ *   one person's answers are never served to anyone, including the same
+ *   person's next request, and nothing is registered with the module-wide
+ *   cache sweep.
+ * - **Exactly this bearer, every time.** Every request carries it as an
+ *   explicit `Authorization` header: never refreshed (that is the user's own
+ *   client's job), never dropped for an expired or opaque token, never
+ *   replaced by the server's service token. Oxy answers a revoked or expired
+ *   bearer 401, which the access readers map to `ACCESS_SESSION_REQUIRED`.
+ * - **Deterministic end.** `withUser` disposes the client when the callback
+ *   settles, so a reference that escapes the callback holds no bearer. A
+ *   client from `asUser` that is never disposed holds no global resource
+ *   either; it is collected with its last reference.
+ *
+ * Node only; reachable solely from `@oxy.so/core/server`.
+ */
+
+import { OxyServices, type OxyConfig } from '../OxyServices';
+import type { HttpMethod } from '../client/context';
+import type { RequestOptions, ResponsePayload } from '../HttpService';
+import { isBearerToken, OxyAccessError, type OxyCallerRequest } from './callerAuthority';
+
+/**
+ * Whose bearer a user client carries: a request `middleware.auth()` resolved
+ * to a user session (its `req.accessToken`), or a bearer string the caller has
+ * already verified (a Socket.IO handshake's `socket.accessToken`, say).
+ */
+export type OxyUserSource = string | OxyCallerRequest;
+
+/** The transport settings a user client inherits from its server; never auth, cache or app identity. */
+const INHERITED_TRANSPORT_KEYS = [
+  'baseURL',
+  'cloudURL',
+  'requestTimeout',
+  'enableRetry',
+  'maxRetries',
+  'retryDelay',
+  'maxConcurrentRequests',
+  'requestQueueSize',
+  'enableLogging',
+  'logLevel',
+  'onRequestStart',
+  'onRequestEnd',
+  'onRequestError',
+] as const satisfies readonly (keyof OxyConfig)[];
+
+/** The transport half of a server config, for a user client. */
+export function userClientConfig(config: Readonly<OxyConfig>): OxyConfig {
+  const transport: Partial<Record<keyof OxyConfig, unknown>> = {};
+  for (const key of INHERITED_TRANSPORT_KEYS) {
+    if (config[key] !== undefined) transport[key] = config[key];
+  }
+  return { ...(transport as OxyConfig), enableCache: false };
+}
+
+/**
+ * The user bearer `source` carries. Throws `OxyAccessError`
+ * (`ACCESS_SESSION_REQUIRED`) for a request with no user session — anonymous,
+ * or authenticated by a SERVICE token, whose bearer is the calling service's
+ * and never a person's.
+ */
+export function userBearerOf(source: OxyUserSource): string {
+  if (typeof source === 'string') {
+    if (!isBearerToken(source)) {
+      throw new OxyAccessError('ACCESS_SESSION_REQUIRED', 'A user client needs a bearer token');
+    }
+    return source;
+  }
+  if (source.serviceApp) {
+    throw new OxyAccessError(
+      'ACCESS_SESSION_REQUIRED',
+      'This request is authenticated by a service token; a user client needs a person’s session',
+    );
+  }
+  const token = source.accessToken;
+  if (typeof token !== 'string' || !isBearerToken(token)) {
+    throw new OxyAccessError(
+      'ACCESS_SESSION_REQUIRED',
+      'No verified user session on this request; mount middleware.auth() first',
+    );
+  }
+  return token;
+}
+
+/**
+ * Every `OxyServices` namespace, authenticated as one person. Create it with
+ * `OxyServer.withUser` (disposed for you) or `OxyServer.asUser` (dispose it
+ * yourself); the constructor is not part of the public contract.
+ */
+export class OxyUserClient extends OxyServices {
+  private bearer: string | null;
+
+  /** @internal Use `OxyServer.asUser` / `OxyServer.withUser`. */
+  constructor(config: OxyConfig, accessToken: string) {
+    super(config);
+    this.bearer = accessToken;
+    // For the namespaces that read the session's identity (`session.userId`).
+    this.http.setTokens(accessToken);
+  }
+
+  /**
+   * Every namespace call goes through here: it carries this client's bearer
+   * explicitly, which also keeps the response out of any cache and out of
+   * request de-duplication. Rejects once the client is disposed.
+   */
+  override async request<T>(
+    method: HttpMethod,
+    url: string,
+    data?: unknown,
+    options: RequestOptions = {},
+  ): Promise<ResponsePayload<T>> {
+    const bearer = this.bearer;
+    if (!bearer) throw new Error('This Oxy user client has been disposed');
+    // This client speaks as its person only: no caller-supplied credential,
+    // in any letter case, rides along.
+    const headers: Record<string, string> = {};
+    for (const [name, value] of Object.entries(options.headers ?? {})) {
+      if (name.toLowerCase() !== 'authorization') headers[name] = value;
+    }
+    headers.Authorization = `Bearer ${bearer}`;
+    return super.request<T>(method, url, data, { ...options, headers });
+  }
+
+  /** Forget the bearer: every later call rejects. */
+  override dispose(): void {
+    this.bearer = null;
+    super.dispose();
+  }
+}

package/src/utils/cache.ts

@@ -57,6 +57,10 @@ export class TTLCache<T> {
   private misses = 0;
 
   private maxEntries: number;
+  /** Registered for the shared expiry sweep (see {@link registerCacheForCleanup}). */
+  private swept = false;
+  /** The sweep generation this cache registered in; {@link stopAllCleanupIntervals} ends it. */
+  private sweptGeneration = -1;
 
   /**
    * Create a new TTL cache
@@ -85,6 +89,7 @@ export class TTLCache<T> {
     if (now >= entry.expiresAt) {
       this.cache.delete(key);
       this.misses++;
+      this.syncSweep();
       return null;
     }
 
@@ -117,7 +122,7 @@ export class TTLCache<T> {
       const oldest = this.cache.keys().next().value;
       if (oldest !== undefined) this.cache.delete(oldest);
     }
-    if (!cleanupInterval && activeCaches.has(this)) updateCleanupInterval();
+    this.syncSweep();
   }
 
   /**
@@ -127,9 +132,7 @@ export class TTLCache<T> {
    */
   delete(key: string): boolean {
     const deleted = this.cache.delete(key);
-    // Only the delete that EMPTIES this cache can let the timer stop; checking
-    // on every delete made bulk invalidation O(deletes x caches).
-    if (deleted && this.cache.size === 0 && activeCaches.has(this)) updateCleanupInterval();
+    if (deleted) this.syncSweep();
     return deleted;
   }
 
@@ -140,7 +143,7 @@ export class TTLCache<T> {
     this.cache.clear();
     this.hits = 0;
     this.misses = 0;
-    if (activeCaches.has(this)) updateCleanupInterval();
+    this.syncSweep();
   }
 
   /**
@@ -155,7 +158,7 @@ export class TTLCache<T> {
         removed++;
       }
     }
-    if (removed > 0 && this.cache.size === 0 && activeCaches.has(this)) updateCleanupInterval();
+    if (removed > 0) this.syncSweep();
     return removed;
   }
 
@@ -170,6 +173,7 @@ export class TTLCache<T> {
 
     if (Date.now() >= entry.expiresAt) {
       this.cache.delete(key);
+      this.syncSweep();
       return false;
     }
 
@@ -191,6 +195,7 @@ export class TTLCache<T> {
         this.cache.delete(key);
       }
     }
+    this.syncSweep();
 
     return validKeys;
   }
@@ -209,10 +214,31 @@ export class TTLCache<T> {
         removed++;
       }
     }
+    if (removed > 0) this.syncSweep();
 
     return removed;
   }
 
+  /**
+   * Start or stop being swept: a registered cache is held by the shared sweep
+   * ONLY while it has entries to expire. An empty cache is referenced by
+   * nothing global, so a client nobody disposed is collected with its cache.
+   */
+  setSwept(swept: boolean): void {
+    this.swept = swept;
+    this.sweptGeneration = sweepGeneration;
+    this.syncSweep();
+  }
+
+  private syncSweep(): void {
+    if (this.swept && this.sweptGeneration === sweepGeneration && this.cache.size > 0) {
+      sweptCaches.add(this);
+    } else {
+      sweptCaches.delete(this);
+    }
+    updateCleanupInterval();
+  }
+
   /**
    * Get cache size (number of entries)
    */
@@ -255,41 +281,47 @@ export function createCache<T>(ttl: number = 5 * 60 * 1000): TTLCache<T> {
 }
 
 /**
- * Global cache cleanup interval (runs every minute)
- * This helps prevent memory leaks from expired cache entries
+ * The shared expiry sweep: one unref'd interval, running only while some
+ * registered cache holds entries.
+ *
+ * `sweptCaches` holds exactly the registered caches that are NON-EMPTY. A
+ * cache joins when it gains its first entry and leaves when it is emptied — by
+ * the sweep itself once its entries expire — so the module never pins a cache
+ * that has nothing to expire. That is what keeps a short-lived client that was
+ * never disposed (one per request, say) collectable: the most it can be held
+ * for is its entries' TTL.
  */
 let cleanupInterval: ReturnType<typeof setInterval> | null = null;
-const activeCaches = new Set<TTLCache<unknown>>();
+const sweptCaches = new Set<TTLCache<unknown>>();
+/** Bumped by {@link stopAllCleanupIntervals}, which ends every registration. */
+let sweepGeneration = 0;
 
 /**
  * Register a cache for automatic cleanup
  * @param cache Cache instance to register
  */
 export function registerCacheForCleanup(cache: TTLCache<unknown>): void {
-  activeCaches.add(cache);
-  updateCleanupInterval();
+  cache.setSwept(true);
 }
 
 /** Empty registered caches need no timer; importing a client must stay inert. */
 function updateCleanupInterval(): void {
-  const hasEntries = [...activeCaches].some((cache) => cache.size() > 0);
-  if (!hasEntries) {
+  if (sweptCaches.size === 0) {
     if (cleanupInterval) clearInterval(cleanupInterval);
     cleanupInterval = null;
     return;
   }
   if (cleanupInterval) return;
   cleanupInterval = setInterval(() => {
-    for (const cache of activeCaches) cache.cleanup();
-    updateCleanupInterval();
+    // `cleanup()` removes an emptied cache from the set as it goes.
+    for (const cache of [...sweptCaches]) cache.cleanup();
   }, 60_000);
   cleanupInterval.unref?.();
 }
 
 /** Unregister a cache without changing its entries or TTL behavior. */
 export function unregisterCacheFromCleanup(cache: TTLCache<unknown>): void {
-  activeCaches.delete(cache);
-  updateCleanupInterval();
+  cache.setSwept(false);
 }
 
 /**
@@ -297,9 +329,15 @@ export function unregisterCacheFromCleanup(cache: TTLCache<unknown>): void {
  * This will clear the interval and unregister all caches
  */
 export function stopAllCleanupIntervals(): void {
+  sweepGeneration += 1;
+  sweptCaches.clear();
   if (cleanupInterval) {
     clearInterval(cleanupInterval);
     cleanupInterval = null;
   }
-  activeCaches.clear();
+}
+
+/** How many caches the shared sweep currently holds (tests). @internal */
+export function sweptCacheCount(): number {
+  return sweptCaches.size;
 }