@adea-ai/plugins 4.0.0 → 4.0.6

package/src/upstream.ts

@@ -0,0 +1,194 @@
+import { spawn } from 'node:child_process'
+import { setTimeout as sleep } from 'node:timers/promises'
+import { canonicalRepositoryUrl } from './sources.js'
+import type { SiteIconFetcher } from './site-icons.js'
+
+export function externalGitRef(ref: string | undefined): string {
+  if (ref === undefined) return 'HEAD'
+  return ref.startsWith('refs/') ? ref : `refs/heads/${ref}`
+}
+
+export async function resolveGitRef(repositoryUrl: string, ref: string): Promise<string> {
+  const peeled = ref.startsWith('refs/tags/') && !ref.endsWith('^{}') ? `${ref}^{}` : undefined
+  const result = spawn(
+    'git',
+    ['ls-remote', canonicalRepositoryUrl(repositoryUrl), ref, ...(peeled ? [peeled] : [])],
+    {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }
+  )
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Promise<string>((resolveOutput, reject) => {
+      const chunks: Buffer[] = []
+      result.stdout?.on('data', (chunk: Buffer) => chunks.push(chunk))
+      result.stdout?.on('error', reject)
+      result.stdout?.on('end', () => resolveOutput(Buffer.concat(chunks).toString('utf8')))
+    }),
+    new Promise<string>((resolveError) => {
+      const chunks: Buffer[] = []
+      result.stderr?.on('data', (chunk: Buffer) => chunks.push(chunk))
+      result.stderr?.on('error', () => resolveError(''))
+      result.stderr?.on('end', () => resolveError(Buffer.concat(chunks).toString('utf8')))
+    }),
+    new Promise<number | null>((resolveExit, reject) => {
+      result.on('error', reject)
+      result.on('close', (code) => resolveExit(code ?? 1))
+    }),
+  ])
+  if (exitCode !== 0)
+    throw new Error(`GIT_REF_LOOKUP_FAILED: ${repositoryUrl}:${ref}:${stderr.trim()}`)
+  const rows = stdout
+    .trim()
+    .split('\n')
+    .map((line) => line.split(/\s+/))
+  const sha =
+    (peeled && rows.find((row) => row[1] === peeled)?.[0]) ??
+    rows.find((row) => row[1] === ref)?.[0]
+  if (!sha || !/^[a-f0-9]{40}$/.test(sha))
+    throw new Error(`GIT_REF_NOT_FOUND: ${repositoryUrl}:${ref}`)
+  return sha
+}
+
+export async function fetchUpstreamBytes(url: string, signal?: AbortSignal): Promise<Uint8Array> {
+  const response = await fetchUpstream(url, {
+    headers: upstreamRequestHeaders(url),
+    ...(signal ? { signal } : {}),
+  })
+  if (!response.ok) throw new Error(`HTTP_FETCH_FAILED: ${response.status}: ${url}`)
+  return new Uint8Array(await response.arrayBuffer())
+}
+
+export function rawContentUrl(repositoryUrl: string, commitSha: string, path: string): string {
+  const parsed = new URL(canonicalRepositoryUrl(repositoryUrl))
+  return `https://raw.githubusercontent.com${parsed.pathname}/${commitSha}/${path.split('/').map(encodeURIComponent).join('/')}`
+}
+
+export async function fetchText(url: string): Promise<string> {
+  const response = await fetchUpstream(url, { headers: upstreamRequestHeaders(url) })
+  if (!response.ok) throw new Error(`HTTP_FETCH_FAILED: ${response.status}:${url}`)
+  return response.text()
+}
+
+const UPSTREAM_USER_AGENT = 'agent-hq-plugin-marketplace'
+
+/**
+ * Hosts that may receive the repository credential.
+ *
+ * Everything else is fetched anonymously. The token this build runs with
+ * authorises repository writes for the duration of the job, so a vendor
+ * homepage, its icon CDN or any other third party must never be handed it.
+ */
+/** The hosts the network snapshot loader reads repositories from. */
+export const GITHUB_REPOSITORY_HOSTS: readonly string[] = ['github.com', 'www.github.com']
+
+const GITHUB_CREDENTIAL_HOSTS = /(^|\.)(github\.com|githubusercontent\.com)$/
+
+/**
+ * Request headers for one upstream URL.
+ *
+ * The credential and GitHub's media type are attached only for GitHub hosts.
+ * Sending them elsewhere is not merely a needless disclosure: `appwrite.io`
+ * answers a page carrying an `Authorization` header with HTTP 500, and a CDN
+ * asked for an image with `accept: application/vnd.github+json` can answer with
+ * bytes that are not the mark. A build that did this dropped marks it had
+ * already curated, and the curation verifier — which used its own anonymous
+ * headers — could not see it.
+ */
+export function upstreamRequestHeaders(url: string): Record<string, string> {
+  const anonymous = { 'user-agent': UPSTREAM_USER_AGENT }
+  let host: string
+  try {
+    host = new URL(url).hostname.toLowerCase()
+  } catch {
+    return anonymous
+  }
+  const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN
+  if (!token || !GITHUB_CREDENTIAL_HOSTS.test(host)) return anonymous
+  return {
+    accept: 'application/vnd.github+json',
+    authorization: `Bearer ${token}`,
+    'user-agent': UPSTREAM_USER_AGENT,
+  }
+}
+
+/**
+ * Fetches vendor-site documents exactly as a live build does.
+ *
+ * Shared with the curation verifier so both ask a vendor the same question: a
+ * verifier with its own headers reports sites healthy that the build then fails
+ * to resolve.
+ *
+ * `deadline` optionally bounds one product's whole resolution. The per-request
+ * ceiling is always created fresh inside each fetch, so a caller that passes a
+ * deadline — or shares one — can never hand later requests an already-expired
+ * signal.
+ */
+export function createSiteIconFetcher(deadline?: AbortSignal): SiteIconFetcher {
+  const bounded = (): AbortSignal => {
+    const ceiling = AbortSignal.timeout(SITE_FETCH_TIMEOUT_MS)
+    return deadline ? AbortSignal.any([deadline, ceiling]) : ceiling
+  }
+  return {
+    fetchText: async (url) => new TextDecoder().decode(await fetchUpstreamBytes(url, bounded())),
+    fetchBytes: (url) => fetchUpstreamBytes(url, bounded()),
+  }
+}
+
+export const SITE_FETCH_TIMEOUT_MS = 15_000
+
+const UPSTREAM_FETCH_MAX_ATTEMPTS = 3
+const UPSTREAM_FETCH_BASE_DELAY_MS = 1000
+const UPSTREAM_FETCH_MAX_DELAY_MS = 30000
+
+function upstreamRetryDelayMs(attempt: number, response?: Response): number {
+  const retryAfter = response?.headers.get('retry-after')
+  if (retryAfter !== null && retryAfter !== undefined) {
+    const seconds = Number(retryAfter)
+    if (Number.isFinite(seconds) && seconds >= 0)
+      return Math.min(seconds * 1000, UPSTREAM_FETCH_MAX_DELAY_MS)
+    const date = Date.parse(retryAfter)
+    if (!Number.isNaN(date))
+      return Math.min(Math.max(date - Date.now(), 0), UPSTREAM_FETCH_MAX_DELAY_MS)
+  }
+  return Math.min(UPSTREAM_FETCH_BASE_DELAY_MS * 2 ** attempt, UPSTREAM_FETCH_MAX_DELAY_MS)
+}
+
+function isRateLimitedUpstream(response: Response): boolean {
+  return (
+    response.headers.get('x-ratelimit-remaining') === '0' ||
+    response.headers.get('retry-after') !== null
+  )
+}
+
+function isRetryableUpstreamStatus(status: number, response?: Response): boolean {
+  if (status === 429) return true
+  if (status >= 500) return true
+  if (status === 403 && response !== undefined && isRateLimitedUpstream(response)) return true
+  return false
+}
+
+export async function fetchUpstream(url: string, init: RequestInit): Promise<Response> {
+  let attempt = 0
+  for (;;) {
+    let response: Response
+    try {
+      response = await fetch(url, init)
+    } catch (error) {
+      if (init.signal?.aborted || attempt >= UPSTREAM_FETCH_MAX_ATTEMPTS - 1) throw error
+      await sleep(upstreamRetryDelayMs(attempt), undefined, { signal: init.signal ?? undefined })
+      attempt += 1
+      continue
+    }
+    if (
+      response.ok ||
+      !isRetryableUpstreamStatus(response.status, response) ||
+      attempt >= UPSTREAM_FETCH_MAX_ATTEMPTS - 1
+    )
+      return response
+    await response.body?.cancel().catch(() => {})
+    await sleep(upstreamRetryDelayMs(attempt, response), undefined, {
+      signal: init.signal ?? undefined,
+    })
+    attempt += 1
+  }
+}

