Skip to content

A full-featured download manager.

34.2 KB
Raw Blame
import { createHash } from 'node:crypto'
import { readdir, readFile, rm } from 'node:fs/promises'
import path from 'node:path'
import { getLogger } from '@core/logger'
import {
  FALLBACK_LOCALE,
  type SupportedLocale,
} from '@shared/constants/locales'
import { AppError, ErrorCode } from '@shared/errors'
import type {
  PluginSecurityDecision,
  PluginSecurityIdentity,
} from '@shared/schemas/plugin-security'
import { semverGt } from '@shared/semver'
import type {
  PluginListDTO,
  PluginManifest,
  PluginSource,
  PluginStateRecord,
} from '@shared/types/plugin'
import type { OfficialPackageProof } from '@shared/types/plugin-install'
import { FfmpegStaging } from './hooks/staging-dir'
import { readInstallRecord } from './install/install-record'
import { readMoextEntry } from './install/moext-reader'
import { loadOfficialPackage } from './install/official-package'
import {
  flattenLocaleDict,
  type ManifestLocaleDict,
  resolveManifestI18n,
} from './manifest/i18n-resolve'
import { parseManifest } from './manifest/parse'
import { resolveInsidePluginDir } from './manifest/path-safety'
import {
  hasSecurityAdmission,
  recordSecurityAdmission,
} from './security/admission-receipts'
import type { PluginSecurityService } from './security/security-service'
import type { PluginStateStore } from './state/plugin-state-store'
import { verifyBuiltinSignature } from './update/signature'

const log = getLogger('plugin:registry')

export interface PluginRegistryOptions {
  security?: PluginSecurityService
  pluginsDir: string // community: <userDataDir>/plugins
  builtinDir: string // built-in: <resourcesDir>/builtin-plugins
  stateStore: PluginStateStore
  hostVersion: string // semver, e.g. '2.5.0'
  // BCP-47 tag (e.g. 'zh-CN'). The registry loads <rootDir>/<l10n>/<lang>.json
  // for placeholder resolution and always falls back to the shared catalog's
  // fallback locale.
  hostLanguage?: SupportedLocale
  // <userDataDir>/builtin-updates — signature-verified hot-update overlay for
  // builtin plugins (BuiltinUpdater's write path). Omitted entirely disables
  // the overlay scan (e.g. tests that don't care about it).
  overlayDir?: string
  /** Injectable for tests; defaults to the pinned build-time keys. */
  signingPubkeys?: ReadonlyArray<string>
  /** Injectable locale reader for deterministic prepare/commit race tests. */
  readLocaleFile?: (filePath: string) => Promise<string>
  /** Host-owned gate for writable community plugin directories. */
  communityDirectoryPolicy?: (
    pluginDir: string
  ) => Promise<{ ok: boolean; reason?: string }>
  /** Shell-provided plugin development directory; omitted outside dev mode. */
  devPath?: string
}

export interface IndexedPlugin {
  archiveSha256?: string
  securityPending?: boolean
  manifestRaw: PluginManifest
  manifest: PluginManifest
  origin: 'community' | 'builtin'
  rootDir: string
  /** SHA-256 of the exact guest entry bytes selected for execution. */
  executableDigest?: string
  state: PluginStateRecord
  /**
   * True when this entry was loaded from MOTRIX_PLUGIN_DEV_PATH. Dev plugins
   * bypass the installer + consent flow (spec §7 L2418-2431) and surface a
   * distinct `PluginSource.type === 'dev'` in PluginListDTO so the renderer
   * can render a "Dev mode" badge.
   */
  dev?: boolean
  /** Official optional packages retain community permission and hook policy. */
  official?: OfficialPackageProof & { recordedAt: number }
  /**
   * Present when this builtin's effective code was earned from the
   * signature-verified <overlayDir>/<id> hot-update overlay rather than the
   * read-only seed tree. Drives `deriveListSource`'s `builtin-update` source.
   * `signature` is the validated `_overlay.json.signature` (base64, over
   * bundle.moext) — carried through so PluginHost can re-verify bundle.moext
   * at load time without re-reading _overlay.json (Firefox packed-XPI model:
   * manifest AND executed code both come from the verified bundle, never the
   * separately-tamperable extracted tree).
   */
  overlay?: { packageUrl: string; recordedAt: number; signature: string }
}

