mcpose 2.0.2 → 3.0.0

package/src/delegation.ts

@@ -0,0 +1,224 @@
+/**
+ * The delegation chain wire format: how a chain crosses the wire in
+ * `params._meta` and how it is read back (ADR-0016).
+ *
+ * The chain is attribution, never authorization. A presented chain is
+ * written by the previous hop and is attacker-influenced at the boundary,
+ * so `roles` and `claims` never travel on the wire and are never taken
+ * from one: extraction produces identities with empty roles and claims,
+ * unconditionally.
+ */
+import { ErrorCode, type McpError } from '@modelcontextprotocol/sdk/types.js';
+import type { Identity } from './identity.js';
+import { outboundDelegationChain, type ProxyContext } from './proxyContext.js';
+import { rejectionMcpError } from './rejection.js';
+
+/**
+ * The `params._meta` key carrying the delegation chain. Exported so a host
+ * attaching {@link outboundDelegationChain} to its own outbound MCP calls
+ * uses the same key core does.
+ */
+// A public wire constant, not a credential: the trailing allow keeps
+// gitleaks' generic-api-key rule from matching the `_KEY` name.
+export const DELEGATION_META_KEY = 'mcpose/delegation'; // gitleaks:allow
+
+/** The only wire version this proxy parses or emits. */
+const WIRE_VERSION = 1;
+
+/**
+ * Parse bound on a presented chain, not the hop-count policy knob ADR-0011
+ * rejected: it constrains what this proxy will parse, not what host
+ * outbound code does.
+ */
+const MAX_CHAIN_ENTRIES = 32;
+
+const IDENTITY_TYPES = ['human', 'agent', 'service'] as const;
+const IDENTITY_SOURCES = ['jwt', 'mtls', 'apikey', 'custom'] as const;
+
+const ISO_8601 =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+/** One entry of the wire chain: no `roles`, no `claims`, ever. */
+export interface DelegationWireEntry {
+  sub: string;
+  type: Identity['type'];
+  displayName?: string;
+  resolvedAt?: string;
+  source?: Identity['source'];
+}
+
+/** The versioned payload carried at `params._meta["mcpose/delegation"]`. */
+export interface DelegationWirePayload {
+  v: number;
+  chain: DelegationWireEntry[];
+}
+
+/** What reading the inbound payload produced. Both fields absent means "no chain". */
+export interface InboundDelegation {
+  /** The presented chain, oldest-first. Absent when there was none. */
+  chain?: Identity[];
+  /**
+   * The rejection a malformed payload earned. Thrown inside the pipeline by
+   * the caller, so observing middleware records the attempt.
+   */
+  error?: McpError;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isIsoTimestamp(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    ISO_8601.test(value) &&
+    !Number.isNaN(Date.parse(value))
+  );
+}
+
+function rejection(detail: string): McpError {
+  return rejectionMcpError(
+    'DELEGATION_INVALID',
+    ErrorCode.InvalidRequest,
+    `Invalid delegation chain: ${detail}`,
+  );
+}
+
+function invalid(detail: string): InboundDelegation {
+  return { error: rejection(detail) };
+}
+
+/**
+ * Serializes a chain to its wire payload, dropping `roles` and `claims`.
+ *
+ * Exported for hosts that attach {@link outboundDelegationChain} to their own
+ * outbound MCP calls from a local tool handler, which ADR-0011 leaves to the
+ * host because outbound host code may not be MCP at all.
+ */
+export function serializeDelegationChain(
+  chain: ReadonlyArray<Identity>,
+): DelegationWirePayload {
+  return {
+    v: WIRE_VERSION,
+    chain: chain.map((identity) => ({
+      sub: identity.sub,
+      type: identity.type,
+      ...(identity.displayName === undefined
+        ? {}
+        : { displayName: identity.displayName }),
+      resolvedAt: identity.resolvedAt,
+      source: identity.source,
+    })),
+  };
+}
+
+/**
+ * Reads the chain from a raw request, before the ADR-0008 request-`_meta`
+ * strip runs: read first, strip second, or the marker never survives a
+ * chained proxy (the ADR-0011 boundary-ordering constraint).
+ *
+ * An absent payload is not an error. A present-but-malformed one is, and is
+ * returned rather than thrown so the caller can throw it inside the pipeline.
+ */
+export function readInboundDelegation(req: {
+  params?: { _meta?: unknown } | undefined;
+}): InboundDelegation {
+  const meta = req.params?._meta;
+  const payload = isRecord(meta) ? meta[DELEGATION_META_KEY] : undefined;
+  if (payload === undefined) return {};
+  if (!isRecord(payload)) return invalid('payload is not an object');
+  if (payload.v !== WIRE_VERSION) {
+    return invalid(`unsupported version ${JSON.stringify(payload.v)}`);
+  }
+  const wireChain = payload.chain;
+  if (!Array.isArray(wireChain)) return invalid('chain is not an array');
+  if (wireChain.length > MAX_CHAIN_ENTRIES) {
+    return invalid(`chain exceeds ${MAX_CHAIN_ENTRIES} entries`);
+  }
+
+  const receivedAt = new Date().toISOString();
+  const chain: Identity[] = [];
+  for (const entry of wireChain as unknown[]) {
+    if (!isRecord(entry)) return invalid('an entry is not an object');
+    const { sub, type } = entry;
+    if (typeof sub !== 'string' || sub === '') {
+      return invalid('an entry has no sub');
+    }
+    if (!IDENTITY_TYPES.includes(type as Identity['type'])) {
+      return invalid(`entry ${JSON.stringify(sub)} has an unknown type`);
+    }
+    chain.push({
+      sub,
+      type: type as Identity['type'],
+      ...(typeof entry.displayName === 'string'
+        ? { displayName: entry.displayName }
+        : {}),
+      // Attribution, never authorization: whatever the wire claimed here is
+      // discarded, so a presented chain cannot smuggle a privilege.
+      roles: [],
+      claims: {},
+      resolvedAt: isIsoTimestamp(entry.resolvedAt)
+        ? entry.resolvedAt
+        : receivedAt,
+      source: IDENTITY_SOURCES.includes(entry.source as Identity['source'])
+        ? (entry.source as Identity['source'])
+        : 'custom',
+    });
+  }
+  // An empty presented chain says the same thing as no chain at all, and
+  // leaving `delegatedFrom` unset keeps it either absent or non-empty.
+  return chain.length === 0 ? {} : { chain };
+}
+
+/**
+ * Detects a chain that loops back through this proxy: the sub of the identity
+ * it resolved for the caller already appears in the chain that caller
+ * presents, so the call has cycled (ADR-0016).
+ *
+ * Runs after identity resolution and returns the rejection rather than
+ * throwing it, so the caller throws it inside the pipeline and the audit
+ * trail records the attempt against the identity that tripped it.
+ *
+ * With no resolved identity there is nothing to look for, which is the stdio
+ * case: only the structural validation in {@link readInboundDelegation}
+ * applies there. Core sees only the calls it forwards itself, so a cycle that
+ * closes through a local tool handler's own outbound call is outside this
+ * check, exactly as ADR-0011 said a partial control must admit.
+ */
+export function detectDelegationLoop(
+  context: ProxyContext,
+): McpError | undefined {
+  const sub = context.identity?.sub;
+  if (sub === undefined) return undefined;
+  const looped = (context.delegatedFrom ?? []).some(
+    (entry) => entry.sub === sub,
+  );
+  return looped
+    ? rejection(`the caller ${JSON.stringify(sub)} is already in the chain`)
+    : undefined;
+}
+
+/**
+ * Attaches the chain this proxy can vouch for to a forwarded request's
+ * params, closing the loop for a chained proxy: the inbound strip removes
+ * the caller's copy, and core re-attaches the extended chain (ADR-0016).
+ *
+ * A no-op when the outbound chain is empty, so a proxy with no identity and
+ * no inbound chain forwards params untouched.
+ */
+export function attachDelegationMeta<P>(params: P, context: ProxyContext): P {
+  const chain = outboundDelegationChain(context);
+  if (chain.length === 0) return params;
+  const existing = (params as { _meta?: Record<string, unknown> } | undefined)
+    ?._meta;
+  // P is inferred from the call site, so the result is exactly the params
+  // shape the callee expects, plus a `_meta` every request type allows —
+  // which the compiler cannot prove for an unresolved generic.
+  return {
+    ...params,
+    _meta: {
+      ...existing,
+      [DELEGATION_META_KEY]: serializeDelegationChain(chain),
+    },
+  };
+}

