@pellux/goodvibes-tui 0.18.4

package/src/runtime/plugins/manifest.ts

@@ -0,0 +1,167 @@
+/**
+ * Plugin capability manifest validation and resolution.
+ *
+ * Implements deny-by-default capability enforcement:
+ * 1. Parse raw manifest capabilities (unknown → typed)
+ * 2. Validate that each requested capability is a known capability
+ * 3. Run the runtime's capability policy to grant or deny each capability
+ * 4. Return a resolved PluginCapabilityManifest
+ */
+
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import {
+  ALL_CAPABILITIES,
+  HIGH_RISK_CAPABILITIES,
+  type PluginCapability,
+  type PluginCapabilityManifest,
+  type PluginManifestV2,
+} from './types.ts';
+import { type PluginTrustTier, filterCapabilitiesByTrust } from './trust.ts';
+
+/**
+ * Default capability policy: grant all valid capabilities.
+ *
+ * Callers can supply a stricter policy via PluginLifecycleManagerOptions.
+ */
+function defaultPolicy(_pluginName: string, _capability: PluginCapability): boolean {
+  return true;
+}
+
+/**
+ * Returns whether a string value is a known PluginCapability.
+ */
+function isKnownCapability(value: string): value is PluginCapability {
+  return (ALL_CAPABILITIES as ReadonlyArray<string>).includes(value);
+}
+
+/**
+ * resolveCapabilityManifest — Parse and resolve the capability manifest for a
+ * plugin, applying the runtime's capability policy and trust-tier constraints.
+ *
+ * Evaluation order:
+ *   1. Unknown capability strings are filtered out (warn + ignore).
+ *   2. Trust-tier constraints are applied — high-risk capabilities blocked
+ *      unless the plugin has the `trusted` tier.
+ *   3. The runtime capability policy callback is applied to the remaining set.
+ *
+ * @param pluginName - Plugin name (for logging).
+ * @param manifest   - The raw plugin manifest (may have `capabilities` array).
+ * @param policy     - Capability grant/deny callback. Defaults to permissive.
+ * @param trustTier  - Effective trust tier for this plugin. Defaults to 'untrusted'.
+ * @returns A fully-resolved PluginCapabilityManifest.
+ */
+export function resolveCapabilityManifest(
+  pluginName: string,
+  manifest: PluginManifestV2,
+  policy: (name: string, cap: PluginCapability) => boolean = defaultPolicy,
+  trustTier: PluginTrustTier = 'untrusted',
+): PluginCapabilityManifest {
+  const rawRequested = manifest.capabilities ?? [];
+
+  // Validate and filter unknown capability strings.
+  const requested: PluginCapability[] = [];
+  for (const raw of rawRequested) {
+    if (isKnownCapability(raw)) {
+      requested.push(raw);
+    } else {
+      logger.warn(
+        `[plugin-lifecycle:${pluginName}] Unknown capability '${raw}' — ignored`,
+      );
+    }
+  }
+
+  // Apply trust-tier constraints before the policy callback.
+  const trustResult = filterCapabilitiesByTrust(requested, trustTier);
+  if (trustResult.blocked.length > 0) {
+    logger.warn(
+      `[plugin-lifecycle:${pluginName}] Trust tier '${trustTier}' blocks` +
+      ` high-risk capabilities: [${trustResult.blocked.join(', ')}]` +
+      ' — trust escalation required',
+    );
+  }
+
+  // Only the trust-permitted capabilities proceed to policy evaluation.
+  const afterTrust = trustResult.permitted;
+
+  const granted: PluginCapability[] = [];
+  const denied: PluginCapability[] = [...trustResult.blocked];
+  const denialReasons: Partial<Record<PluginCapability, string>> = { ...trustResult.reasons };
+
+  for (const cap of afterTrust) {
+    if (policy(pluginName, cap)) {
+      granted.push(cap);
+    } else {
+      denied.push(cap);
+      denialReasons[cap] = `Capability '${cap}' denied by runtime policy`;
+      logger.warn(
+        `[plugin-lifecycle:${pluginName}] Capability '${cap}' denied by policy`,
+      );
+    }
+  }
+
+  logger.debug(
+    `[plugin-lifecycle:${pluginName}] Capabilities resolved (trust=${trustTier})` +
+    ` — granted: [${granted.join(', ')}]` +
+    (denied.length > 0 ? `, denied: [${denied.join(', ')}]` : ''),
+  );
+
+  return {
+    requested: Object.freeze(requested),
+    granted,
+    denied,
+    denialReasons,
+  };
+}
+
+/**
+ * isHighRiskCapability — Returns whether a capability is classified as high-risk.
+ * High-risk capabilities require the `trusted` tier to be granted.
+ */
+export function isHighRiskCapability(capability: PluginCapability): boolean {
+  return (HIGH_RISK_CAPABILITIES as ReadonlyArray<string>).includes(capability);
+}
+
+/**
+ * hasCapability — Returns whether a plugin has been granted a specific
+ * capability after manifest resolution.
+ */
+export function hasCapability(
+  manifest: PluginCapabilityManifest,
+  capability: PluginCapability,
+): boolean {
+  return manifest.granted.includes(capability);
+}
+
+/**
+ * validateManifestV2 — Light validation of the PluginManifestV2 shape.
+ * Returns null on success or an error string on failure.
+ */
+export function validateManifestV2(manifest: unknown): string | null {
+  if (!manifest || typeof manifest !== 'object') {
+    return 'manifest must be an object';
+  }
+  const m = manifest as Record<string, unknown>;
+  if (typeof m['name'] !== 'string' || !m['name']) {
+    return "manifest.name must be a non-empty string";
+  }
+  if (typeof m['version'] !== 'string' || !m['version']) {
+    return "manifest.version must be a non-empty string";
+  }
+  if (typeof m['description'] !== 'string') {
+    return "manifest.description must be a string";
+  }
+  if (m['capabilities'] !== undefined) {
+    if (!Array.isArray(m['capabilities'])) {
+      return "manifest.capabilities must be an array";
+    }
+    for (const cap of m['capabilities'] as unknown[]) {
+      if (typeof cap !== 'string') {
+        return `manifest.capabilities entries must be strings, got: ${typeof cap}`;
+      }
+    }
+  }
+  if (m['minRuntimeVersion'] !== undefined && typeof m['minRuntimeVersion'] !== 'string') {
+    return "manifest.minRuntimeVersion must be a string";
+  }
+  return null;
+}