export interface PluginPolicySnapshot {
  pluginId: string
  generation: number
  enabled: boolean
  version: string
  rootDir: string
  executableDigest?: string
}

export interface LoadError {
  pluginDir: string
  code: string
  message: string
}

export interface PluginLocaleDictionaries {
  currentDict: ManifestLocaleDict
  fallbackDict: ManifestLocaleDict
}

interface PreparedPluginLocaleEntry {
  pluginId: string
  indexed: IndexedPlugin
  manifest: PluginManifest
  dictionaries: PluginLocaleDictionaries
}

interface PreparedPluginLocaleChange {
  owner: PluginRegistry
  language: SupportedLocale
  registryRevision: number
  entries: ReadonlyArray<PreparedPluginLocaleEntry>
}

export interface HostLanguageTransactionOptions {
  /** Runs after all plugin files are prepared, immediately before commit. */
  beforeCommit?: () => Promise<void> | void
  /** Must synchronously publish the same locale to the capability host. */
  commitHostLocale: () => void
  /** Restores the host if commitHostLocale unexpectedly throws. */
  rollbackHostLocale: (
    previousLanguage: SupportedLocale
  ) => Promise<void> | void
  /** Cancels stale work before beforeCommit and again before synchronous commit. */
  shouldCommit?: () => boolean
}

export class PluginRegistry {
  private readonly byId = new Map<string, IndexedPlugin>()
  private readonly errors: LoadError[] = []
  private readonly localeDictionaries = new Map<
    string,
    PluginLocaleDictionaries
  >()
  private discoveryTail: Promise<void> = Promise.resolve()
  private registryRevision = 0
  private readonly policyGenerations = new Map<string, number>()
  private currentLang: SupportedLocale

  constructor(private readonly opts: PluginRegistryOptions) {
    this.currentLang = opts.hostLanguage ?? FALLBACK_LOCALE
  }

  private async loadLocale(
    rootDir: string,
    l10n: string | undefined,
    lang: string
  ): Promise<ManifestLocaleDict> {
    if (!l10n) return {}
    // Contain l10n to the plugin dir: a "../../etc" l10n must not read JSON
    // from outside the plugin (its strings surface in the manifest UI).
    const localeDir = resolveInsidePluginDir(rootDir, l10n)
    if (!localeDir) return {}
    try {
      const localePath = path.join(localeDir, `${lang}.json`)
      const raw = this.opts.readLocaleFile
        ? await this.opts.readLocaleFile(localePath)
        : await readFile(localePath, 'utf8')
      const parsed = JSON.parse(raw)
      if (!parsed || typeof parsed !== 'object') return {}
      // Flatten nested entries to dotted keys so manifest placeholders like
      // %nav.title% resolve (matching the runtime i18n.t key space) instead of
      // silently failing when only top-level strings were kept.
      return flattenLocaleDict(parsed as Record<string, unknown>)
    } catch {
      return {}
    }
  }

  private async prepareManifestLocale(
    manifest: PluginManifest,
    rootDir: string,
    language: SupportedLocale
  ): Promise<{
    manifest: PluginManifest
    dictionaries: PluginLocaleDictionaries
  }> {
    const l10n = (manifest as { l10n?: string }).l10n
    // When the active language is the fallback locale, both dictionaries come
    // from the same file, so load it once; otherwise fetch both in parallel.
    let current: ManifestLocaleDict
    let fallback: ManifestLocaleDict
    if (language === FALLBACK_LOCALE) {
      current = await this.loadLocale(rootDir, l10n, FALLBACK_LOCALE)
      fallback = current
    } else {
      ;[current, fallback] = await Promise.all([
        this.loadLocale(rootDir, l10n, language),
        this.loadLocale(rootDir, l10n, FALLBACK_LOCALE),
      ])
    }
    const dictionaries = {
      currentDict: current,
      fallbackDict: fallback,
    }
    try {
      return {
        manifest: resolveManifestI18n(manifest, dictionaries),
        dictionaries,
      }
    } catch (e) {
      // resolveManifestI18n throws on mixed-placeholder; leave manifest
      // as-is so the registry still indexes the plugin and the load
      // error surfaces in errors[].
      log.warn(
        { err: e, pluginId: manifest.id },
        'i18n resolution failed; falling back to raw manifest'
      )
      return { manifest, dictionaries }
    }
  }

