@adea-ai/plugins 4.0.1 → 4.0.6

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)
+}

package/src/write-artifacts.test.ts

@@ -315,7 +315,6 @@ describe('crash recovery', () => {
       expect(await readFile(join(`${output}.previous`, 'recovery'), 'utf8')).toBe('saved')
       expect(await read(output)).toBe('current')
       expect(await withCatalogRead(output, () => read(output))).toBe('current')
-      expect(await readFile(join(`${output}.previous`, 'recovery'), 'utf8')).toBe('saved')
     }))
 
   test('a failed write keeps the previous catalog and releases the lock', () =>

package/dist/source-digest.d.ts

@@ -1,2 +0,0 @@
-/** Shared source-byte identity for catalog provenance and canonical package recipes. */
-export declare function sourceDigest(files: ReadonlyMap<string, Uint8Array>): string;

package/dist/source-digest.js

@@ -1,12 +0,0 @@
-import { createHash } from 'node:crypto';
-/** Shared source-byte identity for catalog provenance and canonical package recipes. */
-export function sourceDigest(files) {
-    const hash = createHash('sha256');
-    // English matches the compiler runtime; ordinal ties distinguish equivalent Unicode names.
-    for (const [path, bytes] of [...files].toSorted(([a], [b]) => a.localeCompare(b, 'en') || (a < b ? -1 : a > b ? 1 : 0))) {
-        hash.update(`${path.length}:${path}:${bytes.byteLength}:`);
-        hash.update(bytes);
-    }
-    return `sha256:${hash.digest('hex')}`;
-}
-//# sourceMappingURL=source-digest.js.map

package/dist/source-digest.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"source-digest.js","sourceRoot":"","sources":["../src/source-digest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,wFAAwF;AACxF,MAAM,UAAU,YAAY,CAAC,KAAsC;IACjE,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAA;IACjC,2FAA2F;IAC3F,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,QAAQ,CAC7C,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACvE,EAAE,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,IAAI,KAAK,CAAC,UAAU,GAAG,CAAC,CAAA;QAC1D,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACpB,CAAC;IACD,OAAO,UAAU,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;AACvC,CAAC"}

package/src/source-digest.ts

@@ -1,14 +0,0 @@
-import { createHash } from 'node:crypto'
-
-/** Shared source-byte identity for catalog provenance and canonical package recipes. */
-export function sourceDigest(files: ReadonlyMap<string, Uint8Array>): string {
-  const hash = createHash('sha256')
-  // English matches the compiler runtime; ordinal ties distinguish equivalent Unicode names.
-  for (const [path, bytes] of [...files].toSorted(
-    ([a], [b]) => a.localeCompare(b, 'en') || (a < b ? -1 : a > b ? 1 : 0)
-  )) {
-    hash.update(`${path.length}:${path}:${bytes.byteLength}:`)
-    hash.update(bytes)
-  }
-  return `sha256:${hash.digest('hex')}`
-}