package/src/runtime/plugins/quarantine.ts

@@ -0,0 +1,202 @@
+/**
+ * Plugin quarantine engine.
+ *
+ * Quarantine removes a plugin's unsafe contribution effects without fully
+ * unloading it. This allows the operator to isolate a suspicious plugin,
+ * inspect it, then either restore or permanently disable it.
+ *
+ * Quarantine effects:
+ *   - All high-risk capabilities are revoked in the resolved manifest.
+ *   - The plugin is moved to a `quarantined` lifecycle bucket in the store.
+ *   - A quarantine record is created with a timestamp and reason.
+ *
+ * Restore path:
+ *   - `lift()` — Restores previously revoked capabilities (if trust was upgraded).
+ *   - The caller is responsible for reloading the plugin after lifting.
+ */
+
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import type { PluginCapability, PluginCapabilityManifest } from './types.ts';
+import { isHighRiskCapability } from './manifest.ts';
+
+// ── Quarantine Record ─────────────────────────────────────────────────────────
+
+/**
+ * A record describing a plugin currently in quarantine.
+ */
+export interface QuarantineRecord {
+  /** Plugin name. */
+  readonly pluginName: string;
+  /** Unix epoch ms when quarantine was applied. */
+  readonly quarantinedAt: number;
+  /** Human-readable reason for quarantine. */
+  readonly reason: string;
+  /** The capabilities that were revoked when quarantine was applied. */
+  readonly revokedCapabilities: ReadonlyArray<PluginCapability>;
+  /** Whether the quarantine has been lifted. */
+  lifted: boolean;
+  /** Unix epoch ms when quarantine was lifted, if applicable. */
+  liftedAt?: number;
+}
+
+// ── Quarantine Engine ─────────────────────────────────────────────────────────
+
+/**
+ * PluginQuarantineEngine — Tracks quarantined plugins and applies/revokes
+ * capability restrictions.
+ *
+ * This is intentionally separate from the PluginLifecycleManager so that
+ * quarantine can be applied without triggering a full state machine transition.
+ * The lifecycle manager delegates to this engine when quarantine is requested.
+ */
+export class PluginQuarantineEngine {
+  private readonly records = new Map<string, QuarantineRecord>();
+
+  /**
+   * quarantine — Apply quarantine to a plugin.
+   *
+   * Revokes all high-risk capabilities from the plugin's resolved manifest
+   * and creates a quarantine record. The plugin remains in memory but its
+   * unsafe contributions are neutralised.
+   *
+   * @param pluginName       - Plugin identifier.
+   * @param capabilityManifest - The plugin's live capability manifest (mutated in place).
+   * @param reason           - Human-readable reason for quarantine.
+   * @returns The quarantine record, or null if already quarantined.
+   */
+  quarantine(
+    pluginName: string,
+    capabilityManifest: PluginCapabilityManifest,
+    reason: string,
+  ): QuarantineRecord | null {
+    if (this.isQuarantined(pluginName)) {
+      logger.warn(`[plugin-quarantine] ${pluginName}: already quarantined — skipping`);
+      return null;
+    }
+
+    // Identify which currently-granted capabilities are high-risk.
+    const revokedCapabilities: PluginCapability[] = capabilityManifest.granted.filter(
+      (cap) => isHighRiskCapability(cap),
+    );
+
+    // Strip high-risk capabilities from the live manifest.
+    capabilityManifest.granted = capabilityManifest.granted.filter(
+      (cap) => !isHighRiskCapability(cap),
+    );
+
+    // Record denied reason for each revoked cap. Collect first, then assign once.
+    const newDenied: PluginCapability[] = [];
+    for (const cap of revokedCapabilities) {
+      newDenied.push(cap);
+      capabilityManifest.denialReasons[cap] = `Capability '${cap}' revoked: plugin quarantined — ${reason}`;
+    }
+    capabilityManifest.denied = [...capabilityManifest.denied, ...newDenied];
+
+    const record: QuarantineRecord = {
+      pluginName,
+      quarantinedAt: Date.now(),
+      reason,
+      revokedCapabilities: Object.freeze(revokedCapabilities),
+      lifted: false,
+    };
+
+    this.records.set(pluginName, record);
+
+    logger.warn(
+      `[plugin-quarantine] ${pluginName}: quarantined — ${reason}` +
+      (revokedCapabilities.length > 0
+        ? ` (revoked: [${revokedCapabilities.join(', ')}])`
+        : ' (no high-risk capabilities were granted)'),
+    );
+
+    return record;
+  }
+
+  /**
+   * lift — Lift quarantine for a plugin.
+   *
+   * Previously revoked capabilities are NOT automatically restored here;
+   * the caller should trigger a re-resolve of the capability manifest
+   * (e.g. by reloading the plugin) after lifting so that trust-tier
+   * constraints are re-evaluated with the new tier.
+   *
+   * @returns true if quarantine was successfully lifted; false if not found.
+   */
+  lift(pluginName: string): boolean {
+    const record = this.records.get(pluginName);
+    if (!record) {
+      logger.debug(`[plugin-quarantine] ${pluginName}: no quarantine record found — nothing to lift`);
+      return false;
+    }
+    if (record.lifted) {
+      logger.debug(`[plugin-quarantine] ${pluginName}: quarantine already lifted`);
+      return false;
+    }
+
+    record.lifted = true;
+    record.liftedAt = Date.now();
+
+    logger.info(`[plugin-quarantine] ${pluginName}: quarantine lifted`);
+    return true;
+  }
+
+  /** Returns whether a plugin is currently quarantined (and not lifted). */
+  isQuarantined(pluginName: string): boolean {
+    const record = this.records.get(pluginName);
+    return record !== undefined && !record.lifted;
+  }
+
+  /** Returns the quarantine record for a plugin, or undefined. */
+  getRecord(pluginName: string): Readonly<QuarantineRecord> | undefined {
+    return this.records.get(pluginName);
+  }
+
+  /** Returns all quarantine records (including lifted ones). */
+  getAllRecords(): ReadonlyArray<Readonly<QuarantineRecord>> {
+    return Array.from(this.records.values());
+  }
+
+  /** Returns only active (not-lifted) quarantine records. */
+  getActiveQuarantines(): ReadonlyArray<Readonly<QuarantineRecord>> {
+    return Array.from(this.records.values()).filter((r) => !r.lifted);
+  }
+
+  /**
+   * applyToNewManifest — Apply quarantine constraints to a freshly-resolved
+   * capability manifest. Used when a plugin is reloaded while under quarantine.
+   *
+   * Unlike `quarantine()`, this does not create a new record — it reuses the
+   * existing one. Call this during manifest re-resolution if `isQuarantined()`
+   * is true.
+   */
+  applyToNewManifest(
+    pluginName: string,
+    capabilityManifest: PluginCapabilityManifest,
+  ): void {
+    if (!this.isQuarantined(pluginName)) return;
+
+    const toRevoke: PluginCapability[] = capabilityManifest.granted.filter(
+      (cap) => isHighRiskCapability(cap),
+    );
+
+    if (toRevoke.length === 0) return;
+
+    capabilityManifest.granted = capabilityManifest.granted.filter(
+      (cap) => !isHighRiskCapability(cap),
+    );
+
+    // Collect all denied caps first, then assign once to avoid quadratic churn.
+    const reason = this.records.get(pluginName)?.reason ?? 'quarantined';
+    const newDenied: PluginCapability[] = [];
+    for (const cap of toRevoke) {
+      newDenied.push(cap);
+      capabilityManifest.denialReasons[cap] = `Capability '${cap}' blocked: plugin is quarantined — ${reason}`;
+    }
+    capabilityManifest.denied = [...capabilityManifest.denied, ...newDenied];
+
+    logger.debug(
+      `[plugin-quarantine] ${pluginName}: quarantine re-applied to reloaded manifest` +
+      ` (blocked: [${toRevoke.join(', ')}])`,
+    );
+  }
+}