  private async i18nResolve(
    manifest: PluginManifest,
    rootDir: string
  ): Promise<PluginManifest> {
    const prepared = await this.prepareManifestLocale(
      manifest,
      rootDir,
      this.currentLang
    )
    this.localeDictionaries.set(manifest.id, prepared.dictionaries)
    return prepared.manifest
  }

  discover(): Promise<void> {
    const pending = this.discoveryTail.then(() => this.performDiscover())
    this.discoveryTail = pending.catch(() => {})
    return pending
  }

  private async performDiscover(): Promise<void> {
    this.registryRevision += 1
    const previousPolicy = new Map(
      [...this.byId.entries()].map(([id, entry]) => [
        id,
        executablePolicyFingerprint(entry),
      ])
    )
    try {
      try {
        await FfmpegStaging.cleanupOrphans(this.opts.pluginsDir)
      } catch (e) {
        log.warn({ err: e }, 'ffmpeg staging orphan cleanup failed; continuing')
      }
      this.byId.clear()
      this.errors.length = 0
      this.localeDictionaries.clear()
      await this.scanInto(this.opts.builtinDir, 'builtin')
      if (this.opts.overlayDir) await this.applyOverlay(this.opts.overlayDir)
      await this.scanInto(this.opts.pluginsDir, 'community')
      const devPath = this.opts.devPath
      if (devPath) {
        try {
          const raw = await readFile(
            path.join(devPath, 'motrix-plugin.json'),
            'utf8'
          )
          const { manifest } = parseManifest(raw, {
            hostVersion: this.opts.hostVersion,
            origin: 'community',
          })
          const resolved = await this.i18nResolve(manifest, devPath)
          const state = this.getOrCreateState(resolved.id)
          const executableDigest = await digestFile(
            resolveInsidePluginDir(devPath, resolved.main)
          )
          this.byId.set(resolved.id, {
            manifestRaw: manifest,
            manifest: resolved,
            origin: 'community',
            rootDir: devPath,
            executableDigest,
            state,
            dev: true,
          })
        } catch (e: unknown) {
          log.warn(
            { err: e, devPath },
            'MOTRIX_PLUGIN_DEV_PATH: failed to load dev plugin manifest'
          )
        }
      }
      const discoveredIds = new Set(this.byId.keys())
      for (const [id, entry] of this.byId) {
        const previous = previousPolicy.get(id)
        if (previous !== executablePolicyFingerprint(entry)) {
          this.bumpPolicyGeneration(id)
        } else if (!this.policyGenerations.has(id)) {
          this.policyGenerations.set(id, 1)
        }
      }
      for (const id of previousPolicy.keys()) {
        if (!discoveredIds.has(id)) this.bumpPolicyGeneration(id)
      }
    } finally {
      this.registryRevision += 1
    }
  }

  /**
   * Read and resolve every plugin locale without mutating observable registry
   * state. Active bridges therefore continue to see a complete old snapshot
   * for the entire asynchronous prepare phase.
   */
  private async prepareHostLanguage(
    language: SupportedLocale
  ): Promise<PreparedPluginLocaleChange> {
    // Wait for any discovery that was already registered. A later discovery
    // invalidates registryRevision, making commitHostLanguage reject + retry.
    await this.discoveryTail
    const registryRevision = this.registryRevision
    if (language === this.currentLang) {
      return {
        owner: this,
        language,
        registryRevision,
        entries: [],
      }
    }

    const indexedEntries = [...this.byId.values()]
    const entries = await Promise.all(
      indexedEntries.map(async (indexed) => ({
        pluginId: indexed.manifestRaw.id,
        indexed,
        ...(await this.prepareManifestLocale(
          indexed.manifestRaw,
          indexed.rootDir,
          language
        )),
      }))
    )
    return {
      owner: this,
      language,
      registryRevision,
      entries,
    }
  }

  private canCommitHostLanguage(
    prepared: PreparedPluginLocaleChange,
    shouldCommit: () => boolean = () => true
  ): boolean {
    return !(
      !shouldCommit() ||
      prepared.owner !== this ||
      prepared.registryRevision !== this.registryRevision ||
      prepared.entries.some(
        ({ pluginId, indexed }) => this.byId.get(pluginId) !== indexed
      )
    )
  }

