openclaw/src/plugins/config-contracts.test.ts

// Covers plugin config contract validation and ownership boundaries.
import { beforeEach, describe, expect, it, vi } from "vitest";
import type { PluginManifestRegistry } from "./manifest-registry.js";

const mocks = vi.hoisted(() => {
  const loadManifestRegistry = vi.fn();
  return {
    discoverOpenClawPlugins: vi.fn(() => ({ candidates: [], diagnostics: [] })),
    findBundledPluginMetadataById: vi.fn(),
    loadBundledManifestRegistry: vi.fn(),
    loadPluginManifestRegistryForInstalledIndex: loadManifestRegistry,
    loadPluginManifestRegistryForPluginRegistry: loadManifestRegistry,
    loadPluginRegistrySnapshot: vi.fn(() => ({ plugins: [] })),
  };
});

vi.mock("./discovery.js", () => ({
  discoverOpenClawPlugins: mocks.discoverOpenClawPlugins,
}));

vi.mock("./bundled-plugin-metadata.js", () => ({
  findBundledPluginMetadataById: mocks.findBundledPluginMetadataById,
}));

vi.mock("./manifest-registry.js", () => ({
  loadPluginManifestRegistryCore: mocks.loadBundledManifestRegistry,
}));

vi.mock("./manifest-registry-installed.js", () => ({
  loadPluginManifestRegistryForInstalledIndex: mocks.loadPluginManifestRegistryForInstalledIndex,
}));

vi.mock("./plugin-registry.js", () => ({
  loadPluginManifestRegistryForPluginRegistry: mocks.loadPluginManifestRegistryForPluginRegistry,
  loadPluginRegistrySnapshot: mocks.loadPluginRegistrySnapshot,
}));

import {
  collectPluginConfigContractMatches,
  resolvePluginConfigContractsById,
} from "./config-contracts.js";

type PluginManifestRecord = PluginManifestRegistry["plugins"][number];

function createRegistry(plugins: PluginManifestRegistry["plugins"]): PluginManifestRegistry {
  return {
    plugins,
    diagnostics: [],
  };
}

function createPluginRecord(
  overrides: Pick<PluginManifestRecord, "id" | "origin"> & Partial<PluginManifestRecord>,
): PluginManifestRecord {
  return {
    rootDir: `/tmp/${overrides.id}`,
    manifestPath: `/tmp/${overrides.id}/openclaw.plugin.json`,
    channelConfigs: undefined,
    configUiHints: undefined,
    configSchema: undefined,
    configContracts: undefined,
    contracts: undefined,
    name: undefined,
    description: undefined,
    version: undefined,
    enabledByDefault: undefined,
    autoEnableWhenConfiguredProviders: undefined,
    legacyPluginIds: undefined,
    format: undefined,
    bundleFormat: undefined,
    bundleCapabilities: undefined,
    kind: undefined,
    channels: [],
    providers: [],
    modelSupport: undefined,
    cliBackends: [],
    providerAuthAliases: undefined,
    providerAuthChoices: undefined,
    skills: [],
    settingsFiles: undefined,
    hooks: [],
    source: `/tmp/${overrides.id}/openclaw.plugin.json`,
    setupSource: undefined,
    channelCatalogMeta: undefined,
    ...overrides,
  };
}

