fhirsmith 0.16.1 → 0.18.0

package/tx/ocl/resolve/reference-resolver.js

@@ -0,0 +1,458 @@
+// Client for OCL's $resolveReference operation.
+//
+// Answers "which OCL repo holds this canonical URL?" authoritatively, so callers
+// stop iterating source/collection listings to find a matching canonical_url. See
+// https://docs.openconceptlab.org/en/latest/oclapi/apireference/resolveReference.html
+//
+// Namespace is deliberately NOT supported: FHIR operations carry no namespace
+// parameter, so every resolution here runs in OCL's global namespace. Namespace
+// semantics (multi-tenant discrimination, sandboxing) are an open discussion with
+// the OCL team, not something to encode client-side yet.
+//
+// Plain .js rather than tx/ocl's .cjs+stub convention: jest's collectCoverageFrom
+// globs **/*.js only, so a .cjs module would be invisible to coverage.
+
+const { PublicAccessChecker, safeForLog, mapLimit } = require('./public-access');
+
+const RESOLVE_PATH = '/$resolveReference/';
+
+// The live instance rejects large batches (403 somewhere between 150 and 200
+// references); 100 resolved in ~1.1s. Chunking is transparent to callers.
+const MAX_BATCH_SIZE = 100;
+
+// Caps so that client-supplied references cannot grow memory or outbound traffic
+// without bound (the resolver is reachable from any public terminology request):
+//  - the cache is a bounded LRU, so distinct references evict the oldest rather
+//    than accumulating forever;
+//  - references longer than the limit are treated as unresolved and never sent to
+//    OCL (nothing legitimate is anywhere near this long).
+const DEFAULT_CACHE_LIMIT = 5000;
+const MAX_REFERENCE_LENGTH = 2048;
+
+// A transient 401/403 (rate limit, a brief credential hiccup, an oversized batch
+// on a busy instance) backs the resolver off for a while rather than disabling it
+// for the whole process life. 404 (endpoint not implemented) stays permanent.
+const DEFAULT_AUTH_BACKOFF_MS = 60_000;
+
+// Cap on concurrent public_access repo GETs when gating a batch of resolutions.
+const PUBLIC_ACCESS_CONCURRENCY = 8;
+
+// Org-only visibility policy: an artifact is expected to live in an organization
+// to be visible through the terminology service. The path must be a concrete
+// /orgs/<org>/(sources|collections)/<id>/ repo path — this both enforces the
+// policy and keeps repoUrl a safe relative OCL path (so it can never redirect an
+// authenticated request, carrying our token, to an arbitrary host).
+const REPO_PATH_PATTERN = /^\/orgs\/[^/]+\/(sources|collections)\/[^/]+\//;
+
+// Reference object fields forwarded to OCL. `namespace` is intentionally absent.
+const BODY_FIELDS = [
+  'url',
+  'version',
+  'code',
+  'display',
+  'id',
+  'filter',
+  'cascade',
+  'includeExclude',
+  'resourceType'
+];
+
+/**
+ * True for a relative OCL repo path the terminology service may serve — i.e. an
+ * organization-owned source or collection (`/orgs/CIEL/sources/CIEL/`). User-owned
+ * paths (`/users/joe/...`), absolute URLs, and anything containing path traversal
+ * are rejected.
+ */
+function isOclRepoPath(value) {
+  const s = String(value == null ? '' : value).trim();
+  if (s.includes('..')) {
+    // No legitimate OCL repo path contains `..`; reject traversal outright.
+    return false;
+  }
+  return REPO_PATH_PATTERN.test(s);
+}
+
+/**
+ * A repoUrl we can safely GET against the OCL base URL: a relative, same-host path
+ * with no traversal. Absolute or protocol-relative URLs are rejected so an authed
+ * request (carrying our token) can never be redirected to an arbitrary host. This
+ * is the SSRF guard and is deliberately separate from the org-only policy: a
+ * same-host `/users/...` path is "safe" here but still rejected by isOrgOwned.
+ */
+function isSafeRelativeOclPath(value) {
+  const s = String(value == null ? '' : value).trim();
+  return s.startsWith('/') && !s.startsWith('//') && !s.includes('..');
+}
+
+/**
+ * Org-only policy check for an OCL repo payload or resolve result. The path must
+ * be a valid org repo path AND, when an explicit owner_type is present, it must be
+ * an Organization. owner_type alone can never override the path check — a payload
+ * claiming owner_type:"Organization" on a non-org (or off-host) URL is not served.
+ */
+function isOrgOwned(repo) {
+  if (!repo || typeof repo !== 'object') {
+    return false;
+  }
+  if (!isOclRepoPath(repo.url)) {
+    return false;
+  }
+  const ownerType = repo.owner_type || repo.ownerType || null;
+  return ownerType ? ownerType === 'Organization' : true;
+}
+
+/**
+ * Accepts either a relative/canonical URL string or an expanded reference object,
+ * returning the request-body form OCL expects.
+ */
+function normalizeReference(ref) {
+  if (typeof ref === 'string') {
+    const url = ref.trim();
+    if (!url) {
+      throw new Error('OCL reference string cannot be empty');
+    }
+    return url;
+  }
+
+  if (!ref || typeof ref !== 'object' || Array.isArray(ref)) {
+    throw new Error(`Invalid OCL reference: expected a string or object, got ${typeof ref}`);
+  }
+
+  const url = String(ref.url == null ? '' : ref.url).trim();
+  if (!url) {
+    throw new Error('OCL reference object requires a url');
+  }
+
+  const body = {};
+  for (const field of BODY_FIELDS) {
+    if (ref[field] !== undefined && ref[field] !== null) {
+      body[field] = ref[field];
+    }
+  }
+  return body;
+}
+
+function cacheKey(body) {
+  return typeof body === 'string' ? body : JSON.stringify(body);
+}
+
+// Length of the reference's URL, used for the inbound length cap.
+function referenceLength(body) {
+  return (typeof body === 'string' ? body : String(body?.url ?? '')).length;
+}
+
+
+function unresolved(request) {
+  return {
+    resolved: false,
+    repoUrl: null,
+    canonical: null,
+    ownerType: null,
+    publicAccess: null,
+    resolutionUrl: null,
+    registryEntry: null,
+    referenceType: null,
+    request,
+    result: null
+  };
+}
+
+function normalizeResult(entry, request) {
+  if (!entry || typeof entry !== 'object') {
+    return unresolved(request);
+  }
+
+  const result = entry.result && typeof entry.result === 'object' ? entry.result : null;
+  const repoUrl = result && result.url ? result.url : null;
+
+  // Only ever hand back a repoUrl that is a safe same-host relative path. Anything
+  // absolute or off-host (or containing traversal) is treated as unresolved, so a
+  // surprising OCL response can never cause a caller to issue an authenticated
+  // request (with our token) to an arbitrary host. The org-only policy is applied
+  // separately by the caller (isOrgOwned), so a same-host /users/ path survives to
+  // there and is rejected with a logged reason.
+  if (repoUrl && !isSafeRelativeOclPath(repoUrl)) {
+    return unresolved(entry.request === undefined ? request : entry.request);
+  }
+
+  return {
+    resolved: Boolean(entry.resolved) && Boolean(repoUrl),
+    repoUrl,
+    // OCL returns the repo's own canonical_url and owner_type (richer than the
+    // documented example). Prefer them over echoing the request back: they are
+    // authoritative, the request is just whatever spelling the caller used.
+    canonical: result ? (result.canonical_url || result.canonicalUrl || null) : null,
+    ownerType: result ? (result.owner_type || result.ownerType || null) : null,
+    // public_access is not in the $resolveReference result today (the live capture
+    // omits it), so this is usually null and the repo is fetched to check — kept
+    // anyway so the gate is free the day OCL does inline it.
+    publicAccess: result ? (result.public_access ?? result.publicAccess ?? null) : null,
+    resolutionUrl: entry.resolution_url || null,
+    // Kept even though every observed response so far carries null: whether a URL
+    // Registry entry was involved is exactly what the OCL-team discussion needs.
+    registryEntry: entry.url_registry_entry || null,
+    referenceType: entry.reference_type || null,
+    request: entry.request === undefined ? request : entry.request,
+    result
+  };
+}
+
+class OclReferenceResolver {
+  #httpClient;
+  #logger;
+  #cache = new Map();
+  #cacheLimit;
+  #enabled;
+  #disabledReason = null;
+  #authBackoffMs;
+  #backoffUntil = 0;
+  #publicAccess;
+
+  /**
+   * @param {object} options
+   * @param {object} options.httpClient - axios instance from createOclHttpClient
+   * @param {string} [options.token] - when absent the resolver stays disabled:
+   *   $resolveReference is authenticated on every OCL instance probed, while the
+   *   listing endpoints it replaces are public, so a tokenless call is a
+   *   guaranteed 401
+   * @param {object} [options.logger] - module logger; defaults to console only as
+   *   a last resort (callers pass their child logger)
+   * @param {number} [options.cacheLimit] - max cached references (bounded LRU)
+   * @param {number} [options.authBackoffMs] - cooldown after a transient 401/403
+   * @param {PublicAccessChecker} [options.publicAccess] - shared public-access gate
+   *   (so discovery and the resolver share one repoUrl cache); created if absent
+   */
+  constructor({ httpClient, token = null, logger = console, cacheLimit = DEFAULT_CACHE_LIMIT, authBackoffMs = DEFAULT_AUTH_BACKOFF_MS, publicAccess = null } = {}) {
+    if (!httpClient) {
+      throw new Error('OCL reference resolver requires an http client');
+    }
+
+    this.#httpClient = httpClient;
+    this.#logger = logger;
+    this.#cacheLimit = cacheLimit > 0 ? cacheLimit : DEFAULT_CACHE_LIMIT;
+    this.#authBackoffMs = authBackoffMs >= 0 ? authBackoffMs : DEFAULT_AUTH_BACKOFF_MS;
+    this.#publicAccess = publicAccess || new PublicAccessChecker({ httpClient, logger });
+    this.#enabled = Boolean(token);
+    if (!this.#enabled) {
+      this.#disabledReason = 'no token configured';
+    }
+  }
+
+  isEnabled() {
+    return this.#enabled && Date.now() >= this.#backoffUntil;
+  }
+
+  get disabledReason() {
+    return this.#disabledReason;
+  }
+
+  // Permanent: no token, or the endpoint does not exist on this instance.
+  #disable(reason) {
+    this.#enabled = false;
+    this.#disabledReason = reason;
+  }
+
+  // Transient: back off for a cooldown, then let requests resume.
+  #backOff(reason) {
+    this.#backoffUntil = Date.now() + this.#authBackoffMs;
+    this.#disabledReason = reason;
+  }
+
+  #cacheTouch(key) {
+    // Re-insert to mark most-recently-used.
+    const value = this.#cache.get(key);
+    this.#cache.delete(key);
+    this.#cache.set(key, value);
+    return value;
+  }
+
+  #cachePut(key, value) {
+    if (this.#cache.has(key)) {
+      this.#cache.delete(key);
+    }
+    this.#cache.set(key, value);
+    if (this.#cache.size > this.#cacheLimit) {
+      const oldest = this.#cache.keys().next().value;
+      this.#cache.delete(oldest);
+    }
+  }
+
+  /**
+   * Resolve one reference. Returns null when the resolver is unavailable, so the
+   * caller falls back to its existing path.
+   */
+  async resolve(ref) {
+    const results = await this.resolveReferences([ref]);
+    return results ? results[0] : null;
+  }
+
+  /**
+   * Resolve many references, chunked into POSTs of at most MAX_BATCH_SIZE.
+   * Results come back in the caller's order.
+   *
+   * @param {object} [options]
+   * @param {boolean} [options.bypassCache] - re-ask OCL even for cached entries
+   *   (the cache is still updated). Used by discovery refresh, where a source's
+   *   default version may have changed since it was last resolved.
+   * @returns {Promise<Array|null>} null when the resolver is unavailable (use fallback)
+   */
+  async resolveReferences(refs, { bypassCache = false } = {}) {
+    if (!this.isEnabled()) {
+      return null;
+    }
+
+    const list = Array.isArray(refs) ? refs : [refs];
+    if (list.length === 0) {
+      return [];
+    }
+
+    const bodies = list.map(normalizeReference);
+    const output = new Array(bodies.length).fill(null);
+    const misses = [];
+
+    bodies.forEach((body, index) => {
+      // Length cap: an over-long reference is never cached nor sent to OCL.
+      if (referenceLength(body) > MAX_REFERENCE_LENGTH) {
+        output[index] = unresolved(body);
+        return;
+      }
+      const key = cacheKey(body);
+      if (!bypassCache && this.#cache.has(key)) {
+        output[index] = this.#cacheTouch(key);
+      } else {
+        misses.push({ body, index });
+      }
+    });
+
+    for (let start = 0; start < misses.length; start += MAX_BATCH_SIZE) {
+      const chunk = misses.slice(start, start + MAX_BATCH_SIZE);
+      const outcome = await this.#resolveChunk(chunk, output);
+      if (outcome === null) {
+        // Resolver became unavailable; the caller falls back wholesale rather
+        // than acting on a half-resolved set.
+        return null;
+      }
+    }
+
+    return output;
+  }
+
+  async #resolveChunk(chunk, output) {
+    let response;
+    try {
+      response = await this.#httpClient.post(RESOLVE_PATH, chunk.map(m => m.body));
+    } catch (error) {
+      return this.#handleError(error, chunk, output);
+    }
+
+    const payload = Array.isArray(response?.data)
+      ? response.data
+      : response?.data == null
+        ? []
+        : [response.data];
+
+    // Results are positional. On a count mismatch we cannot know which result
+    // belongs to which reference, so treat the chunk as unresolved rather than
+    // silently attributing a resolution to the wrong canonical.
+    if (payload.length !== chunk.length) {
+      this.#logger.error(
+        `$resolveReference returned ${payload.length} result(s) for ${chunk.length} reference(s); discarding to avoid misaligned results`
+      );
+      for (const { body, index } of chunk) {
+        output[index] = unresolved(body);
+      }
+      return output;
+    }
+
+    // Pass 1 (sync): normalize + org-only policy.
+    const prelim = chunk.map(({ body, index }, position) => {
+      let value = normalizeResult(payload[position], body);
+      // Org-only policy: a canonical resolving to a user-owned repo is treated as
+      // unresolved — user artifacts are experimental and not visible through the
+      // terminology service. Cached: the policy outcome is deterministic.
+      if (value.resolved && !isOrgOwned({ owner_type: value.ownerType, url: value.repoUrl })) {
+        this.#logger.info(
+          `$resolveReference resolved ${safeForLog(cacheKey(body))} to a user-owned repo (${safeForLog(value.repoUrl)}); org-only policy treats it as unresolved`
+        );
+        value = unresolved(body);
+      }
+      return { body, index, value };
+    });
+
+    // Pass 2 (async): public-access gate. A private repo (public_access other than
+    // View/Edit) that the configured token can see must NOT be served through the
+    // public terminology server, so anything not positively confirmed public is
+    // dropped. public_access is not in the resolve result today, so the shared
+    // checker fetches the repo once (cached by repoUrl, concurrency-limited). A
+    // transient fetch error is NOT cached — that reference is left out of the
+    // result cache below and retried next time rather than pinned as unresolved.
+    await mapLimit(prelim, PUBLIC_ACCESS_CONCURRENCY, async entry => {
+      if (!entry.value.resolved) {
+        return;
+      }
+      const { public: isPublic, determined } = await this.#publicAccess.check(entry.value.repoUrl, entry.value.publicAccess);
+      if (!isPublic) {
+        this.#logger.info(
+          `$resolveReference resolved ${safeForLog(cacheKey(entry.body))} to a non-public repo ` +
+          `(${safeForLog(entry.value.repoUrl)}); not served`
+        );
+        entry.value = unresolved(entry.body);
+        entry.skipCache = !determined;
+      }
+    });
+
+    for (const { body, index, value, skipCache } of prelim) {
+      if (!skipCache) {
+        this.#cachePut(cacheKey(body), value);
+      }
+      output[index] = value;
+    }
+
+    return output;
+  }
+
+  #handleError(error, misses, output) {
+    const status = error?.response?.status;
+
+    if (status === 404) {
+      this.#disable('endpoint not implemented (404)');
+      this.#logger.info(
+        `$resolveReference is not available on this instance (404); using listing search instead`
+      );
+      return null;
+    }
+
+    if (status === 401 || status === 403) {
+      // Transient: back off and retry after a cooldown rather than disabling for
+      // the life of the process. A busy public instance can 401/403 briefly (rate
+      // limiting, an oversized batch) without our credentials being wrong.
+      this.#backOff(`not authorised (${status})`);
+      this.#logger.warn(
+        `$resolveReference rejected our credentials (${status}); backing off, using listing search meanwhile`
+      );
+      return null;
+    }
+
+    if (status === 400) {
+      // Our request body is wrong — a bug on this side. Don't disable: a later,
+      // well-formed batch may be fine.
+      const detail = error?.response?.data?.detail || error.message;
+      this.#logger.error(`$resolveReference rejected the request body: ${safeForLog(detail)}`);
+      for (const { body, index } of misses) {
+        output[index] = unresolved(body);
+      }
+      return output;
+    }
+
+    this.#logger.warn(`$resolveReference failed: ${safeForLog(error.message)}`);
+    return null;
+  }
+}
+
+module.exports = {
+  OclReferenceResolver,
+  normalizeReference,
+  isOclRepoPath,
+  isOrgOwned,
+  RESOLVE_PATH
+};