  /**
   * Synchronously publishes a validated locale and capability snapshot in the
   * same JavaScript turn. The promise is used only to await exceptional
   * rollback; the successful publication itself contains no async boundary.
   */
  private async commitHostLanguage(
    prepared: PreparedPluginLocaleChange,
    onCommit: () => void,
    onRollback: (previousLanguage: SupportedLocale) => Promise<void> | void,
    shouldCommit: () => boolean = () => true
  ): Promise<boolean> {
    if (!this.canCommitHostLanguage(prepared, shouldCommit)) return false

    const previousLanguage = this.currentLang
    const previousEntries = prepared.entries.map(({ pluginId, indexed }) => ({
      pluginId,
      indexed,
      manifest: indexed.manifest,
      dictionaries: this.localeDictionaries.get(pluginId),
    }))
    this.currentLang = prepared.language
    for (const {
      pluginId,
      indexed,
      manifest,
      dictionaries,
    } of prepared.entries) {
      indexed.manifest = manifest
      this.localeDictionaries.set(pluginId, dictionaries)
    }
    this.registryRevision += 1
    try {
      onCommit()
    } catch (error) {
      this.currentLang = previousLanguage
      for (const {
        pluginId,
        indexed,
        manifest,
        dictionaries,
      } of previousEntries) {
        indexed.manifest = manifest
        if (dictionaries) this.localeDictionaries.set(pluginId, dictionaries)
        else this.localeDictionaries.delete(pluginId)
      }
      this.registryRevision += 1
      try {
        await onRollback(previousLanguage)
      } catch (rollbackError) {
        throw new AggregateError(
          [error, rollbackError],
          'plugin locale commit and rollback both failed'
        )
      }
      throw error
    }
    return true
  }

  /** Atomically switch registry-only consumers such as manifest list tests. */
  async setHostLanguage(language: SupportedLocale): Promise<void> {
    await this.setHostLanguageTransaction(language, {
      commitHostLocale: () => {},
      rollbackHostLocale: () => {},
    })
  }

  /** Prepare asynchronously, then atomically commit registry + host locale. */
  async setHostLanguageTransaction(
    language: SupportedLocale,
    options: HostLanguageTransactionOptions
  ): Promise<boolean> {
    const shouldCommit = options.shouldCommit ?? (() => true)
    for (;;) {
      if (!shouldCommit()) return false
      const prepared = await this.prepareHostLanguage(language)
      if (!this.canCommitHostLanguage(prepared, shouldCommit)) {
        if (!shouldCommit()) return false
        continue
      }

      const previousLanguage = this.currentLang
      try {
        await options.beforeCommit?.()
      } catch (error) {
        try {
          await options.rollbackHostLocale(previousLanguage)
        } catch (rollbackError) {
          throw new AggregateError(
            [error, rollbackError],
            'plugin locale prepare-commit and rollback both failed'
          )
        }
        throw error
      }

      if (!this.canCommitHostLanguage(prepared, shouldCommit)) {
        await options.rollbackHostLocale(previousLanguage)
        if (!shouldCommit()) return false
        continue
      }
      const committed = await this.commitHostLanguage(
        prepared,
        options.commitHostLocale,
        options.rollbackHostLocale,
        shouldCommit
      )
      if (committed) return true
      await options.rollbackHostLocale(previousLanguage)
      if (!shouldCommit()) return false
    }
  }

  private getOrCreateState(pluginId: string): PluginStateRecord {
    const existing = this.opts.stateStore.get(pluginId)
    if (existing) return existing
    const state: PluginStateRecord = {
      pluginId,
      enabled: true,
      status: 'inactive',
      errorCount: 0,
      installedAt: Date.now(),
    }
    this.opts.stateStore.upsert(state)
    return state
  }