package/src/runtime/plugins/trust.ts

@@ -0,0 +1,291 @@
+/**
+ * Plugin extension trust framework.
+ *
+ * Defines trust tiers (untrusted, limited, trusted), signed manifest
+ * validation for the trusted tier, and the PluginTrustStore that manages
+ * trust records with persistence support.
+ *
+ * Trust tiers gate access to high-risk capabilities:
+ *   - untrusted — only safe, read-only capabilities allowed
+ *   - limited   — moderate capabilities; high-risk capabilities blocked
+ *   - trusted   — full capability set; requires signed manifest validation
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import type { PluginCapability } from './types.ts';
+import { isHighRiskCapability } from './manifest.ts';
+
+// ── Trust Tier ────────────────────────────────────────────────────────────────
+
+/**
+ * The three trust tiers available to a plugin.
+ *
+ * - `untrusted` — Default for newly discovered plugins. Only safe capabilities
+ *   are accessible. The plugin may not have been reviewed.
+ * - `limited`   — Operator-reviewed plugin. Moderate capabilities granted.
+ *   High-risk capabilities (shell.exec, filesystem.write, network.outbound)
+ *   remain blocked without explicit trust escalation.
+ * - `trusted`   — Fully trusted plugin. Requires a valid signed manifest.
+ *   All declared capabilities may be granted (subject to runtime policy).
+ */
+export type PluginTrustTier = 'untrusted' | 'limited' | 'trusted';
+
+// ── Trust Record ──────────────────────────────────────────────────────────────
+
+/**
+ * A persisted trust record for a single plugin.
+ */
+export interface PluginTrustRecord {
+  /** Plugin identifier (manifest name). */
+  readonly pluginName: string;
+  /** Current trust tier. */
+  tier: PluginTrustTier;
+  /** Unix epoch ms when the trust record was last updated. */
+  updatedAt: number;
+  /** Who or what granted this trust level. */
+  grantedBy: 'operator' | 'signed-manifest';
+  /**
+   * Fingerprint of the verified signature for trusted-tier plugins.
+   * Undefined for untrusted/limited plugins.
+   */
+  signatureFingerprint?: string;
+  /** Optional human-readable note attached by the operator. */
+  note?: string;
+}
+
+// ── Signature Validation ──────────────────────────────────────────────────────
+
+/**
+ * Result of validating a plugin's signed manifest.
+ */
+export interface SignatureValidationResult {
+  /** Whether the signature is valid. */
+  valid: boolean;
+  /** A stable fingerprint derived from the signature (e.g. hex digest prefix). */
+  fingerprint?: string;
+  /** Human-readable failure reason. Only set when `valid` is false. */
+  reason?: string;
+}
+
+/**
+ * validatePluginSignature — Validates the manifest signature for a plugin
+ * seeking the `trusted` tier.
+ *
+ * The signature field in PluginManifestV2 is expected to be a base64-encoded
+ * HMAC-SHA256 of the canonical manifest JSON (name + version + capabilities
+ * sorted and serialised). For production use, callers should supply a real
+ * key; this implementation uses a structural check so external tooling can
+ * provide real crypto without requiring Node.js crypto APIs at import time.
+ *
+ * @param manifest  - The raw manifest object containing the `signature` field.
+ * @param publicKey - Optional verification key. When omitted, structural
+ *                    validity only is checked (suitable for CI/test).
+ */
+export function validatePluginSignature(
+  manifest: { name: string; version: string; capabilities?: string[]; signature?: string },
+  publicKey?: string,
+): SignatureValidationResult {
+  const { name, version, capabilities = [], signature } = manifest;
+
+  if (!signature || typeof signature !== 'string' || signature.trim().length === 0) {
+    return { valid: false, reason: 'No signature field present in manifest' };
+  }
+
+  // Structural check: signature must be a non-empty hex or base64 string.
+  const isStructurallyValid = /^[A-Za-z0-9+/=]{32,}$/.test(signature.trim());
+  if (!isStructurallyValid) {
+    return { valid: false, reason: 'Signature field does not match expected format (base64/hex, min 32 chars)' };
+  }
+
+  // Canonical payload that should have been signed.
+  const sortedCapabilities = [...capabilities].sort();
+  const payload = JSON.stringify({ name, version, capabilities: sortedCapabilities });
+
+  // When a public key is provided, perform full HMAC verification.
+  if (publicKey) {
+    const expected = createHmac('sha256', publicKey)
+      .update(payload)
+      .digest('base64');
+    const sigBuf = Buffer.from(signature.trim(), 'base64');
+    const expBuf = Buffer.from(expected, 'base64');
+    if (sigBuf.length !== expBuf.length || !timingSafeEqual(sigBuf, expBuf)) {
+      return { valid: false, reason: 'HMAC mismatch' };
+    }
+  }
+
+  // Derive a short fingerprint for record keeping.
+  const fingerprint = signature.trim().slice(0, 16);
+
+  logger.debug(
+    `[plugin-trust] Manifest signature validated — plugin=${name} fingerprint=${fingerprint}` +
+    (publicKey ? ' (full HMAC)' : ' (structural only)'),
+  );
+
+  return { valid: true, fingerprint };
+}
+
+// ── Capability filtering by trust tier ───────────────────────────────────────
+
+/**
+ * Capabilities that are safe for any trust tier (including untrusted).
+ */
+export const SAFE_CAPABILITIES: ReadonlyArray<PluginCapability> = [
+  'register.tool',
+  'register.provider',
+  'register.panel',
+  'register.hook',
+  'filesystem.read',
+] as const;
+
+/**
+ * filterCapabilitiesByTrust — Returns the subset of `requested` capabilities
+ * that are permitted for the given trust tier.
+ *
+ * - `untrusted`: only SAFE_CAPABILITIES
+ * - `limited`:   all capabilities except HIGH_RISK_CAPABILITIES
+ * - `trusted`:   all capabilities (HIGH_RISK_CAPABILITIES included)
+ */
+export function filterCapabilitiesByTrust(
+  requested: ReadonlyArray<PluginCapability>,
+  tier: PluginTrustTier,
+): { permitted: PluginCapability[]; blocked: PluginCapability[]; reasons: Partial<Record<PluginCapability, string>> } {
+  const permitted: PluginCapability[] = [];
+  const blocked: PluginCapability[] = [];
+  const reasons: Partial<Record<PluginCapability, string>> = {};
+
+  for (const cap of requested) {
+    if (tier === 'trusted') {
+      permitted.push(cap);
+    } else if (tier === 'limited') {
+      if (isHighRiskCapability(cap)) {
+        blocked.push(cap);
+        reasons[cap] = `Capability '${cap}' requires trust tier 'trusted' (current: limited)`;
+      } else {
+        permitted.push(cap);
+      }
+    } else {
+      // untrusted
+      if ((SAFE_CAPABILITIES as ReadonlyArray<string>).includes(cap)) {
+        permitted.push(cap);
+      } else {
+        blocked.push(cap);
+        reasons[cap] = `Capability '${cap}' requires trust tier 'limited' or higher (current: untrusted)`;
+      }
+    }
+  }
+
+  return { permitted, blocked, reasons };
+}
+
+// ── Trust Store ───────────────────────────────────────────────────────────────
+
+/**
+ * PluginTrustStore — In-memory trust registry for all plugins.
+ *
+ * Callers are responsible for persistence (serialise/deserialise via
+ * `exportRecords` / `importRecords`). The PluginManager bridges this to
+ * the plugins.json state file.
+ */
+export class PluginTrustStore {
+  private readonly records = new Map<string, PluginTrustRecord>();
+
+  /**
+   * Returns the trust record for a plugin, or `undefined` if not yet assessed.
+   * Callers should treat `undefined` as implicitly `untrusted`.
+   */
+  getRecord(pluginName: string): Readonly<PluginTrustRecord> | undefined {
+    return this.records.get(pluginName);
+  }
+
+  /**
+   * Returns the trust tier for a plugin.
+   * Plugins without an explicit record are treated as `untrusted`.
+   */
+  getTier(pluginName: string): PluginTrustTier {
+    return this.records.get(pluginName)?.tier ?? 'untrusted';
+  }
+
+  /**
+   * setTier — Explicitly assign a trust tier to a plugin.
+   *
+   * Intended for operator use via `/plugin trust`.
+   * For the `trusted` tier, prefer `trustSigned()` which also validates the signature.
+   */
+  setTier(
+    pluginName: string,
+    tier: PluginTrustTier,
+    options: { note?: string } = {},
+  ): PluginTrustRecord {
+    const record: PluginTrustRecord = {
+      pluginName,
+      tier,
+      updatedAt: Date.now(),
+      grantedBy: 'operator',
+      note: options.note,
+    };
+    this.records.set(pluginName, record);
+    logger.info(`[plugin-trust] ${pluginName}: tier set to '${tier}'${options.note ? ` — ${options.note}` : ''}`);
+    return record;
+  }
+
+  /**
+   * trustSigned — Elevate a plugin to the `trusted` tier after verifying its
+   * signed manifest. Returns `{ ok: false, reason }` if validation fails.
+   */
+  trustSigned(
+    pluginName: string,
+    manifest: { name: string; version: string; capabilities?: string[]; signature?: string },
+    publicKey?: string,
+  ): { ok: true; record: PluginTrustRecord } | { ok: false; reason: string } {
+    const validation = validatePluginSignature(manifest, publicKey);
+    if (!validation.valid) {
+      logger.warn(`[plugin-trust] ${pluginName}: signature validation failed — ${validation.reason}`);
+      return { ok: false, reason: validation.reason! };
+    }
+
+    const record: PluginTrustRecord = {
+      pluginName,
+      tier: 'trusted',
+      updatedAt: Date.now(),
+      grantedBy: 'signed-manifest',
+      signatureFingerprint: validation.fingerprint,
+    };
+    this.records.set(pluginName, record);
+    logger.info(`[plugin-trust] ${pluginName}: elevated to 'trusted' via signed manifest (fingerprint=${validation.fingerprint})`);
+    return { ok: true, record };
+  }
+
+  /**
+   * verify — Verify the current signature on a plugin manifest without
+   * changing its tier. Useful for `/plugin verify` inspection.
+   */
+  verify(
+    manifest: { name: string; version: string; capabilities?: string[]; signature?: string },
+    publicKey?: string,
+  ): SignatureValidationResult {
+    return validatePluginSignature(manifest, publicKey);
+  }
+
+  /** Returns all trust records as an array. */
+  getAllRecords(): ReadonlyArray<Readonly<PluginTrustRecord>> {
+    return Array.from(this.records.values());
+  }
+
+  /** Export all records for persistence. */
+  exportRecords(): Record<string, PluginTrustRecord> {
+    const out: Record<string, PluginTrustRecord> = {};
+    for (const [name, record] of this.records) {
+      out[name] = { ...record };
+    }
+    return out;
+  }
+
+  /** Import records from persisted state. Merges into existing records. */
+  importRecords(records: Record<string, PluginTrustRecord>): void {
+    for (const [name, record] of Object.entries(records)) {
+      this.records.set(name, record);
+    }
+    logger.debug(`[plugin-trust] Imported ${Object.keys(records).length} trust record(s)`);
+  }
+}