package/src/eventStore.ts

@@ -0,0 +1,106 @@
+import type {
+  EventStore,
+  EventId,
+  StreamId,
+} from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * Plug in a persistent event store to support SSE reconnect replay across
+ * restarts or load-balanced instances. Re-exports the SDK's `EventStore`
+ * interface — any implementation satisfying it is compatible.
+ *
+ * For single-instance deployments, use {@link createInMemoryEventStore}.
+ * For production (multi-instance, HA), implement against Redis or Postgres.
+ */
+export type { EventStore as PersistentEventStore };
+
+/**
+ * In-memory EventStore — default for single-instance deployments.
+ * Dropped connections can replay missed notifications on reconnect.
+ * Events are evicted FIFO once `maxEvents` is reached.
+ */
+export function createInMemoryEventStore(maxEvents = 1000): EventStore {
+  const store = new Map<
+    EventId,
+    { streamId: StreamId; message: JSONRPCMessage }
+  >();
+  let seq = 0;
+
+  return {
+    async storeEvent(streamId, message) {
+      const id = String(++seq);
+      store.set(id, { streamId, message });
+      if (store.size > maxEvents) {
+        store.delete(store.keys().next().value!);
+      }
+      return id;
+    },
+
+    async getStreamIdForEventId(eventId) {
+      return store.get(eventId)?.streamId;
+    },
+
+    async replayEventsAfter(lastEventId, { send }) {
+      // Unknown or malformed Last-Event-ID (or one already evicted): replay
+      // nothing rather than the whole buffer.
+      const origin = store.get(lastEventId);
+      if (!origin) return '';
+
+      const afterSeq = parseInt(lastEventId, 10);
+      for (const [id, { streamId, message }] of store) {
+        if (streamId === origin.streamId && parseInt(id, 10) > afterSeq) {
+          await send(id, message);
+        }
+      }
+      return origin.streamId;
+    },
+  };
+}
+
+/**
+ * Namespaces every stream id by session before it reaches the store.
+ *
+ * The SDK gives every session's standalone SSE stream the literal id
+ * `_GET_stream`, so one store shared by many sessions would otherwise keep
+ * their standalone-stream history under one key and a `Last-Event-ID` from
+ * one session would replay another's events (#154). Prefixing the stream id
+ * with the session id keeps each session's history apart, and a cursor that
+ * belongs to another session is reported as unknown, which the transport
+ * turns into a 400.
+ */
+export function scopeEventStore(
+  store: EventStore,
+  sessionId: string,
+): EventStore {
+  const prefix = `${sessionId}:`;
+  const own = (streamId: StreamId | undefined): StreamId | undefined =>
+    streamId?.startsWith(prefix) ? streamId.slice(prefix.length) : undefined;
+
+  return {
+    storeEvent: (streamId, message) =>
+      store.storeEvent(prefix + streamId, message),
+
+    getStreamIdForEventId: async (eventId) =>
+      own(await streamIdOf(store, eventId)),
+
+    async replayEventsAfter(lastEventId, { send }) {
+      if (own(await streamIdOf(store, lastEventId)) === undefined) return '';
+      return own(await store.replayEventsAfter(lastEventId, { send })) ?? '';
+    },
+  };
+}
+
+// ponytail: a store without `getStreamIdForEventId` (none of ours) is asked
+// to replay into a sink once to learn the owner; give it that method if the
+// double replay ever matters.
+async function streamIdOf(
+  store: EventStore,
+  eventId: EventId,
+): Promise<StreamId | undefined> {
+  if (store.getStreamIdForEventId) return store.getStreamIdForEventId(eventId);
+  const streamId = await store.replayEventsAfter(eventId, {
+    send: async () => undefined,
+  });
+  return streamId === '' ? undefined : streamId;
+}