  private async scanInto(
    root: string,
    origin: 'community' | 'builtin'
  ): Promise<void> {
    let entries: string[] = []
    try {
      entries = await readdir(root)
    } catch (e: unknown) {
      const code = (e as NodeJS.ErrnoException).code
      if (code === 'ENOENT') return
      throw e
    }
    for (const name of entries) {
      if (origin === 'community' && name.startsWith('_')) continue
      const dir = path.join(root, name)
      try {
        if (origin === 'community' && this.opts.communityDirectoryPolicy) {
          const policy = await this.opts.communityDirectoryPolicy(dir)
          if (!policy.ok) {
            this.errors.push({
              pluginDir: dir,
              code: ErrorCode.PluginManifestInvalid,
              message: policy.reason ?? 'plugin.lifecycle.unsigned_not_allowed',
            })
            continue
          }
        }
        const record =
          origin === 'community' ? await readInstallRecord(dir) : null
        const officialArchive = record?.official
          ? await loadOfficialPackage(
              dir,
              record.official,
              this.opts.signingPubkeys
            )
          : undefined
        const manifestBytes = officialArchive
          ? await readMoextEntry(officialArchive.bytes, 'motrix-plugin.json')
          : undefined
        if (officialArchive && !manifestBytes) {
          throw new AppError(
            ErrorCode.PluginManifestInvalid,
            'plugin.install.official_signature_invalid'
          )
        }
        const raw =
          manifestBytes?.toString('utf8') ??
          (await readFile(path.join(dir, 'motrix-plugin.json'), 'utf8'))
        const { manifest } = parseManifest(raw, {
          hostVersion: this.opts.hostVersion,
          origin,
          official: officialArchive !== undefined,
        })
        if (officialArchive && record?.pluginId !== manifest.id) {
          throw new AppError(
            ErrorCode.PluginManifestInvalid,
            'plugin.install.official_signature_invalid'
          )
        }
        if (manifest.id !== name) {
          this.errors.push({
            pluginDir: dir,
            code: 'plugin.manifest.id_mismatch_with_dir',
            message: `manifest id "${manifest.id}" does not match directory name "${name}"`,
          })
          continue
        }
        if (this.byId.has(manifest.id)) {
          this.errors.push({
            pluginDir: dir,
            code: 'plugin.manifest.duplicate_id',
            message: `duplicate plugin id "${manifest.id}"`,
          })
          continue
        }
        const resolved = await this.i18nResolve(manifest, dir)
        const state = this.getOrCreateState(resolved.id)
        const signedExecutable = officialArchive
          ? await readMoextEntry(officialArchive.bytes, resolved.main)
          : undefined
        if (officialArchive && !signedExecutable) {
          throw new AppError(
            ErrorCode.PluginManifestInvalid,
            'plugin.install.official_signature_invalid'
          )
        }
        const executableDigest = signedExecutable
          ? digestBytes(signedExecutable)
          : await digestFile(resolveInsidePluginDir(dir, resolved.main))
        this.byId.set(resolved.id, {
          manifestRaw: manifest,
          manifest: resolved,
          origin,
          rootDir: dir,
          executableDigest,
          archiveSha256:
            record?.official?.archiveSha256 ?? record?.source.archiveSha256,
          securityPending:
            record?.securityReviewed === false &&
            !(await hasSecurityAdmission(
              this.opts.pluginsDir,
              record.source.archiveSha256
            )),
          state,
          ...(record?.official
            ? {
                official: {
                  ...record.official,
                  recordedAt: record.source.recordedAt,
                },
              }
            : {}),
        })
      } catch (e: unknown) {
        // For AppError (PluginManifestInvalid / PluginEngineVersionTooOld),
        // surface the enum string value (e.g. 'PLUGIN_ENGINE_VERSION_TOO_OLD').
        // For unknown errors, fall back to 'PLUGIN_MANIFEST_INVALID'.
        const code =
          e instanceof AppError ? e.code : ErrorCode.PluginManifestInvalid
        this.errors.push({
          pluginDir: dir,
          code,
          message: (e as Error).message,
        })
      }
    }
  }