package/tx/ocl/vs-ocl.cjs

@@ -9,6 +9,8 @@ const { TxParameters } = require('../params');
 const { OCLSourceCodeSystemFactory, OCLBackgroundJobQueue } = require('./cs-ocl');
 const { PAGE_SIZE, CONCEPT_PAGE_SIZE, FILTERED_CONCEPT_PAGE_SIZE, COLD_CACHE_FRESHNESS_MS } = require('./shared/constants');
 const { createOclHttpClient } = require('./http/client');
+const { OclReferenceResolver, isOrgOwned } = require('./resolve/reference-resolver');
+const { PublicAccessChecker } = require('./resolve/public-access');
 const { CACHE_VS_DIR, getCacheFilePath } = require('./cache/cache-paths');
 const { ensureCacheDirectories, getColdCacheAgeMs, formatCacheAgeMinutes } = require('./cache/cache-utils');
 const { computeValueSetExpansionFingerprint } = require('./fingerprint/fingerprint');
@@ -44,6 +46,16 @@ class OCLValueSetProvider extends AbstractValueSetProvider {
     this.baseUrl = http.baseUrl;
     this.httpClient = http.client;
 
+    // Resolves a canonical to its OCL repo authoritatively. Disabled without a
+    // token, in which case the search paths below run exactly as before.
+    this.publicAccess = new PublicAccessChecker({ httpClient: this.httpClient, logger: oclVsLog });
+    this.referenceResolver = new OclReferenceResolver({
+      httpClient: this.httpClient,
+      token: options.token || null,
+      logger: oclVsLog,
+      publicAccess: this.publicAccess
+    });
+
     this.valueSetMap = new Map();
     this._idMap = new Map();
     this.collectionMeta = new Map();
@@ -726,6 +738,11 @@ class OCLValueSetProvider extends AbstractValueSetProvider {
     }
 
     const sourceKeys = await this.#fetchCollectionSourceKeys(meta.conceptsUrl, meta.owner || null);
+    // Resolve every source's canonical in a single $resolveReference batch and seed
+    // the per-source cache, replacing one sequential GET per source. The loop below
+    // then reads from cache; anything the batch could not resolve falls through to
+    // the individual GET in #getSourceCanonicalUrl, so behaviour is unchanged.
+    await this.#primeSourceCanonicalsBatch(sourceKeys);
     for (const { owner, source } of sourceKeys) {
       const systemUrl = normalizeCanonicalSystem(await this.#getSourceCanonicalUrl(owner, source));
       if (systemUrl && !seen.has(systemUrl)) {
@@ -1185,6 +1202,15 @@ class OCLValueSetProvider extends AbstractValueSetProvider {
     }
 
     const pending = (async () => {
+      // Ask OCL which repo holds this canonical. An authoritative answer skips
+      // the per-org text search below; without one (no token, or the endpoint is
+      // unavailable) we fall through to it.
+      const resolvedCollection = await this.#resolveCollectionViaReference(canonicalUrl, version);
+      if (resolvedCollection) {
+        this.collectionByCanonicalCache.set(lookupKey, resolvedCollection);
+        return resolvedCollection;
+      }
+
       const organizations = await this.#fetchOrganizationIds();
       const endpoints = organizations.length > 0
         ? organizations.map(orgId => `/orgs/${encodeURIComponent(orgId)}/collections/`)
@@ -1251,6 +1277,56 @@ class OCLValueSetProvider extends AbstractValueSetProvider {
     }
   }
 
+  /**
+   * Resolve a ValueSet canonical to its OCL collection via $resolveReference,
+   * then fetch the collection object so it matches the shape the text-search path
+   * returns. Returns null when the resolver is disabled (no token), the endpoint
+   * is unavailable, OCL cannot resolve it, or the resolved repo is not a
+   * collection -- in every case the caller falls back to the search.
+   */
+  async #resolveCollectionViaReference(canonicalUrl, version) {
+    let resolved;
+    try {
+      resolved = await this.referenceResolver.resolve(
+        version ? { url: canonicalUrl, version } : canonicalUrl
+      );
+    } catch (error) {
+      oclVsLog.warn(`$resolveReference lookup failed for ${canonicalUrl}: ${error.message}`);
+      return null;
+    }
+
+    if (!resolved?.resolved || !resolved.repoUrl) {
+      return null;
+    }
+
+    // $resolveReference resolves any repo type; only collections are ValueSets.
+    if (!/[/]collections[/]/.test(resolved.repoUrl)) {
+      return null;
+    }
+
+    let collection;
+    try {
+      const response = await this.httpClient.get(resolved.repoUrl);
+      collection = response?.data || null;
+    } catch (error) {
+      oclVsLog.warn(`failed to fetch resolved collection ${resolved.repoUrl}: ${error.message}`);
+      return null;
+    }
+
+    if (!collection || typeof collection !== 'object' || !collection.id) {
+      return null;
+    }
+
+    // Honour an explicit version: the resolved repo is HEAD unless OCL matched a
+    // version, so a mismatch means fall back to the version-aware search.
+    if (version && (collection.version || null) !== version) {
+      return null;
+    }
+
+    oclVsLog.info(`$resolveReference resolved ${canonicalUrl} -> ${resolved.repoUrl}`);
+    return collection;
+  }
+
   #valueSetMetadataSignature(vs) {
     const meta = this.#getCollectionMeta(vs);
     const payload = {
@@ -1311,10 +1387,37 @@ class OCLValueSetProvider extends AbstractValueSetProvider {
   }
 
   async #fetchCollectionsForDiscovery() {
+    // Prefer the global listing: one paginated crawl instead of one listing per
+    // org (N+1 requests). Org-only policy: user-owned collections are
+    // experimental by convention and not visible to the terminology service.
+    try {
+      const all = await this.#fetchAllPages('/collections/');
+      if (Array.isArray(all) && all.length > 0) {
+        const seen = new Set();
+        const orgOwned = [];
+        for (const collection of all) {
+          if (!collection || typeof collection !== 'object' || !isOrgOwned(collection)) {
+            continue;
+          }
+          const key = this.#collectionIdentity(collection);
+          if (seen.has(key)) {
+            continue;
+          }
+          seen.add(key);
+          orgOwned.push(collection);
+        }
+        if (orgOwned.length > 0) {
+          // Public-only: a private collection the token can see must not be served.
+          return await this.publicAccess.filterPublic(orgOwned);
+        }
+      }
+    } catch (error) {
+      oclVsLog.warn(`Global /collections/ listing failed (${error.message}); falling back to per-org discovery`);
+    }
+
     const organizations = await this.#fetchOrganizationIds();
     if (organizations.length === 0) {
-      // Fallback for OCL instances that expose global listing but not org listing.
-      return await this.#fetchAllPages('/collections/');
+      return [];
     }
 
     const allCollections = [];
@@ -1324,7 +1427,9 @@ class OCLValueSetProvider extends AbstractValueSetProvider {
       const endpoint = `/orgs/${encodeURIComponent(orgId)}/collections/`;
       const collections = await this.#fetchAllPages(endpoint);
       for (const collection of collections) {
-        if (!collection || typeof collection !== 'object') {
+        // Org-only policy applies to the per-org fallback too, not just the global
+        // listing (an org listing can still surface non-org-owned entries).
+        if (!collection || typeof collection !== 'object' || !isOrgOwned(collection)) {
           continue;
         }
         const key = this.#collectionIdentity(collection);
@@ -1336,7 +1441,8 @@ class OCLValueSetProvider extends AbstractValueSetProvider {
       }
     }
 
-    return allCollections;
+    // Public-only: a private collection the token can see must not be served.
+    return await this.publicAccess.filterPublic(allCollections);
   }
 
   async #fetchOrganizationIds() {
@@ -1783,6 +1889,63 @@ class OCLValueSetProvider extends AbstractValueSetProvider {
     }
   }
 
+  /**
+   * Resolve many sources' canonicals in one $resolveReference batch, seeding
+   * sourceCanonicalCache. A no-op when the resolver is disabled (no token) or the
+   * batch fails: #getSourceCanonicalUrl then falls back to its per-source GET, so
+   * this only ever saves round trips, never changes the result.
+   */
+  async #primeSourceCanonicalsBatch(sourceKeys) {
+    if (!this.referenceResolver.isEnabled()) {
+      return;
+    }
+
+    // Only sources not already cached, deduplicated by owner|source.
+    const pending = [];
+    const seen = new Set();
+    for (const { owner, source } of sourceKeys || []) {
+      if (!owner || !source) {
+        continue;
+      }
+      const key = `${owner}|${source}`;
+      if (this.sourceCanonicalCache.has(key) || seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+      pending.push({ key, ref: `/orgs/${encodeURIComponent(owner)}/sources/${encodeURIComponent(source)}/` });
+    }
+
+    if (pending.length === 0) {
+      return;
+    }
+
+    let results;
+    try {
+      results = await this.referenceResolver.resolveReferences(pending.map(p => p.ref));
+    } catch (error) {
+      oclVsLog.warn(`$resolveReference batch failed: ${error.message}`);
+      return;
+    }
+
+    // null => resolver disabled or unavailable mid-flight; leave the cache untouched
+    // so the per-source GET fallback runs.
+    if (!Array.isArray(results)) {
+      return;
+    }
+
+    let resolvedCount = 0;
+    for (let i = 0; i < pending.length; i++) {
+      const canonical = results[i]?.resolved ? results[i].canonical : null;
+      if (canonical) {
+        this.sourceCanonicalCache.set(pending[i].key, canonical);
+        resolvedCount++;
+      }
+    }
+    if (resolvedCount > 0) {
+      oclVsLog.info(`$resolveReference batch resolved ${resolvedCount}/${pending.length} source canonical(s) in one request`);
+    }
+  }
+
   #matches(json, params) {
     for (const [name, value] of Object.entries(params)) {
       if (!value) {