package/src/hiddenTools.ts

@@ -0,0 +1,84 @@
+/**
+ * Predicate form of `ProxyOptions.hiddenTools`, closing the dispatcher
+ * bypass a name-only blocklist cannot see (a meta-tool that takes the real
+ * tool name as an argument). See ADR-0006.
+ */
+
+/**
+ * Decides whether a tool is hidden.
+ *
+ * `args` carries the phase: `undefined` during list filtering (a listed
+ * tool has no arguments), and always an object at call time (empty when
+ * the client sent none). That distinction lets a predicate keep a
+ * dispatcher visible in `tools/list` while failing closed on a dispatcher
+ * call whose target argument is missing.
+ */
+export type HiddenToolPredicate = (
+  name: string,
+  args: Readonly<Record<string, unknown>> | undefined,
+) => boolean;
+
+/** Options for {@link dispatcherAwareBlock}. */
+export interface DispatcherAwareBlockOptions {
+  /** Tool names to hide, whether called directly or through a dispatcher. */
+  tools: ReadonlyArray<string>;
+  /** Dispatcher (meta-tool) names whose target argument is checked. */
+  dispatchers: ReadonlyArray<string>;
+  /** Path to the target tool name inside the dispatcher's arguments. Dotted paths are supported, e.g. `'request.tool.name'`. */
+  argPath: string;
+}
+
+/**
+ * Resolves a dotted path through own enumerable-or-not plain-object keys.
+ * Traversing a non-object, an array, or a prototype key (e.g.
+ * `constructor`) resolves to `undefined` — the caller fails closed.
+ */
+function resolveArgPath(
+  args: Readonly<Record<string, unknown>>,
+  path: string,
+): unknown {
+  let current: unknown = args;
+  for (const key of path.split('.')) {
+    if (
+      current === null ||
+      typeof current !== 'object' ||
+      Array.isArray(current) ||
+      !Object.hasOwn(current, key)
+    ) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+/**
+ * A {@link HiddenToolPredicate} that blocks the listed tools both directly
+ * and through the listed dispatchers.
+ *
+ * Fail-closed: a dispatcher call whose target argument is missing, `null`,
+ * a number, an object, or an array is blocked, as is one whose `argPath`
+ * cannot be resolved. The dispatcher itself stays listed in `tools/list`
+ * and callable with a permitted target.
+ *
+ * @example
+ * hiddenTools: dispatcherAwareBlock({
+ *   tools: ['update_issue', 'delete_issue'],
+ *   dispatchers: ['execute_sentry_tool'],
+ *   argPath: 'name',
+ * })
+ */
+export function dispatcherAwareBlock(
+  options: DispatcherAwareBlockOptions,
+): HiddenToolPredicate {
+  const blocked = new Set(options.tools);
+  const dispatchers = new Set(options.dispatchers);
+
+  return (name, args) => {
+    if (blocked.has(name)) return true;
+    // args === undefined is the list phase: the dispatcher stays listed.
+    if (args === undefined || !dispatchers.has(name)) return false;
+    const target = resolveArgPath(args, options.argPath);
+    return typeof target !== 'string' || blocked.has(target);
+  };
+}

package/src/identity.ts

@@ -0,0 +1,15 @@
+/** Who made the request — resolved once per session via {@link resolveIdentity}. */
+export interface Identity {
+  /** Stable unique identifier (e.g. OIDC `sub` claim). */
+  sub: string;
+  /** Whether the caller is a human user, an AI agent, or an automated service. */
+  type: 'human' | 'agent' | 'service';
+  displayName?: string;
+  roles: string[];
+  /** Arbitrary claims from the resolved identity source (JWT payload, cert CN, etc.). */
+  claims: Record<string, unknown>;
+  /** ISO 8601 timestamp of when identity was resolved. */
+  resolvedAt: string;
+  /** Which resolver produced this identity. */
+  source: 'jwt' | 'mtls' | 'apikey' | 'custom';
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+export type { Middleware } from './middleware.js';
+export { compose, markPassThroughObserver } from './middleware.js';
+
+export type { BackendConfig, BackendClient } from './backendClient.js';
+export { createBackendClient } from './backendClient.js';
+
+export type { Identity } from './identity.js';
+
+export type {
+  ProxyContext,
+  ProxyIdentity,
+  PolicyDecision,
+} from './proxyContext.js';
+export { createProxyContext, outboundDelegationChain } from './proxyContext.js';
+
+export type {
+  TelemetryEvent,
+  ToolCallTelemetryEvent,
+  BackendDegradedTelemetryEvent,
+} from './telemetry.js';
+
+export type { Backends } from './mesh.js';
+
+export type { PersistentEventStore } from './eventStore.js';
+export { createInMemoryEventStore } from './eventStore.js';
+
+export type { SessionRecord, SessionRegistry } from './sessionRegistry.js';
+
+export type {
+  DelegationWireEntry,
+  DelegationWirePayload,
+} from './delegation.js';
+export { DELEGATION_META_KEY, serializeDelegationChain } from './delegation.js';
+
+export type { RejectionReason } from './rejection.js';
+export { rejectionMcpError } from './rejection.js';
+
+export type {
+  HiddenToolPredicate,
+  DispatcherAwareBlockOptions,
+} from './hiddenTools.js';
+export { dispatcherAwareBlock } from './hiddenTools.js';
+
+export type { SanitizeToolDescriptionsOptions } from './sanitizeCatalog.js';
+export { sanitizeToolDescriptions } from './sanitizeCatalog.js';
+
+export type {
+  ProxyOptions,
+  HttpProxyOptions,
+  LocalTool,
+  ToolMiddleware,
+  ResourceMiddleware,
+  PromptMiddleware,
+  ListToolsMiddleware,
+  ToolResultHandlers,
+} from './core.js';
+export {
+  hasToolContent,
+  mapToolResult,
+  createProxyServer,
+  startProxy,
+  startHttpProxy,
+} from './core.js';

package/src/mesh.ts

@@ -0,0 +1,204 @@
+/**
+ * Multi-backend (mesh) composition: backend-key validation, namespacing,
+ * routing, and failure-isolated listing. See ADR-0013.
+ */
+import type { BackendClient } from './backendClient.js';
+
+/**
+ * Separates a backend key from the upstream name in mesh mode:
+ * `<backendKey>__<name>`. A key may not contain it, so the first occurrence
+ * always splits the two, even when the upstream name contains one itself.
+ */
+const BACKEND_NAMESPACE_SEPARATOR = '__';
+
+/**
+ * A backend key is an identifier: it is spliced into tool and prompt names
+ * and, for resources, into the authority of a `mcpose://<key>/<uri>` URI
+ * (ADR-0022), so it is limited to what both a name and a URI host accept.
+ */
+const BACKEND_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/**
+ * The scheme a mesh exposes upstream resources under. The key is the
+ * authority and the upstream URI follows verbatim as the path, so the
+ * original is recovered by stripping a fixed prefix and never parsed.
+ */
+const RESOURCE_SCHEME = 'mcpose://';
+
+/**
+ * Pages drained from one backend before the proxy gives up on it. A backend
+ * that never advances its cursor would otherwise hang the whole list.
+ */
+const MAX_PAGES_PER_BACKEND = 100;
+
+/** One named upstream of a mesh. */
+export interface MeshEntry {
+  readonly key: string;
+  readonly client: BackendClient;
+}
+
+/**
+ * Either a single upstream (1:1 proxy, no namespacing) or a record of named
+ * backends keyed by backend key (mesh mode). See ADR-0013.
+ */
+export type Backends = BackendClient | Readonly<Record<string, BackendClient>>;
+
+const isBackendClient = (backends: Backends): backends is BackendClient =>
+  typeof (backends as BackendClient).getServerCapabilities === 'function';
+
+/**
+ * Normalizes the `backends` argument to an ordered entry list. The 1:1 form
+ * yields a single entry with an empty key and `mesh: false`.
+ *
+ * @throws On an empty record, an empty backend key, or a key containing the
+ * namespace separator — each would make an exposed name ambiguous, and
+ * guessing which upstream a caller meant is the failure mesh routing exists
+ * to prevent.
+ */
+export function normalizeBackends(backends: Backends): {
+  mesh: boolean;
+  entries: ReadonlyArray<MeshEntry>;
+} {
+  if (isBackendClient(backends)) {
+    return { mesh: false, entries: [{ key: '', client: backends }] };
+  }
+
+  const entries = Object.entries(backends).map(([key, client]) => ({
+    key,
+    client,
+  }));
+
+  if (entries.length === 0) {
+    throw new Error(
+      'mcpose: backends record is empty — pass at least one named backend, or a single BackendClient for a 1:1 proxy.',
+    );
+  }
+  for (const { key } of entries) {
+    if (key === '') {
+      throw new Error('mcpose: backend key must not be empty');
+    }
+    if (key.includes(BACKEND_NAMESPACE_SEPARATOR)) {
+      throw new Error(
+        `mcpose: backend key "${key}" must not contain "${BACKEND_NAMESPACE_SEPARATOR}" — it is the namespace separator`,
+      );
+    }
+    if (!BACKEND_KEY.test(key)) {
+      throw new Error(
+        `mcpose: backend key "${key}" must be an identifier (letters, digits, ".", "_" and "-", starting with a letter or digit) — it names the backend inside tool names and resource URIs`,
+      );
+    }
+  }
+
+  return { mesh: true, entries };
+}
+
+/** Namespaces a listed tool or prompt as `<key>__<name>`. */
+export function namespaceName<Item extends { name: string }>(
+  key: string,
+  item: Item,
+): Item {
+  return { ...item, name: `${key}${BACKEND_NAMESPACE_SEPARATOR}${item.name}` };
+}
+
+/**
+ * Exposes a listed resource as `mcpose://<key>/<uri>`. The upstream URI is
+ * appended untouched, so what the client holds is still one valid URI whose
+ * only meaning is "read me through this proxy", exactly as opaque as before.
+ */
+export function namespaceUri<Item extends { uri: string }>(
+  key: string,
+  item: Item,
+): Item {
+  return { ...item, uri: `${RESOURCE_SCHEME}${key}/${item.uri}` };
+}
+
+/**
+ * Resolves an exposed resource URI to its backend and upstream URI.
+ *
+ * Returns `undefined` for a URI not under `mcpose://`, an unknown key, or an
+ * empty upstream URI, and the caller rejects it as `BACKEND_UNROUTABLE`:
+ * there is no "which backend listed this URI" lookup, for the same reason
+ * tool names get no single-backend fallback.
+ */
+export function routeResourceUri(
+  uri: string,
+  byKey: ReadonlyMap<string, BackendClient>,
+): { client: BackendClient; uri: string } | undefined {
+  if (!uri.startsWith(RESOURCE_SCHEME)) return undefined;
+  const rest = uri.slice(RESOURCE_SCHEME.length);
+  const slash = rest.indexOf('/');
+  if (slash <= 0) return undefined;
+  const client = byKey.get(rest.slice(0, slash));
+  const upstreamUri = rest.slice(slash + 1);
+  if (client === undefined || upstreamUri === '') return undefined;
+  return { client, uri: upstreamUri };
+}
+
+/**
+ * Resolves an exposed name to its backend and upstream name.
+ *
+ * Returns `undefined` for an un-namespaced name, an unknown key, or an empty
+ * upstream name. The caller turns that into a loud `BACKEND_UNROUTABLE`
+ * rejection: there is deliberately no "resolve it if only one backend has
+ * that name" fallback, because it silently re-routes once a backend is added.
+ */
+export function routeNamespaced(
+  name: string,
+  byKey: ReadonlyMap<string, BackendClient>,
+): { client: BackendClient; name: string } | undefined {
+  const at = name.indexOf(BACKEND_NAMESPACE_SEPARATOR);
+  if (at <= 0) return undefined;
+  const client = byKey.get(name.slice(0, at));
+  const upstreamName = name.slice(at + BACKEND_NAMESPACE_SEPARATOR.length);
+  if (client === undefined || upstreamName === '') return undefined;
+  return { client, name: upstreamName };
+}
+
+/** One page of a paginated list surface. */
+export interface MeshPage<Item> {
+  items: ReadonlyArray<Item>;
+  nextCursor: string | undefined;
+}
+
+/**
+ * Lists one paginated surface across every backend concurrently, exposing
+ * each entry under its backend key via `expose` and isolating failures: a
+ * backend that throws (or never finishes paginating) contributes nothing and
+ * is reported through `onDegraded`, while the live backends' entries are
+ * still returned.
+ *
+ * Entries keep backend declaration order. A backend that fails part-way
+ * through pagination contributes nothing at all rather than a truncated
+ * list, so the response never looks complete when it is not.
+ */
+export async function listAcrossMesh<Item>(
+  entries: ReadonlyArray<MeshEntry>,
+  listPage: (
+    client: BackendClient,
+    cursor: string | undefined,
+  ) => Promise<MeshPage<Item>>,
+  onDegraded: (key: string, error: unknown) => void,
+  expose: (key: string, item: Item) => Item,
+): Promise<Item[]> {
+  const settled = await Promise.allSettled(
+    entries.map(async ({ key, client }) => {
+      const collected: Item[] = [];
+      let cursor: string | undefined;
+      for (let page = 0; page < MAX_PAGES_PER_BACKEND; page += 1) {
+        const { items, nextCursor } = await listPage(client, cursor);
+        for (const item of items) collected.push(expose(key, item));
+        if (nextCursor === undefined) return collected;
+        cursor = nextCursor;
+      }
+      throw new Error(
+        `mcpose: backend "${key}" did not finish paginating within ${MAX_PAGES_PER_BACKEND} pages`,
+      );
+    }),
+  );
+
+  return settled.flatMap((outcome, index) => {
+    if (outcome.status === 'fulfilled') return outcome.value;
+    onDegraded(entries[index]!.key, outcome.reason);
+    return [];
+  });
+}