  /**
   * Signature-gated builtin hot-update overlay pass (2026-07-18 design §3
   * consumer half). Runs after the builtin seed scan and before the
   * community scan. CRITICAL INVARIANT: origin 'builtin' is EARNED here by
   * re-verifying the stored bundle.moext against _overlay.json.signature and
   * the pinned keys on EVERY scan — the overlay lives in OS-writable
   * userData, so an unverified entry is an attack, not a plugin.
   */
  private async applyOverlay(root: string): Promise<void> {
    let names: string[] = []
    try {
      names = await readdir(root)
    } catch (e: unknown) {
      if ((e as NodeJS.ErrnoException).code === 'ENOENT') return
      throw e
    }
    for (const name of names) {
      if (name.startsWith('.tmp-') || name.startsWith('.bak-')) continue
      const dir = path.join(root, name)
      const drop = () => rm(dir, { recursive: true, force: true })

      // Every step below runs inside this per-entry guard: the overlay dir
      // is OS-writable userData, so ANY unexpected throw here (a shape we
      // didn't anticipate, a downstream helper misbehaving, ...) must be
      // treated the same as a known-corrupt entry — log + drop + keep
      // scanning — rather than escaping applyOverlay and failing the whole
      // discover() call. The deliberate PluginEngineVersionTooOld
      // ignore-not-delete branch below uses a bare `continue`, which skips
      // this catch entirely (as intended — that path is not corruption).
      try {
        // 1. Signature gate — origin 'builtin' is EARNED here, never assumed
        //    from directory location (the overlay lives in OS-writable
        //    userData; an unsigned entry is an attack, not a plugin).
        let meta: unknown
        let bundle: Buffer
        try {
          meta = JSON.parse(
            await readFile(path.join(dir, '_overlay.json'), 'utf8')
          )
          bundle = await readFile(path.join(dir, 'bundle.moext'))
        } catch {
          await drop()
          continue
        }
        // JSON.parse succeeds on plenty of non-object input (`null`, `42`,
        // `"str"`, ...) — validate SHAPE before touching meta.signature /
        // meta.packageUrl / meta.recordedAt, or a malformed-but-parseable
        // file crashes the property access outside any try/catch.
        if (!isValidOverlayMeta(meta)) {
          log.warn({ dir }, 'malformed overlay metadata dropped')
          await drop()
          continue
        }
        if (
          !verifyBuiltinSignature(
            bundle,
            meta.signature,
            this.opts.signingPubkeys
          )
        ) {
          log.warn({ dir }, 'unsigned/tampered builtin overlay dropped')
          await drop()
          continue
        }

        // 2. Orphan gate — a builtin retired from the seed set retires its
        //    overlay. Uses the seed DIRECTORY, not the parsed map: a corrupt
        //    seed manifest must never trigger overlay deletion.
        let seedDirExists = true
        try {
          await readFile(
            path.join(this.opts.builtinDir, name, 'motrix-plugin.json'),
            'utf8'
          )
        } catch {
          seedDirExists = false
        }
        if (!seedDirExists) {
          await drop()
          continue
        }

        // 3. Parse the manifest from the VERIFIED BUNDLE, never the tree
        //    (Firefox packed-XPI model — 2026-07-18 design §4). The
        //    extracted tree is OS-writable and, from here on, serves
        //    display-only assets (l10n) only; the signature gate above only
        //    proves bundle.moext's bytes are untampered, so the manifest we
        //    trust must come from those same bytes, not a sibling file an
        //    attacker could edit independently. Engine incompatibility is
        //    IGNORED (not deleted — an app upgrade may revalidate it); a
        //    missing entry or parse failure is corruption (deleted — seed is
        //    the availability floor).
        let manifest: PluginManifest
        try {
          const manifestBytes = await readMoextEntry(
            bundle,
            'motrix-plugin.json'
          )
          if (!manifestBytes) {
            log.warn(
              { dir },
              'overlay bundle missing motrix-plugin.json; dropped'
            )
            await drop()
            continue
          }
          manifest = parseManifest(manifestBytes.toString('utf8'), {
            hostVersion: this.opts.hostVersion,
            origin: 'builtin',
          }).manifest as PluginManifest
        } catch (e: unknown) {
          if (
            e instanceof AppError &&
            e.code === ErrorCode.PluginEngineVersionTooOld
          ) {
            continue
          }
          log.warn({ dir }, 'corrupt overlay manifest dropped')
          await drop()
          continue
        }
        if (manifest.id !== name) {
          log.warn({ dir }, 'overlay manifest id mismatch dropped')
          await drop()
          continue
        }

        // 4. Arbitration vs the parsed seed (if the seed parsed at all).
        const seed = this.byId.get(manifest.id)
        if (seed && !semverGt(manifest.version, seed.manifest.version)) {
          // seed >= overlay → Chrome-style retirement of the stale overlay
          await drop()
          continue
        }

        const resolved = await this.i18nResolve(manifest, dir)
        const state = this.getOrCreateState(resolved.id)
        const executable = await readMoextEntry(bundle, resolved.main)
        if (!executable) {
          log.warn({ dir }, 'overlay bundle missing guest entry; dropped')
          await drop()
          continue
        }
        this.byId.set(resolved.id, {
          manifestRaw: manifest,
          manifest: resolved,
          origin: 'builtin',
          rootDir: dir,
          executableDigest: digestBytes(executable),
          archiveSha256: digestBytes(bundle),
          state,
          overlay: {
            packageUrl: meta.packageUrl,
            recordedAt: meta.recordedAt,
            signature: meta.signature,
          },
        })
      } catch (e: unknown) {
        log.warn(
          { err: e, dir },
          'unexpected error scanning builtin overlay entry; dropped'
        )
        await drop()
      }
    }
  }

