@bevel-software/platform-core-backend 0.30.0 → 0.32.0

package/src/modules/mcp/oauth/bevel-oauth-provider.ts

@@ -32,9 +32,27 @@ import { signAuthRequest, type McpAuthRequestState } from './oauth-state.js';
 // (`<tenant>-int_`).
 const TOKEN_BYTES = 32;
 
+/** A transaction's handle, for the statements a refresh must land together. */
+type Tx = Parameters<Parameters<Database['transaction']>[0]>[0];
+
 const ACCESS_TTL_MS = 60 * 60_000; // 1 hour
 const REFRESH_TTL_MS = 30 * 24 * 60 * 60_000; // 30 days, rotated on use
 const CODE_TTL_MS = 60_000; // exchanged within seconds of Finish
+/**
+ * How long a refresh token that was just rotated is honoured once more.
+ *
+ * Rotation makes a refresh token single-use, and a client that refreshes
+ * from two places at once — Claude's hosted apps refresh proactively before
+ * expiry AND reactively on a 401, and a scheduled task runs beside the chat
+ * that shares its connector — presents the same token twice. The second
+ * presentation used to be answered `invalid_grant`, which a client reads as
+ * "the credential is dead" and turns into a re-authorization prompt every
+ * day or two. Within this window the loser is answered as the winner was,
+ * with a fresh pair; past it, reuse is refused, which is what makes a stolen
+ * token's later replay fail. Sixty seconds is the window Okta allows at most
+ * and Auth0 recommends for exactly this case.
+ */
+const REFRESH_REUSE_GRACE_MS = 60_000;
 /**
  * How often, at most, one process stamps an agent connection's `last_used_at`.
  * The Audit log shows the instant relatively ("4 minutes ago"), so a minute's
@@ -261,34 +279,54 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     _resource?: URL,
   ): Promise<OAuthTokens> {
     const now = new Date();
-    // Rotation: atomically revoke the presented refresh token; the winner of
-    // a concurrent double-refresh gets the new pair, the loser a clean 400.
-    // `clientId` is IN the predicate so a caller presenting a valid refresh
-    // token under the WRONG client can't revoke (kill) another client's
-    // session — the update matches nothing and their token stays live.
-    const [row] = await this.deps.db
-      .update(oauthTokens)
-      .set({ revokedAt: now })
-      .where(
-        and(
-          eq(oauthTokens.refreshTokenHash, hashToken(refreshToken)),
-          eq(oauthTokens.clientId, client.client_id),
-          isNull(oauthTokens.revokedAt),
-        ),
-      )
-      .returning();
-    if (!row) {
-      throw new InvalidGrantError('Invalid or revoked refresh token');
+    const hash = hashToken(refreshToken);
+    const clientId = client.client_id;
+    // The row is READ first and judged whole, and consumed only once every
+    // check has passed: a refusal must leave a token the client could still
+    // use with a different request (a narrower scope) usable, and nothing
+    // may be minted or retired on a token that is expired, revoked, or
+    // bound to a revoked agent. Looked up by hash AND client, so a caller
+    // presenting a valid refresh token under the WRONG client learns
+    // nothing and changes nothing.
+    const [seen] = await this.deps.db
+      .select()
+      .from(oauthTokens)
+      .where(and(eq(oauthTokens.refreshTokenHash, hash), eq(oauthTokens.clientId, clientId)))
+      .limit(1);
+    if (!seen) return this.refuseRefresh('unknown refresh token for this client', 'Invalid or revoked refresh token', { clientId });
+    const rotatedAgoMs = seen.rotatedAt ? now.getTime() - seen.rotatedAt.getTime() : null;
+    const rotatedAgo = rotatedAgoMs === null ? null : `${Math.round(rotatedAgoMs / 1000)} s ago`;
+    if (seen.revokedAt) {
+      return this.refuseRefresh(
+        rotatedAgo ? `refresh token rotated ${rotatedAgo} and already replayed once, or revoked since` : 'refresh token revoked',
+        'Invalid or revoked refresh token',
+        seen,
+      );
+    }
+    if (rotatedAgoMs !== null && rotatedAgoMs > REFRESH_REUSE_GRACE_MS) {
+      return this.refuseRefresh(
+        `refresh token rotated ${rotatedAgo}, past the ${REFRESH_REUSE_GRACE_MS / 1000} s reuse grace`,
+        'Invalid or revoked refresh token',
+        seen,
+      );
     }
-    if (row.refreshExpiresAt && row.refreshExpiresAt <= now) {
-      throw new InvalidGrantError('Refresh token expired');
+    if (seen.refreshExpiresAt && seen.refreshExpiresAt <= now) {
+      return this.refuseRefresh('refresh token expired', 'Refresh token expired', seen);
     }
     // Scope may only narrow on refresh (RFC 6749 §6).
-    let scope = row.scope;
+    let scope = seen.scope;
     if (scopes?.length) {
-      const granted = new Set((row.scope ?? '').split(' ').filter(Boolean));
+      const granted = new Set((seen.scope ?? '').split(' ').filter(Boolean));
       if (!scopes.every((s) => granted.has(s))) {
-        throw new InvalidScopeError('Requested scope exceeds the originally granted scope');
+        // `invalid_scope` to the client (RFC 6749 §5.2), since the token
+        // itself is fine — and untouched, so the same token refreshes with
+        // the scope it was granted.
+        return this.refuseRefresh(
+          'requested scope exceeds the originally granted scope',
+          'Requested scope exceeds the originally granted scope',
+          seen,
+          (message) => new InvalidScopeError(message),
+        );
       }
       scope = scopes.join(' ');
     }
@@ -299,13 +337,115 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     // mint an unrevoked pair — the revoke undone by a millisecond. A token
     // from before connections existed has none to stay on and is placed
     // under one as a first mint would be.
-    if (row.connectionId) {
-      if (!(await this.isConnectionLive(row.connectionId))) {
-        throw new InvalidGrantError('Access for this agent was revoked');
+    if (seen.connectionId && !(await this.isConnectionLive(seen.connectionId))) {
+      return this.refuseRefresh('access for this agent was revoked', 'Access for this agent was revoked', seen);
+    }
+
+    // Consume, with the state the row was judged in as the predicate, so two
+    // refreshes racing on one row have exactly one winner. A fresh token is
+    // RETIRED (`rotatedAt`), not revoked: its pair's access token stays good
+    // until its own expiry, an hour at most, so a runner still holding it is
+    // not cut off mid-task by a refresh another runner made, while a revoke
+    // or a sign-out still ends it at once. A token already retired within
+    // the reuse grace — the loser of a double refresh, which is what a client
+    // refreshing from two places at once produces — is honoured ONCE more,
+    // and the replay revokes the row in the same statement that admits it,
+    // so a third presentation, or two replays racing, find nothing. That does
+    // end the retired pair's access token: the runner that replayed holds the
+    // fresh pair from here, and the rotation's winner holds its own.
+    //
+    // The consume and the mint are ONE transaction: a token is retired or
+    // replayed only in the same commit that hands its holder the new pair, so
+    // a mint that fails leaves the token exactly as it was — never spent with
+    // nothing to show for it, which for a replayed token would be the lockout
+    // this whole path exists to prevent. A token from before connections
+    // existed is placed under one first, outside the transaction, as a first
+    // mint would place it: finding or making a connection is idempotent.
+    const connectionId = seen.connectionId ?? (await this.ensureConnection(seen.userId, seen.clientId));
+    // The opportunistic prune too runs BEFORE the transaction opens, on the
+    // pool: inside it, this request would hold a transaction's client while
+    // waiting for a second one, and a burst of refreshes the size of the pool
+    // would have every one of them wait out the connect timeout.
+    await this.pruneTokenTables(now.getTime());
+    const { consumed, tokens, replayed } = await this.deps.db.transaction(async (tx) => {
+      let row = rotatedAgoMs === null ? await this.retireFresh(tx, hash, clientId, now) : undefined;
+      let replayed = rotatedAgoMs !== null;
+      if (!row) {
+        // Either a retired token within the grace, or a fresh one that lost
+        // its rotation to a concurrent refresh between the read above and the
+        // retire — which makes it the loser of a double refresh, and so
+        // replayable now.
+        row = await this.replayRetired(tx, hash, clientId, now);
+        replayed = true;
+      }
+      if (!row) {
+        return this.refuseRefresh('refresh token rotated or revoked by a concurrent request', 'Invalid or revoked refresh token', seen);
       }
-      this.noteConnectionUse(row.connectionId);
+      const tokens = await this.mintTokens(row.userId, row.clientId, scope, row.resource, connectionId, tx);
+      return { consumed: row, tokens, replayed };
+    });
+    if (replayed) {
+      log.info(
+        `refresh replayed ${Math.round((now.getTime() - consumed.rotatedAt!.getTime()) / 1000)} s after its rotation, within the reuse grace; a fresh pair is minted`,
+        { clientId, connectionId, userId: consumed.userId },
+      );
     }
-    return this.mintTokens(row.userId, row.clientId, scope, row.resource, row.connectionId ?? undefined);
+    this.noteConnectionUse(connectionId);
+    return tokens;
+  }
+
+  /** Retire a fresh refresh token: the one statement that wins a rotation. */
+  private async retireFresh(tx: Tx, hash: string, clientId: string, now: Date) {
+    const [row] = await tx
+      .update(oauthTokens)
+      .set({ rotatedAt: now })
+      .where(
+        and(
+          eq(oauthTokens.refreshTokenHash, hash),
+          eq(oauthTokens.clientId, clientId),
+          isNull(oauthTokens.revokedAt),
+          isNull(oauthTokens.rotatedAt),
+        ),
+      )
+      .returning();
+    return row;
+  }
+
+  /** Consume a retired refresh token's one replay: revoked in the statement that admits it, within the grace only. */
+  private async replayRetired(tx: Tx, hash: string, clientId: string, now: Date) {
+    const since = new Date(now.getTime() - REFRESH_REUSE_GRACE_MS);
+    const [row] = await tx
+      .update(oauthTokens)
+      .set({ revokedAt: now })
+      .where(
+        and(
+          eq(oauthTokens.refreshTokenHash, hash),
+          eq(oauthTokens.clientId, clientId),
+          isNull(oauthTokens.revokedAt),
+          gt(oauthTokens.rotatedAt, since),
+        ),
+      )
+      .returning();
+    return row;
+  }
+
+  /**
+   * The one place a refresh is refused: logged with its reason, never the
+   * token, then the client's error — `invalid_grant` unless the caller says
+   * otherwise (a widened scope is `invalid_scope`).
+   */
+  private refuseRefresh(
+    reason: string,
+    clientMessage: string,
+    row: { clientId: string; connectionId?: string | null; userId?: string },
+    error: (message: string) => Error = (message) => new InvalidGrantError(message),
+  ): never {
+    log.warn(`refresh refused: ${reason}`, {
+      clientId: row.clientId,
+      connectionId: row.connectionId ?? null,
+      userId: row.userId ?? null,
+    });
+    throw error(clientMessage);
   }
 
   async verifyAccessToken(token: string): Promise<AuthInfo> {
@@ -413,10 +553,15 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     // back to re-authorise into the same one.)
     const connectionId = revoked.find((r) => r.connectionId)?.connectionId;
     if (!connectionId) return;
+    // A rotated row is not a live token: its successor is the live one, and
+    // counting it would keep a connection open on a refresh token nobody can
+    // use any more.
     const [{ live }] = await this.deps.db
       .select({ live: count() })
       .from(oauthTokens)
-      .where(and(eq(oauthTokens.connectionId, connectionId), isNull(oauthTokens.revokedAt)));
+      .where(
+        and(eq(oauthTokens.connectionId, connectionId), isNull(oauthTokens.revokedAt), isNull(oauthTokens.rotatedAt)),
+      );
     if (Number(live) > 0) return;
     await this.deps.db
       .update(agentConnections)
@@ -428,6 +573,12 @@ export class BevelOAuthProvider implements OAuthServerProvider {
    * @param connectionId The agent connection the pair belongs to, when the
    *   caller already holds one (a refresh: the consumed token's). Absent on a
    *   first mint, which finds or makes the live connection for (user, client).
+   * @param tx The transaction the insert belongs to, when the mint must land
+   *   with the statement that consumed the token it replaces (a refresh).
+   *   The prune is then the caller's, before the transaction opens: a
+   *   best-effort statement that fails inside a transaction would abort the
+   *   mint it is meant to spare, and one on the pool from inside it would
+   *   hold this request's client while waiting for another.
    */
   private async mintTokens(
     userId: string,
@@ -435,30 +586,17 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     scope: string | null,
     resource: string | null,
     connectionId?: string,
+    tx?: Tx,
   ): Promise<OAuthTokens> {
     const accessToken = this.deps.tokenPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
     const refreshToken = this.refreshPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
     const now = Date.now();
-    // Opportunistic pruning, piggybacked on mint (one per sign-in / refresh —
-    // no scheduler needed) so the oauth tables stay bounded: a token row whose
-    // refresh window has closed can never authenticate again (revoked-but-live
-    // rows are kept until then, so revocation stays observable), and an auth
-    // code past its 60s TTL can never be exchanged. Best-effort — a cleanup
-    // hiccup must not fail the token issuance itself.
-    try {
-      const cutoff = new Date(now);
-      await this.deps.db.delete(oauthTokens).where(
-        or(
-          lt(oauthTokens.refreshExpiresAt, cutoff),
-          and(isNull(oauthTokens.refreshExpiresAt), lt(oauthTokens.expiresAt, cutoff)),
-        ),
-      );
-      await this.deps.db.delete(oauthAuthCodes).where(lt(oauthAuthCodes.expiresAt, cutoff));
-    } catch (err) {
-      log.warn('token-table prune failed (non-fatal):', { err });
-    }
+    // A mint of its own (a sign-in) prunes here; a refresh pruned before its
+    // transaction opened.
+    if (!tx) await this.pruneTokenTables(now);
     const boundTo = connectionId ?? (await this.ensureConnection(userId, clientId));
-    await this.deps.db.insert(oauthTokens).values({
+    const sink: Tx | Database = tx ?? this.deps.db;
+    await sink.insert(oauthTokens).values({
       accessTokenHash: hashToken(accessToken),
       refreshTokenHash: hashToken(refreshToken),
       clientId,
@@ -478,6 +616,34 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     };
   }
 
+  /**
+   * Opportunistic pruning, piggybacked on every mint (one per sign-in /
+   * refresh — no scheduler needed) so the oauth tables stay bounded: a token
+   * row whose refresh window has closed can never authenticate again
+   * (revoked-but-live rows are kept until then, so revocation stays
+   * observable), a rotated row can authenticate for its access token's hour
+   * and be replayed for the reuse grace and past both is history only, and
+   * an auth code past its 60s TTL can never be exchanged. Best-effort, on the
+   * pool and never inside a transaction — a cleanup hiccup must not fail the
+   * token issuance itself.
+   */
+  private async pruneTokenTables(now: number): Promise<void> {
+    try {
+      const cutoff = new Date(now);
+      const rotatedCutoff = new Date(now - ACCESS_TTL_MS - REFRESH_REUSE_GRACE_MS);
+      await this.deps.db.delete(oauthTokens).where(
+        or(
+          lt(oauthTokens.refreshExpiresAt, cutoff),
+          and(isNull(oauthTokens.refreshExpiresAt), lt(oauthTokens.expiresAt, cutoff)),
+          lt(oauthTokens.rotatedAt, rotatedCutoff),
+        ),
+      );
+      await this.deps.db.delete(oauthAuthCodes).where(lt(oauthAuthCodes.expiresAt, cutoff));
+    } catch (err) {
+      log.warn('token-table prune failed (non-fatal):', { err });
+    }
+  }
+
   /**
    * The live `agent_connections` row for (user, client) — found, or made on
    * the first mint for the pair. A refresh finds the row the sign-in made, so

package/src/modules/mcp/request-context.ts

@@ -0,0 +1,34 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { RequestAudit } from '../audit/index.js';
+
+/**
+ * What ONE MCP request brings to the tool client it runs on: the bearer its
+ * loopback calls carry, and the Audit log's view of it.
+ *
+ * The client is cached across requests (see {@link SurfaceCache}), so neither
+ * may live on the client. A connection-key request's loopback bearer is its
+ * own key — per-key metering rides on it, and a revoked key must stop working
+ * on its very next request even while the person's client is warm. An OAuth
+ * or session request's bearer is an internal token minted for that request,
+ * with a lifetime: baked into a cached client it would outlive nothing and
+ * expire under a page kept open for a day. So the client reads both from
+ * here, at call time, and a request supplies its own.
+ */
+export interface McpRequestContext {
+  /** The bearer this request's loopback calls carry (`${CONNECTION_KEY}` of every platform-hosted manual). */
+  loopbackBearer: string;
+  /** The request's Audit log view, or null when the request is attributed to nothing. */
+  audit: RequestAudit | null;
+}
+
+const storage = new AsyncLocalStorage<McpRequestContext>();
+
+/** Run `fn` as part of the request `ctx`: every tool call it makes, however deep, reads `ctx`. */
+export function runInRequest<T>(ctx: McpRequestContext, fn: () => T): T {
+  return storage.run(ctx, fn);
+}
+
+/** The request the current call belongs to, or undefined outside one. */
+export function currentRequest(): McpRequestContext | undefined {
+  return storage.getStore();
+}

package/src/modules/mcp/shared-definitions.ts

@@ -0,0 +1,121 @@
+import { createHash } from 'node:crypto';
+import type { CallTemplate, Tool as UtcpTool } from '@utcp/sdk';
+import type { CodeModeUtcpClient } from '@utcp/code-mode';
+import type { ProxiedTool } from '@bevel-software/platform-mcp-core';
+
+/**
+ * Tool definitions held once for every cached client that discovered the same
+ * ones.
+ *
+ * Two hundred people whose catalogs are identical would otherwise hold two
+ * hundred copies of the same descriptions and schemas: a client's repository
+ * keeps what discovery parsed, and every build parses its own. After a build,
+ * each manual's discovered tools are swapped for the first copy of identical
+ * tools this process has seen, so the descriptions, schemas and call templates
+ * are one object graph no matter how many clients point at it. A client keeps
+ * only what is its own: the repository's per-tool shells, its variables and
+ * its secrets loader.
+ *
+ * Identity is the CONTENT of the definitions, not the manual's name or its
+ * template: the knowledge base's manual is filtered per caller, so two people
+ * can get different tools from the same template, and only identical content
+ * may be shared. Definitions are tool schemas and call TEMPLATES — `${VAR}`
+ * placeholders, never a resolved value — so sharing them shares no secret.
+ *
+ * Nothing here is read back for correctness: a definition dropped from these
+ * maps (they are bounded) only stops the NEXT build from sharing it.
+ */
+export class SharedDefinitions {
+  private readonly byContent = new Map<string, unknown>();
+  private readonly interfaceCaches = new Map<string, Map<string, string>>();
+
+  /** `maxEntries` bounds each map; 0 shares nothing. */
+  constructor(private readonly maxEntries = 1000) {}
+
+  /**
+   * The first-seen copy of `value` (by its JSON), or `value` itself when it is
+   * the first. Kinds share no key space: a tool list and a listing could
+   * otherwise serialise alike.
+   */
+  intern<T>(kind: string, value: T): T {
+    const key = `${kind}\u0000${fingerprint(value)}`;
+    const held = this.byContent.get(key);
+    if (held !== undefined) {
+      // Recently used goes last, so the first entry is the one to drop.
+      this.byContent.delete(key);
+      this.byContent.set(key, held);
+      return held as T;
+    }
+    if (this.maxEntries <= 0) return value;
+    bound(this.byContent, this.maxEntries);
+    this.byContent.set(key, value);
+    return value;
+  }
+
+  /**
+   * Point `client`'s repository at shared definitions: every manual's tools,
+   * and the client's cache of generated TypeScript interfaces.
+   *
+   * `rawTemplates` are the manuals as fetched, by the name they are registered
+   * under. Registration stores the template AFTER variable substitution — for
+   * a platform-hosted manual, with the bearer of the request that built the
+   * client in its headers. Nothing calls through a stored template (each
+   * tool's own template is substituted at call time), but a cached client
+   * must hold no request's credential, so the stored template is put back to
+   * its placeholders.
+   */
+  async share(client: CodeModeUtcpClient, rawTemplates: ReadonlyMap<string, CallTemplate>): Promise<void> {
+    const repo = client.config.tool_repository;
+    const templates = await repo.getManualCallTemplates();
+    const everyTool: UtcpTool[] = [];
+    for (const stored of templates) {
+      const name = String(stored.name ?? '');
+      const manual = await repo.getManual(name);
+      if (!manual) continue;
+      const tools = this.intern('tools', manual.tools);
+      everyTool.push(...tools);
+      const raw = rawTemplates.get(name);
+      const template = raw ? ({ ...raw, name } as CallTemplate) : stored;
+      await repo.saveManual(template, { ...manual, tools });
+    }
+    // `toolFunctionCache` is filled lazily by `tools_info` and every chain,
+    // keyed by tool name and derived from the definitions alone. Shared by
+    // every client holding the very same tool set, it is generated once for
+    // all of them instead of once per person.
+    (client as unknown as { toolFunctionCache: Map<string, string> }).toolFunctionCache = this.interfaceCache(
+      fingerprint(everyTool),
+    );
+  }
+
+  /** The flattened catalog a surface lists, shared the same way. */
+  listing(tools: ProxiedTool[]): ProxiedTool[] {
+    return this.intern('listing', tools);
+  }
+
+  /** The generated-interface cache of one exact tool set. */
+  private interfaceCache(toolSet: string): Map<string, string> {
+    let cache = this.interfaceCaches.get(toolSet);
+    if (cache) {
+      this.interfaceCaches.delete(toolSet);
+    } else {
+      cache = new Map();
+      if (this.maxEntries <= 0) return cache;
+      bound(this.interfaceCaches, this.maxEntries);
+    }
+    this.interfaceCaches.set(toolSet, cache);
+    return cache;
+  }
+}
+
+/** Make room for one more entry, dropping the least recently used. */
+function bound(map: Map<string, unknown>, maxEntries: number): void {
+  while (map.size >= maxEntries) {
+    const oldest = map.keys().next().value;
+    if (oldest === undefined) break;
+    map.delete(oldest);
+  }
+}
+
+function fingerprint(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}

package/src/modules/mcp/surface-cache.ts

@@ -0,0 +1,154 @@
+/**
+ * The hosted MCP server's memory of built tool surfaces: one per caller and
+ * catalog revision, built once and reused until something it was built from
+ * changes.
+ *
+ * Keyed by whatever the service says identifies a surface — the person, the
+ * kind of caller, the key's scope and the catalog revision. A catalog change
+ * needs no listener: it is a new revision, so a new key, and the old entry
+ * ages out unused. What the revision cannot see (a secret) is evicted
+ * explicitly through {@link evictWhere} / {@link clear}.
+ *
+ * Bounded twice: an entry unused for `idleTtlMs` is dropped, and at most
+ * `maxEntries` are held, the least recently used going first. `maxEntries: 0`
+ * keeps nothing, which is the per-request build this replaced: the escape
+ * hatch if the cache ever has to be switched off.
+ *
+ * Single-flight: concurrent misses on one key share one build. A build that
+ * fails is not remembered, so the next request tries again. A build that was
+ * in flight when its key was evicted answers the requests waiting on it but is
+ * not kept: it was built from what the eviction said is stale. A build still
+ * running after `buildTimeoutMs` is let go the same way, so a discovery that
+ * hangs holds up the requests already waiting on it, not every later one.
+ *
+ * Holds references only. A surface owns no connection (its `mcp` manuals route
+ * to the downstream pool, which owns and closes those), so dropping an entry
+ * is the whole teardown.
+ */
+export interface SurfaceCacheOptions {
+  /** Drop an entry unused for this long. Default one hour. */
+  idleTtlMs?: number;
+  /** Hold at most this many entries. Default 500; 0 keeps nothing. */
+  maxEntries?: number;
+  /** Let go of a build still running after this long; the next request starts another. Default two minutes. */
+  buildTimeoutMs?: number;
+  /** Clock, for tests. */
+  now?: () => number;
+}
+
+export const SURFACE_IDLE_TTL_MS = 60 * 60 * 1000;
+export const SURFACE_BUILD_TIMEOUT_MS = 2 * 60 * 1000;
+export const SURFACE_MAX_ENTRIES = 500;
+
+interface Entry<V> {
+  value: Promise<V>;
+  startedAt: number;
+  lastUsed: number;
+  /** An absolute end, for a value that must not live its full idle time (see `maxAgeMs`). */
+  expiresAt: number;
+  /** False once the entry was evicted while its build was still running. */
+  live: boolean;
+  settled: boolean;
+}
+
+export class SurfaceCache<V> {
+  private readonly entries = new Map<string, Entry<V>>();
+  private readonly idleTtlMs: number;
+  private readonly maxEntries: number;
+  private readonly buildTimeoutMs: number;
+  private readonly now: () => number;
+
+  constructor(opts: SurfaceCacheOptions = {}) {
+    this.idleTtlMs = opts.idleTtlMs ?? SURFACE_IDLE_TTL_MS;
+    this.maxEntries = opts.maxEntries ?? SURFACE_MAX_ENTRIES;
+    this.buildTimeoutMs = opts.buildTimeoutMs ?? SURFACE_BUILD_TIMEOUT_MS;
+    this.now = opts.now ?? Date.now;
+  }
+
+  /**
+   * The value for `key`, built by `build` when none is held. `hit` says
+   * whether this call found one (or joined a build already running).
+   *
+   * `maxAgeMs`, read off a built value, ends that entry early whatever its
+   * use: a surface built while one of its manuals was failing is kept only
+   * as long as that failure would be remembered anyway.
+   */
+  async get(
+    key: string,
+    build: () => Promise<V>,
+    maxAgeMs?: (value: V) => number | undefined,
+  ): Promise<{ value: V; hit: boolean }> {
+    this.sweep();
+    const now = this.now();
+    const held = this.entries.get(key);
+    if (held) {
+      held.lastUsed = now;
+      // Most recently used goes last, so the first entry is always the one to drop.
+      this.entries.delete(key);
+      this.entries.set(key, held);
+      return { value: await held.value, hit: true };
+    }
+    if (this.maxEntries <= 0) return { value: await build(), hit: false };
+    while (this.entries.size >= this.maxEntries) {
+      const oldest = this.entries.keys().next().value;
+      if (oldest === undefined) break;
+      this.drop(oldest);
+    }
+    const entry: Entry<V> = {
+      value: build(),
+      startedAt: now,
+      lastUsed: now,
+      expiresAt: Number.POSITIVE_INFINITY,
+      live: true,
+      settled: false,
+    };
+    this.entries.set(key, entry);
+    try {
+      const value = await entry.value;
+      entry.settled = true;
+      const maxAge = maxAgeMs?.(value);
+      if (maxAge !== undefined) entry.expiresAt = this.now() + maxAge;
+      if (!entry.live) this.forget(key, entry);
+      return { value, hit: false };
+    } catch (err) {
+      this.forget(key, entry);
+      throw err;
+    }
+  }
+
+  /** Drop every entry whose key matches. A build in flight still answers its waiters, and is not kept. */
+  evictWhere(predicate: (key: string) => boolean): void {
+    for (const key of [...this.entries.keys()]) {
+      if (predicate(key)) this.drop(key);
+    }
+  }
+
+  /** Drop everything. */
+  clear(): void {
+    this.evictWhere(() => true);
+  }
+
+  private drop(key: string): void {
+    const entry = this.entries.get(key);
+    if (!entry) return;
+    entry.live = false;
+    this.entries.delete(key);
+  }
+
+  /** Remove `entry` only if it is still the one under `key` (a newer build may have taken its place). */
+  private forget(key: string, entry: Entry<V>): void {
+    if (this.entries.get(key) === entry) this.entries.delete(key);
+  }
+
+  /** Drop what has been idle too long, or outlived its own end, and let go of a build that has run too long. */
+  private sweep(): void {
+    const now = this.now();
+    for (const [key, entry] of this.entries) {
+      if (!entry.settled) {
+        if (now - entry.startedAt >= this.buildTimeoutMs) this.drop(key);
+        continue;
+      }
+      if (now - entry.lastUsed >= this.idleTtlMs || now >= entry.expiresAt) this.drop(key);
+    }
+  }
+}