describe("resolvePluginConfigContractsById", () => {
  beforeEach(() => {
    mocks.discoverOpenClawPlugins.mockReset();
    mocks.discoverOpenClawPlugins.mockReturnValue({ candidates: [], diagnostics: [] });
    mocks.findBundledPluginMetadataById.mockReset();
    mocks.loadBundledManifestRegistry.mockReset();
    mocks.loadBundledManifestRegistry.mockReturnValue(createRegistry([]));
    mocks.loadPluginManifestRegistryForInstalledIndex.mockReset();
    mocks.loadPluginManifestRegistryForInstalledIndex.mockReturnValue(createRegistry([]));
    mocks.loadPluginRegistrySnapshot.mockReset();
    mocks.loadPluginRegistrySnapshot.mockReturnValue({ plugins: [] });
  });

  it("uses a supplied manifest registry as the authoritative contract source", () => {
    const manifestRegistry = createRegistry([
      createPluginRecord({
        id: "prepared-plugin",
        origin: "config",
        configContracts: {
          secretInputs: {
            paths: [{ path: "credentials.token", expected: "string" }],
          },
        },
      }),
    ]);

    expect(
      resolvePluginConfigContractsById({
        pluginIds: ["prepared-plugin"],
        manifestRegistry,
        fallbackToBundledMetadata: true,
        fallbackToBundledMetadataForResolvedBundled: true,
        fallbackBundledPluginIds: ["prepared-plugin"],
      }),
    ).toEqual(
      new Map([
        [
          "prepared-plugin",
          {
            origin: "config",
            configContracts: {
              secretInputs: {
                paths: [{ path: "credentials.token", expected: "string" }],
              },
            },
          },
        ],
      ]),
    );
    expect(mocks.loadPluginManifestRegistryForPluginRegistry).not.toHaveBeenCalled();
    expect(mocks.discoverOpenClawPlugins).not.toHaveBeenCalled();
    expect(mocks.loadBundledManifestRegistry).not.toHaveBeenCalled();
    expect(mocks.findBundledPluginMetadataById).not.toHaveBeenCalled();
  });

  it("does not fall back to bundled registry when registry already resolved a plugin without config contracts", () => {
    mocks.loadPluginManifestRegistryForInstalledIndex.mockReturnValue(
      createRegistry([
        createPluginRecord({
          id: "brave",
          origin: "bundled",
        }),
      ]),
    );

    expect(
      resolvePluginConfigContractsById({
        pluginIds: ["brave"],
      }),
    ).toEqual(new Map());
    expect(mocks.loadBundledManifestRegistry).not.toHaveBeenCalled();
  });

  it("hydrates supplied bundled registry records from explicit bundled discovery", () => {
    mocks.loadBundledManifestRegistry.mockReturnValue(
      createRegistry([
        createPluginRecord({
          id: "prepared-plugin",
          origin: "bundled",
          configContracts: {
            secretInputs: {
              paths: [{ path: "credentials.token", expected: "string" }],
            },
          },
        }),
      ]),
    );

    expect(
      resolvePluginConfigContractsById({
        pluginIds: ["prepared-plugin"],
        manifestRegistry: createRegistry([
          createPluginRecord({ id: "prepared-plugin", origin: "bundled" }),
        ]),
        fallbackToBundledMetadata: true,
        fallbackToBundledMetadataForResolvedBundled: true,
        fallbackBundledPluginIds: ["prepared-plugin"],
      }),
    ).toEqual(
      new Map([
        [
          "prepared-plugin",
          {
            origin: "bundled",
            configContracts: {
              secretInputs: {
                paths: [{ path: "credentials.token", expected: "string" }],
              },
            },
          },
        ],
      ]),
    );
  });

  it("can hydrate missing contracts from bundled registry for resolved bundled plugins", () => {
    mocks.loadPluginManifestRegistryForInstalledIndex.mockReturnValue(
      createRegistry([
        createPluginRecord({
          id: "voice-call",
          origin: "bundled",
          configContracts: {
            compatibilityMigrationPaths: ["plugins.entries.voice-call.config"],
          },
        }),
      ]),
    );
    mocks.loadBundledManifestRegistry.mockReturnValue(
      createRegistry([
        createPluginRecord({
          id: "voice-call",
          origin: "bundled",
          configContracts: {
            secretInputs: {
              paths: [{ path: "twilio.authToken", expected: "string" }],
            },
          },
        }),
      ]),
    );

    expect(
      resolvePluginConfigContractsById({
        pluginIds: ["voice-call"],
        fallbackToBundledMetadataForResolvedBundled: true,
      }),
    ).toEqual(
      new Map([
        [
          "voice-call",
          {
            origin: "bundled",
            configContracts: {
              compatibilityMigrationPaths: ["plugins.entries.voice-call.config"],
              secretInputs: {
                paths: [{ path: "twilio.authToken", expected: "string" }],
              },
            },
          },
        ],
      ]),
    );
    expect(mocks.loadPluginManifestRegistryForPluginRegistry).toHaveBeenCalledTimes(1);
    expect(mocks.loadBundledManifestRegistry).toHaveBeenCalledTimes(1);
  });

  it("refreshes stale bundled SecretInput contracts from bundled registry", () => {
    mocks.loadPluginManifestRegistryForInstalledIndex.mockReturnValue(
      createRegistry([
        createPluginRecord({
          id: "voice-call",
          origin: "bundled",
          configContracts: {
            compatibilityMigrationPaths: ["plugins.entries.voice-call.config"],
            secretInputs: {
              paths: [{ path: "twilio.authToken", expected: "string" }],
            },
          },
        }),
      ]),
    );
    mocks.loadBundledManifestRegistry.mockReturnValue(
      createRegistry([
        createPluginRecord({
          id: "voice-call",
          origin: "bundled",
          configContracts: {
            secretInputs: {
              paths: [
                { path: "twilio.authToken", expected: "string" },
                { path: "realtime.providers.*.apiKey", expected: "string" },
              ],
            },
          },
        }),
      ]),
    );

    expect(
      resolvePluginConfigContractsById({
        pluginIds: ["voice-call"],
        fallbackToBundledMetadataForResolvedBundled: true,
      }),
    ).toEqual(
      new Map([
        [
          "voice-call",
          {
            origin: "bundled",
            configContracts: {
              compatibilityMigrationPaths: ["plugins.entries.voice-call.config"],
              secretInputs: {
                paths: [
                  { path: "twilio.authToken", expected: "string" },
                  { path: "realtime.providers.*.apiKey", expected: "string" },
                ],
              },
            },
          },
        ],
      ]),
    );
  });

  it("can hydrate missing contracts for plugin ids known to be bundled by runtime discovery", () => {
    mocks.loadPluginManifestRegistryForInstalledIndex.mockReturnValue(
      createRegistry([
        createPluginRecord({
          id: "voice-call",
          origin: "config",
        }),
      ]),
    );
    mocks.loadBundledManifestRegistry.mockReturnValue(
      createRegistry([
        createPluginRecord({
          id: "voice-call",
          origin: "bundled",
          configContracts: {
            secretInputs: {
              paths: [{ path: "tts.providers.*.apiKey", expected: "string" }],
            },
          },
        }),
      ]),
    );

    expect(
      resolvePluginConfigContractsById({
        pluginIds: ["voice-call"],
        fallbackBundledPluginIds: ["voice-call"],
      }),
    ).toEqual(
      new Map([
        [
          "voice-call",
          {
            origin: "bundled",
            configContracts: {
              secretInputs: {
                paths: [{ path: "tts.providers.*.apiKey", expected: "string" }],
              },
            },
          },
        ],
      ]),
    );
  });

  it("can skip bundled metadata fallback for registry-scoped callers", () => {
    expect(
      resolvePluginConfigContractsById({
        pluginIds: ["missing"],
        fallbackToBundledMetadata: false,
      }),
    ).toEqual(new Map());
    expect(mocks.loadBundledManifestRegistry).not.toHaveBeenCalled();
  });
});

describe("collectPluginConfigContractMatches", () => {
  it("only accepts canonical array index path segments", () => {
    const root = { items: ["first", "second"] };

    expect(
      collectPluginConfigContractMatches({
        root,
        pathPattern: "items.1",
      }),
    ).toEqual([{ path: "items[1]", value: "second" }]);
    expect(
      collectPluginConfigContractMatches({
        root,
        pathPattern: "items.1.5",
      }),
    ).toEqual([]);
    expect(
      collectPluginConfigContractMatches({
        root,
        pathPattern: "items.01",
      }),
    ).toEqual([]);
  });

  it("rejects array indexes outside canonical config path bounds", () => {
    const items = Array<string>(100_002);
    items[100_001] = "too far";

    expect(
      collectPluginConfigContractMatches({
        root: { items },
        pathPattern: "items.100001",
      }),
    ).toEqual([]);
  });
});