  get(pluginId: string): IndexedPlugin | undefined {
    return this.byId.get(pluginId)
  }

  /**
   * Return the dictionaries loaded while resolving a plugin manifest. The
   * runtime capability host consumes this cache so manifest placeholders and
   * `motrix.i18n.t()` always switch from the same locale snapshot.
   */
  getLocaleDictionaries(pluginId: string): PluginLocaleDictionaries {
    return (
      this.localeDictionaries.get(pluginId) ?? {
        currentDict: {},
        fallbackDict: {},
      }
    )
  }

  /**
   * Re-read the plugin's row from the PluginStateStore and write it back into
   * the in-memory IndexedPlugin.state. Call after any external mutation of the
   * state store (Commands.Enable/DisablePlugin, PluginHost lifecycle writes)
   * so downstream readers — list(), PluginHost.activate gating,
   * ActivationDispatcher, CrossPluginInvoker — see fresh values without
   * waiting for a process restart / re-discover.
   */
  refreshState(pluginId: string): void {
    const entry = this.byId.get(pluginId)
    if (!entry) return
    const fresh = this.opts.stateStore.get(pluginId)
    if (fresh) {
      const enabledChanged = fresh.enabled !== entry.state.enabled
      entry.state = fresh
      if (enabledChanged) this.bumpPolicyGeneration(pluginId)
    }
  }

  /** Current live-policy generation bound to guest admission and deliveries. */
  policyGenerationFor(pluginId: string): number {
    return this.policyGenerations.get(pluginId) ?? 0
  }

  /**
   * Advance a plugin's live-policy generation. Grant and executable mutation
   * barriers call this only after old admission has closed and drained.
   */
  bumpPolicyGeneration(pluginId: string): number {
    const next = (this.policyGenerations.get(pluginId) ?? 0) + 1
    this.policyGenerations.set(pluginId, next)
    return next
  }

  policySnapshot(pluginId: string): PluginPolicySnapshot | undefined {
    const entry = this.byId.get(pluginId)
    if (!entry) return undefined
    return {
      pluginId,
      generation: this.policyGenerationFor(pluginId),
      enabled: entry.state.enabled && !this.securityDecision(pluginId),
      version: entry.manifest.version,
      rootDir: entry.rootDir,
      executableDigest: entry.executableDigest,
    }
  }

  /**
   * Minimal indexed view consumed by the query helpers in @core/plugin/queries.
   * Decouples those helpers from `IndexedPlugin`'s state row, which is heavier
   * than they need (they care only about `manifest`, `origin`, `enabled`).
   */
  entries(): Array<{
    manifest: PluginManifest
    origin: 'community' | 'builtin'
    enabled: boolean
    executableDigest?: string
  }> {
    const out: Array<{
      manifest: PluginManifest
      origin: 'community' | 'builtin'
      enabled: boolean
      executableDigest?: string
    }> = []
    for (const p of this.byId.values()) {
      out.push({
        manifest: p.manifest,
        origin: p.origin,
        enabled: p.state.enabled && !this.securityDecision(p.manifest.id),
        executableDigest: p.executableDigest,
      })
    }
    return out
  }