package/src/verify-artifacts.ts

@@ -0,0 +1,365 @@
+import type { GeneratedArtifacts } from './artifacts.js'
+import {
+  parseIntegrityManifest,
+  publishedAssetOf,
+  type PublishedAsset,
+} from './integrity-manifest.js'
+import {
+  CATALOG_INDEX_ARTIFACT,
+  iconCoverage,
+  type ConsumerCategory,
+  type ConsumerIndex,
+  type ConsumerProduct,
+  type LeadingDiagnostic,
+} from './consumer-index.js'
+import { digest } from './digest.js'
+import { assertRepositoryAllowed, DEFAULT_POLICY, type CatalogPolicy } from './policy.js'
+import { CatalogSchema, SourcesLockSchema, type Catalog } from './schema.js'
+import { safeRelativePath } from './sources.js'
+
+export interface ConsumerIndexVerification {
+  readonly hasConsumerIndex: boolean
+  readonly diagnostics: readonly LeadingDiagnostic[]
+  readonly counts?: ConsumerIndex['counts']
+  readonly topCount?: number
+  readonly products?: Readonly<Record<string, ConsumerProduct>>
+  readonly categories?: readonly ConsumerCategory[]
+  /** Shards the published integrity file set must carry for this index. */
+  readonly shards: readonly ShardArtifact[]
+}
+
+export interface ShardArtifact {
+  readonly name: string
+  readonly kind: 'index' | 'shelf' | 'list'
+  readonly category?: string
+}
+
+export function verifyArtifacts(artifacts: GeneratedArtifacts): void {
+  const parsedCatalog = CatalogSchema.parse(JSON.parse(artifacts['catalog.v1.json']))
+  verifyCatalogReferences(parsedCatalog)
+  const lock = SourcesLockSchema.parse(JSON.parse(artifacts['sources.lock.json']))
+  const summary = JSON.parse(artifacts['catalog-summary.v1.json']) as {
+    schemaVersion?: unknown
+    catalogId?: unknown
+    sourceCount?: unknown
+    pluginCount?: unknown
+    search?: unknown
+  }
+  const compatibility = JSON.parse(artifacts['compatibility.v1.json']) as {
+    schemaVersion?: unknown
+    catalogId?: unknown
+    plugins?: unknown
+  }
+  const categories = JSON.parse(artifacts['categories.v1.json']) as {
+    schemaVersion?: unknown
+    catalogId?: unknown
+    topCount?: unknown
+    counts?: { plugins?: unknown; products?: unknown; redundantPlugins?: unknown }
+    categories?: unknown
+    products?: unknown
+    diagnostics?: unknown
+  }
+  const integrity = parseIntegrityManifest(JSON.parse(artifacts['integrity.json']))
+  if (parsedCatalog.sources.length !== lock.sources.length)
+    throw new Error('INTEGRITY_SOURCE_COUNT_MISMATCH')
+  if (
+    summary.schemaVersion !== 1 ||
+    summary.catalogId !== parsedCatalog.catalogId ||
+    summary.sourceCount !== parsedCatalog.sources.length ||
+    summary.pluginCount !== parsedCatalog.plugins.length ||
+    !Array.isArray(summary.search) ||
+    compatibility.schemaVersion !== 1 ||
+    compatibility.catalogId !== parsedCatalog.catalogId ||
+    !Array.isArray(compatibility.plugins) ||
+    compatibility.plugins.length !== parsedCatalog.plugins.length ||
+    categories.schemaVersion !== 1 ||
+    categories.catalogId !== parsedCatalog.catalogId ||
+    !Array.isArray(categories.categories) ||
+    (categories.products !== undefined &&
+      (typeof categories.products !== 'object' || categories.products === null)) ||
+    (categories.diagnostics !== undefined && !Array.isArray(categories.diagnostics)) ||
+    integrity.catalogId !== parsedCatalog.catalogId
+  ) {
+    throw new Error('INTEGRITY_ARTIFACT_METADATA_MISMATCH')
+  }
+  // The published file set is exactly what integrity.json enumerates, so the
+  // shards can grow with the category configuration without a fixed list here.
+  for (const name of Object.keys(artifacts))
+    if (name !== 'integrity.json' && integrity.files[name] === undefined)
+      throw new Error(`INTEGRITY_FILE_SET_MISMATCH: ${name}`)
+  for (const [name, expected] of Object.entries(integrity.files)) {
+    const content = artifacts[name]
+    if (content === undefined) throw new Error(`INTEGRITY_FILE_SET_MISMATCH: ${name}`)
+    if (digest(content) !== expected) throw new Error(`INTEGRITY_DIGEST_MISMATCH: ${name}`)
+  }
+  const indexArtifact = artifacts[CATALOG_INDEX_ARTIFACT]
+  const verification = verifyConsumerIndex(
+    artifacts['categories.v1.json'],
+    parsedCatalog,
+    indexArtifact
+  )
+  if (verification.hasConsumerIndex && indexArtifact === undefined)
+    throw new Error(`SHARD_MISSING: ${CATALOG_INDEX_ARTIFACT}`)
+  for (const shard of verification.shards)
+    verifyShardArtifact(shard, artifacts[shard.name], verification, parsedCatalog.catalogId)
+  verifyIconAssets(integrity.assets ?? [], verification)
+}
+
+/**
+ * Re-checks one consumer shard against the navigation index: a shelf carries
+ * exactly the curated products in order, and a category list carries exactly
+ * the category's products in order. The expected catalog ID must come from a
+ * separately verified catalog, not from the shard being checked.
+ */
+export function verifyShardArtifact(
+  shard: ShardArtifact,
+  content: string | undefined,
+  verification: ConsumerIndexVerification,
+  catalogId: string
+): void {
+  if (!CatalogSchema.shape.catalogId.safeParse(catalogId).success)
+    throw new Error('SHARD_CATALOG_ID_REQUIRED')
+  if (content === undefined) throw new Error(`SHARD_MISSING: ${shard.name}`)
+  const parsed = JSON.parse(content) as {
+    schemaVersion?: unknown
+    catalogId?: unknown
+    category?: unknown
+    topCount?: unknown
+    products?: unknown
+  }
+  if (
+    parsed.schemaVersion !== 1 ||
+    parsed.catalogId !== catalogId ||
+    (shard.kind !== 'index' && parsed.category !== shard.category)
+  )
+    throw new Error(`SHARD_IDENTITY_MISMATCH: ${shard.name}`)
+  const products: readonly ConsumerProduct[] =
+    shard.kind === 'index'
+      ? Object.values((parsed.products ?? {}) as Record<string, ConsumerProduct>)
+      : (parsed.products as readonly ConsumerProduct[])
+  if (!Array.isArray(products)) throw new Error(`SHARD_PRODUCTS_INVALID: ${shard.name}`)
+  const keys = products.map((product) => product.productKey)
+  if (new Set(keys).size !== keys.length) throw new Error(`SHARD_DUPLICATE_PRODUCT: ${shard.name}`)
+  if (shard.kind === 'index') {
+    const expected = Object.keys(verification.products ?? {}).toSorted()
+    if (keys.toSorted().join('\n') !== expected.join('\n'))
+      throw new Error('SHARD_INDEX_MEMBERSHIP_MISMATCH')
+    return
+  }
+  const category = verification.categories?.find((item) => item.category === shard.category)
+  if (!category) throw new Error(`SHARD_CATEGORY_UNKNOWN: ${shard.name}`)
+  const expected = shard.kind === 'shelf' ? category.topProductKeys : category.productKeys
+  if (keys.join('\n') !== expected.join('\n'))
+    throw new Error(`SHARD_ORDER_MISMATCH: ${shard.name}`)
+  for (const product of products) {
+    const index = verification.products?.[product.productKey]
+    if (!index || digest(index) !== digest(product))
+      throw new Error(`SHARD_PRODUCT_MISMATCH: ${shard.name}: ${product.productKey}`)
+  }
+}
+
+function verifyIconAssets(
+  declared: readonly PublishedAsset[],
+  verification: ConsumerIndexVerification
+): void {
+  const referenced = new Map<string, PublishedAsset>()
+  for (const product of Object.values(verification.products ?? {})) {
+    if (!product.icon) continue
+    const existing = referenced.get(product.icon.asset)
+    if (existing && existing.digest !== product.icon.digest)
+      throw new Error(`ICON_ASSET_DIGEST_CONFLICT: ${product.icon.asset}`)
+    referenced.set(product.icon.asset, publishedAssetOf(product.icon))
+  }
+  if (declared.length !== referenced.size) throw new Error('INTEGRITY_ASSET_SET_MISMATCH')
+  for (const asset of declared) {
+    const expected = referenced.get(asset.name)
+    if (!expected) throw new Error(`INTEGRITY_ASSET_UNDECLARED: ${asset.name}`)
+    if (
+      expected.digest !== asset.digest ||
+      expected.bytes !== asset.bytes ||
+      expected.contentType !== asset.contentType ||
+      expected.kind !== asset.kind ||
+      expected.origin !== asset.origin
+    )
+      throw new Error(`INTEGRITY_ASSET_MISMATCH: ${asset.name}`)
+  }
+}
+
+/**
+ * Re-checks the published consumer index against the catalog it indexes. The
+ * index is what Adea renders directly, so a contradiction between the two
+ * artifacts must never reach a release. Snapshots published before the index
+ * existed carry membership only; those are still membership-checked and
+ * reported as `hasConsumerIndex: false`.
+ */
+export function verifyConsumerIndex(
+  content: string,
+  catalog: Pick<Catalog, 'plugins'>,
+  indexContent?: string
+): ConsumerIndexVerification {
+  const index = JSON.parse(content) as Partial<ConsumerIndex>
+  const knownPlugins = new Map(catalog.plugins.map((plugin) => [plugin.pluginId, plugin]))
+  // Products live in the index shard; the navigation artifact only points at it.
+  const shard = indexContent ? (JSON.parse(indexContent) as Partial<ConsumerIndex>) : undefined
+  const products =
+    shard && typeof shard.products === 'object' && shard.products !== null
+      ? shard.products
+      : typeof index.products === 'object' && index.products !== null
+        ? index.products
+        : undefined
+  const diagnostics = Array.isArray(index.diagnostics) ? index.diagnostics : []
+  for (const category of index.categories ?? []) {
+    const members = catalog.plugins.filter((plugin) =>
+      plugin.categories.includes(category.category)
+    )
+    if (category.pluginCount !== undefined && category.pluginCount !== members.length)
+      throw new Error(`CONSUMER_INDEX_PLUGIN_COUNT_MISMATCH: ${category.category}`)
+    if (category.pluginIds.length !== members.length)
+      throw new Error(`CONSUMER_INDEX_PLUGIN_LIST_MISMATCH: ${category.category}`)
+    if (new Set(category.pluginIds).size !== category.pluginIds.length)
+      throw new Error(`CONSUMER_INDEX_DUPLICATE_PLUGIN: ${category.category}`)
+    for (const pluginId of category.pluginIds) {
+      const plugin = knownPlugins.get(pluginId)
+      if (!plugin || !plugin.categories.includes(category.category))
+        throw new Error(`CONSUMER_INDEX_FOREIGN_PLUGIN: ${category.category}: ${pluginId}`)
+    }
+    if (!products) continue
+    if (category.productKeys === undefined || category.topProductKeys === undefined)
+      throw new Error(`CONSUMER_INDEX_PRODUCTS_INCOMPLETE: ${category.category}`)
+    if (new Set(category.productKeys).size !== category.productKeys.length)
+      throw new Error(`CONSUMER_INDEX_DUPLICATE_PRODUCT: ${category.category}`)
+    for (const productKey of category.productKeys) {
+      const product = products[productKey]
+      if (!product) throw new Error(`CONSUMER_INDEX_UNKNOWN_PRODUCT: ${productKey}`)
+      if (!product.categories.includes(category.category))
+        throw new Error(`CONSUMER_INDEX_PRODUCT_CATEGORY_MISMATCH: ${productKey}`)
+    }
+    if (category.productCount !== category.productKeys.length)
+      throw new Error(`CONSUMER_INDEX_PRODUCT_COUNT_MISMATCH: ${category.category}`)
+    const topCount = index.topCount
+    if (topCount === undefined || !Number.isInteger(topCount) || topCount < 0)
+      throw new Error('CONSUMER_INDEX_TOP_COUNT_INVALID')
+    if (category.topProductKeys.length > topCount)
+      throw new Error(`CONSUMER_INDEX_TOP_OVERFLOW: ${category.category}`)
+    const shelved = new Set<string>()
+    for (const product of Object.values(products)) {
+      // Indexes published before the install facts existed carry no `release`,
+      // and are still valid; a record that does carry one must agree with the
+      // catalog it claims to describe.
+      if (product.release) {
+        const plugin = knownPlugins.get(product.pluginId)
+        const release = plugin?.availableReleases.find(
+          (candidate) => candidate.releaseId === plugin.currentReleaseId
+        )
+        if (
+          !plugin ||
+          !release ||
+          product.release.releaseId !== release.releaseId ||
+          product.release.canonicalContentDigest !== release.canonicalContentDigest ||
+          product.release.sourceRevision !== release.resolvedCommitSha ||
+          product.provenance?.resolvedCommitSha !== release.resolvedCommitSha
+        )
+          throw new Error(`CONSUMER_INDEX_RELEASE_MISMATCH: ${product.productKey}`)
+      }
+      const icon = product.icon
+      if (!icon?.assetUrl) continue
+      if (!icon.assetUrl.startsWith('https://') || !icon.assetUrl.endsWith(`/${icon.asset}`))
+        throw new Error(`CONSUMER_INDEX_ASSET_URL_INVALID: ${icon.asset}`)
+    }
+    for (const productKey of category.topProductKeys) {
+      if (!category.productKeys.includes(productKey))
+        throw new Error(`CONSUMER_INDEX_TOP_NOT_MEMBER: ${category.category}: ${productKey}`)
+      if (shelved.has(productKey)) throw new Error(`CONSUMER_INDEX_TOP_REPEATED: ${productKey}`)
+      shelved.add(productKey)
+    }
+  }
+  if (products) {
+    // A product headlines one category only, so no product is shelved twice.
+    const claimed = new Set<string>()
+    for (const category of index.categories ?? [])
+      for (const productKey of category.topProductKeys ?? []) {
+        if (claimed.has(productKey))
+          throw new Error(`CONSUMER_INDEX_TOP_CROSS_CATEGORY: ${productKey}`)
+        claimed.add(productKey)
+      }
+    for (const [productKey, product] of Object.entries(products)) {
+      if (productKey !== product.productKey) throw new Error('CONSUMER_INDEX_PRODUCT_KEY_MISMATCH')
+      if (product.variantPluginIds[0] !== product.pluginId)
+        throw new Error(`CONSUMER_INDEX_CANONICAL_NOT_FIRST: ${productKey}`)
+      const variants = new Set(
+        product.variantPluginIds.map((pluginId) => {
+          const plugin = knownPlugins.get(pluginId)
+          if (!plugin) throw new Error(`CONSUMER_INDEX_UNKNOWN_PLUGIN: ${pluginId}`)
+          if (plugin.productGroupingKey !== productKey)
+            throw new Error(`CONSUMER_INDEX_VARIANT_PRODUCT_MISMATCH: ${pluginId}`)
+          return pluginId
+        })
+      )
+      if (variants.size !== product.variantPluginIds.length)
+        throw new Error(`CONSUMER_INDEX_DUPLICATE_VARIANT: ${productKey}`)
+    }
+    const counts = shard?.counts ?? index.counts
+    if (counts?.plugins !== catalog.plugins.length) throw new Error('CONSUMER_INDEX_TOTAL_MISMATCH')
+    if (counts?.products !== Object.keys(products).length)
+      throw new Error('CONSUMER_INDEX_PRODUCT_TOTAL_MISMATCH')
+    if (counts?.redundantPlugins !== catalog.plugins.length - counts.products)
+      throw new Error('CONSUMER_INDEX_REDUNDANCY_MISMATCH')
+    if (index.counts && shard?.counts && digest(index.counts) !== digest(shard.counts))
+      throw new Error('CONSUMER_INDEX_COUNTS_MISMATCH')
+    if (shard?.topCount !== undefined && index.topCount !== shard.topCount)
+      throw new Error('CONSUMER_INDEX_TOP_COUNT_MISMATCH')
+  }
+  if (products && index.iconCoverage) {
+    const expected = iconCoverage({ products })
+    if (
+      index.iconCoverage.total !== expected.total ||
+      index.iconCoverage.content !== expected.content ||
+      index.iconCoverage.favicon !== expected.favicon ||
+      index.iconCoverage.monogramOnly !== expected.monogramOnly ||
+      index.iconCoverage.monogramProductKeys.join('\n') !== expected.monogramProductKeys.join('\n')
+    )
+      throw new Error('CONSUMER_INDEX_ICON_COVERAGE_MISMATCH')
+  }
+  const shards: ShardArtifact[] = [
+    ...(products ? [{ name: CATALOG_INDEX_ARTIFACT, kind: 'index' as const }] : []),
+    ...(index.categories ?? []).flatMap((category) =>
+      products && category.shelfArtifact && category.listArtifact
+        ? [
+            { name: category.shelfArtifact, kind: 'shelf' as const, category: category.category },
+            { name: category.listArtifact, kind: 'list' as const, category: category.category },
+          ]
+        : []
+    ),
+  ]
+  return {
+    hasConsumerIndex: products !== undefined,
+    diagnostics,
+    ...(products ? { counts: index.counts as ConsumerIndex['counts'] } : {}),
+    ...(products && index.topCount !== undefined ? { topCount: index.topCount } : {}),
+    ...(products ? { products, categories: index.categories ?? [] } : {}),
+    shards: products ? shards : [],
+  }
+}
+
+export function verifyCatalogReferences(
+  catalog: Catalog,
+  policy: CatalogPolicy = DEFAULT_POLICY
+): void {
+  for (const source of catalog.sources) {
+    assertRepositoryAllowed(source.repositoryUrl, policy)
+    validateCatalogPath(source.manifestPath, 'SOURCE_MANIFEST_PATH_INVALID')
+  }
+  for (const plugin of catalog.plugins) {
+    assertRepositoryAllowed(plugin.provenance.repositoryUrl, policy)
+    validateCatalogPath(plugin.provenance.pluginSubdirectory, 'PROVENANCE_PATH_INVALID')
+    for (const release of plugin.availableReleases) {
+      assertRepositoryAllowed(release.resolvedRepositoryUrl, policy)
+      validateCatalogPath(release.pluginSubdirectory, 'RELEASE_PATH_INVALID')
+      for (const path of release.fileIndex) validateCatalogPath(path, 'RELEASE_FILE_PATH_INVALID')
+    }
+  }
+}
+
+function validateCatalogPath(path: string, code: string): void {
+  if (path !== '.') safeRelativePath(path, code)
+}