  list(): PluginListDTO[] {
    const out: PluginListDTO[] = []
    for (const p of this.byId.values()) {
      out.push({
        id: p.manifest.id,
        name: p.manifest.name,
        version: p.manifest.version,
        description: p.manifest.description,
        status: p.state.status,
        enabled: p.state.enabled,
        permissions: p.manifest.permissions,
        optionalPermissions: p.manifest.optionalPermissions ?? [],
        errorCount: p.state.errorCount,
        lastError: p.state.lastError,
        source: deriveListSource(p),
        security: this.securityDecision(p.manifest.id),
      })
    }
    return out
  }

  loadErrors(): ReadonlyArray<LoadError> {
    return this.errors
  }

  securityIdentity(pluginId: string): PluginSecurityIdentity | undefined {
    const entry = this.byId.get(pluginId)
    return entry
      ? {
          pluginId,
          version: entry.manifest.version,
          archiveSha256: entry.archiveSha256,
        }
      : undefined
  }

  securityDecision(pluginId: string): PluginSecurityDecision | undefined {
    const identity = this.securityIdentity(pluginId)
    if (!identity) return undefined
    const decision = this.opts.security?.decision(identity)
    if (decision) return decision
    if (
      this.byId.get(pluginId)?.securityPending &&
      this.opts.security &&
      !this.opts.security.isFresh()
    ) {
      return { blocked: true, reason: 'pending', advisoryIds: [] }
    }
    return undefined
  }

  assertSecurityAllowed(pluginId: string): void {
    const decision = this.securityDecision(pluginId)
    if (decision)
      throw new AppError(
        decision.reason === 'pending'
          ? ErrorCode.PluginSecurityPending
          : ErrorCode.PluginSecurityBlocked,
        decision.reason === 'pending'
          ? 'plugins.security.pending'
          : 'plugins.security.blocked'
      )
  }

  async recordSecurityAdmission(pluginId: string): Promise<void> {
    this.assertSecurityAllowed(pluginId)
    const entry = this.byId.get(pluginId)
    if (!entry?.securityPending) return
    if (!entry.archiveSha256) {
      throw new AppError(
        ErrorCode.PluginSecurityPending,
        'plugins.security.pending'
      )
    }
    await recordSecurityAdmission(this.opts.pluginsDir, entry.archiveSha256)
    this.assertSecurityAllowed(pluginId)
    if (this.byId.get(pluginId) === entry) entry.securityPending = false
  }
}

/**
 * Type guard for `_overlay.json` contents. JSON.parse alone is not enough —
 * it happily accepts `null`, `42`, `"str"`, `{}`, etc. as valid JSON, and an
 * unguarded `meta.signature` access on any of those throws a TypeError that
 * would otherwise escape applyOverlay's per-entry try/catch.
 */
function isValidOverlayMeta(
  value: unknown
): value is { packageUrl: string; signature: string; recordedAt: number } {
  if (typeof value !== 'object' || value === null) return false
  const v = value as Record<string, unknown>
  return (
    typeof v.signature === 'string' &&
    typeof v.packageUrl === 'string' &&
    typeof v.recordedAt === 'number'
  )
}

function executablePolicyFingerprint(entry: IndexedPlugin): string {
  return JSON.stringify({
    executableDigest: entry.executableDigest ?? null,
    enabled: entry.state.enabled,
    manifest: entry.manifestRaw,
    origin: entry.origin,
    overlaySignature: entry.overlay?.signature ?? null,
    official: entry.official ?? null,
    rootDir: entry.rootDir,
  })
}

async function digestFile(filePath: string | null): Promise<string> {
  if (!filePath) {
    throw new AppError(
      ErrorCode.PluginManifestInvalid,
      'plugin.manifest.main_escapes_dir'
    )
  }
  return digestBytes(await readFile(filePath))
}

function digestBytes(bytes: Uint8Array): string {
  return createHash('sha256').update(bytes).digest('hex')
}

function deriveListSource(p: IndexedPlugin): PluginSource | undefined {
  if (p.official) {
    return {
      type: 'official',
      url: `registry:${p.manifest.id}`,
      recordedAt: p.official.recordedAt,
    }
  }
  if (p.origin === 'builtin') {
    return p.overlay
      ? {
          type: 'builtin-update',
          url: p.overlay.packageUrl,
          recordedAt: p.overlay.recordedAt,
        }
      : { type: 'builtin', url: 'builtin', recordedAt: 0 }
  }
  if (p.dev) {
    return { type: 'dev', url: p.rootDir, recordedAt: 0 }
  }
  return undefined
}