@xopcai/xopc 0.0.320 → 0.0.323

package/dist/src/extensions/agent-plugins/auth.js

@@ -0,0 +1,156 @@
+import { init_paths_state, resolveStateDir } from "../../config/paths-state.js";
+import { init_write_file_atomic, writeTextAtomic } from "../../infra/write-file-atomic.js";
+import { CredentialResolver, init_credentials } from "../../auth/credentials.js";
+import { pluginName, pluginServerId } from "./validation.js";
+import { clearPluginMcpHealth } from "./health.js";
+import { isDangerousHostEnvVarName } from "../../infra/host-env-security.js";
+import { McpOAuthStore } from "../../agent/mcp/oauth/mcp-oauth-store.js";
+import { join } from "node:path";
+import { existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { validateHeaderName } from "node:http";
+//#region src/extensions/agent-plugins/auth.ts
+init_credentials();
+init_write_file_atomic();
+init_paths_state();
+const bindingSchema = z.strictObject({
+	serverName: z.string(),
+	mode: z.enum([
+		"auto",
+		"oauth",
+		"api-key",
+		"none"
+	]),
+	identityScope: z.literal("owner"),
+	endpointFingerprint: z.string(),
+	fields: z.array(z.strictObject({
+		target: z.enum(["headers", "env"]),
+		key: z.string(),
+		provider: z.string(),
+		prefix: z.string()
+	}))
+});
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+const providerPrefix = (id) => `plugin-${hash(id).slice(0, 16)}-`;
+function pluginEndpointFingerprint(server) {
+	return hash(server.type === "stdio" ? JSON.stringify(server) : new URL(server.url).toString());
+}
+function bindingPath(store, id, name) {
+	return join(store.stateDir, "plugin-auth", pluginName.parse(id), `${hash(name)}.json`);
+}
+function readPluginAuthBinding(store, id, name, server) {
+	const path = bindingPath(store, id, name);
+	if (!existsSync(path)) return void 0;
+	const binding = bindingSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+	return binding.endpointFingerprint === pluginEndpointFingerprint(server) ? binding : void 0;
+}
+async function savePluginAuthBinding(store, id, name, input) {
+	const plugin = store.get(id);
+	const server = plugin?.servers[name];
+	if (!server || plugin?.readiness === "blocked") throw new Error("Plugin MCP server unavailable");
+	if (input.mode === "oauth" && server.type !== "streamable-http") throw new Error("OAuth requires streamable HTTP");
+	const endpointFingerprint = pluginEndpointFingerprint(server);
+	const fields = [];
+	const resolver = new CredentialResolver(store.stateDir === resolveStateDir() ? {} : { stateDir: store.stateDir });
+	if (input.mode !== "api-key" && input.secrets?.length) throw new Error("Secrets require api-key mode");
+	const seen = /* @__PURE__ */ new Set();
+	for (const field of input.secrets ?? []) {
+		if (!field.value || field.value.length > 16384 || /[\r\n\0]/.test(field.value) || /[\r\n\0]/.test(field.prefix ?? "")) throw new Error("Invalid secret value");
+		if (field.target === "headers") {
+			validateHeaderName(field.key);
+			if (server.type === "stdio") throw new Error("stdio credentials must use env");
+			if ([
+				"host",
+				"content-length",
+				"connection",
+				"transfer-encoding",
+				"cookie"
+			].includes(field.key.toLowerCase())) throw new Error("Unsupported credential header");
+		} else if (server.type !== "stdio" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(field.key) || /^(PLUGIN_ROOT|PLUGIN_DATA|PATH)$/i.test(field.key) || isDangerousHostEnvVarName(field.key)) throw new Error("Unsupported credential environment variable");
+		const normalizedKey = field.target === "headers" || process.platform === "win32" ? field.key.toLowerCase() : field.key;
+		if (seen.has(normalizedKey)) throw new Error("Duplicate credential field");
+		seen.add(normalizedKey);
+		const provider = `${providerPrefix(id)}${hash(JSON.stringify([
+			"owner",
+			id,
+			name,
+			endpointFingerprint,
+			field.target,
+			normalizedKey
+		]))}`;
+		fields.push({
+			target: field.target,
+			key: field.key,
+			provider,
+			prefix: field.prefix ?? ""
+		});
+	}
+	for (let i = 0; i < fields.length; i++) await resolver.saveApiKey(fields[i].provider, input.secrets[i].value);
+	const binding = bindingSchema.parse({
+		serverName: name,
+		mode: input.mode,
+		identityScope: "owner",
+		endpointFingerprint,
+		fields
+	});
+	await writeTextAtomic(bindingPath(store, id, name), JSON.stringify(binding));
+	clearPluginMcpHealth(id, name, store.stateDir);
+}
+function applyPluginAuthBinding(raw, binding) {
+	if (!binding) return raw;
+	const result = { ...raw };
+	if (binding.mode === "none" || binding.mode === "api-key") {
+		delete result.auth;
+		delete result.xopcAutoAuth;
+	}
+	if (binding.mode === "oauth") {
+		result.auth = { type: "oauth" };
+		delete result.xopcAutoAuth;
+		result.headers = Object.fromEntries(Object.entries(result.headers ?? {}).filter(([key]) => key.toLowerCase() !== "authorization"));
+	}
+	for (const field of binding.fields) {
+		const values = { ...result[field.target] };
+		const insensitive = field.target === "headers" || process.platform === "win32";
+		for (const key of Object.keys(values)) if (insensitive ? key.toLowerCase() === field.key.toLowerCase() : key === field.key) delete values[key];
+		values[field.key] = { xopcSecretRef: {
+			provider: field.provider,
+			fieldKey: field.key,
+			prefix: field.prefix
+		} };
+		result[field.target] = values;
+	}
+	result.xopcAuthRevision = hash(JSON.stringify(binding));
+	return result;
+}
+function pluginOAuthScope(raw) {
+	const plugin = raw?.xopcPlugin;
+	return plugin ? `owner:${pluginServerId(plugin.id, plugin.serverName)}` : void 0;
+}
+async function removePluginCredentials(store, id) {
+	pluginName.parse(id);
+	const plugin = store.get(id);
+	const serverNames = new Set(Object.keys(plugin?.servers ?? {}));
+	const dir = join(store.stateDir, "plugin-auth", id);
+	if (existsSync(dir)) for (const file of readdirSync(dir)) {
+		if (!/^[a-f0-9]{64}\.json$/.test(file)) throw new Error("Unexpected plugin auth store entry");
+		const binding = bindingSchema.parse(JSON.parse(readFileSync(join(dir, file), "utf8")));
+		serverNames.add(binding.serverName);
+	}
+	const { getMcpOAuthManager } = await import("../../agent/mcp/oauth/mcp-oauth-manager.js");
+	for (const name of serverNames) {
+		await getMcpOAuthManager({ xopcPlugin: {
+			id,
+			serverName: name
+		} }).cancelPending();
+		await new McpOAuthStore(`owner:${pluginServerId(id, name)}`).deleteScope();
+	}
+	const resolver = new CredentialResolver(store.stateDir === resolveStateDir() ? {} : { stateDir: store.stateDir });
+	for (const profile of await resolver.listProfiles()) if (profile.provider.startsWith(providerPrefix(id))) await resolver.deleteProviderCredential(profile.provider);
+	if (existsSync(dir)) rmSync(dir, {
+		recursive: true,
+		force: true
+	});
+}
+//#endregion
+export { applyPluginAuthBinding, pluginEndpointFingerprint, pluginOAuthScope, readPluginAuthBinding, removePluginCredentials, savePluginAuthBinding };

package/dist/src/extensions/agent-plugins/connection.d.ts

@@ -0,0 +1,8 @@
+import type { ConnectionNeed } from '@xopcai/gateway-contract';
+import { AgentPluginStore } from './store.js';
+export declare function pluginMcpCandidateRef(pluginId: string, serverName: string): string;
+export declare function parsePluginMcpCandidateRef(ref: string): {
+    pluginId: string;
+    serverName: string;
+} | undefined;
+export declare function resolvePluginMcpConnectionCandidate(ref: string, store?: AgentPluginStore): ConnectionNeed | undefined;

package/dist/src/extensions/agent-plugins/connection.js

@@ -0,0 +1,41 @@
+import { pluginServerId } from "./validation.js";
+import { AgentPluginStore } from "./store.js";
+//#region src/extensions/agent-plugins/connection.ts
+const PREFIX = "plugin-mcp:";
+function pluginMcpCandidateRef(pluginId, serverName) {
+	return `${PREFIX}${encodeURIComponent(pluginId)}:${encodeURIComponent(serverName)}`;
+}
+function parsePluginMcpCandidateRef(ref) {
+	if (!ref.startsWith(PREFIX)) return void 0;
+	const parts = ref.slice(11).split(":");
+	if (parts.length !== 2) return void 0;
+	try {
+		return {
+			pluginId: decodeURIComponent(parts[0]),
+			serverName: decodeURIComponent(parts[1])
+		};
+	} catch {
+		return;
+	}
+}
+function resolvePluginMcpConnectionCandidate(ref, store = new AgentPluginStore()) {
+	const parsed = parsePluginMcpCandidateRef(ref);
+	if (!parsed) return void 0;
+	const plugin = store.get(parsed.pluginId);
+	const server = plugin?.servers[parsed.serverName];
+	if (!plugin || !server || !plugin.receipt.enabled || plugin.readiness === "blocked" || server.type !== "streamable-http") return;
+	const serverId = pluginServerId(plugin.id, parsed.serverName);
+	return {
+		key: serverId,
+		target: {
+			type: "plugin-mcp",
+			pluginId: plugin.id,
+			serverId,
+			serverName: parsed.serverName
+		},
+		label: plugin.manifest.name,
+		capabilities: [`mcp.tools:${serverId}`]
+	};
+}
+//#endregion
+export { parsePluginMcpCandidateRef, pluginMcpCandidateRef, resolvePluginMcpConnectionCandidate };

package/dist/src/extensions/agent-plugins/health.d.ts

@@ -0,0 +1,4 @@
+export type PluginMcpHealth = 'ready' | 'authorization_required' | 'error' | 'not_tested';
+export declare function readPluginMcpHealth(id: string, name: string, revision: string, stateDir?: string): PluginMcpHealth;
+export declare function clearPluginMcpHealth(id: string, name: string, stateDir?: string): void;
+export declare function recordPluginMcpHealth(raw: unknown, status: Exclude<PluginMcpHealth, 'not_tested'>): void;

package/dist/src/extensions/agent-plugins/health.js

@@ -0,0 +1,48 @@
+import { init_paths_state, resolveStateDir } from "../../config/paths-state.js";
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { init_write_file_atomic, writeTextAtomicSync } from "../../infra/write-file-atomic.js";
+import { pluginName } from "./validation.js";
+import { join } from "node:path";
+import { readFileSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+//#region src/extensions/agent-plugins/health.ts
+init_paths_state();
+init_write_file_atomic();
+init_logger();
+const log = createLogger("PluginMcpHealth");
+function pathFor(id, name, stateDir) {
+	return join(stateDir, "plugin-health", pluginName.parse(id), `${createHash("sha256").update(name).digest("hex")}.json`);
+}
+function readPluginMcpHealth(id, name, revision, stateDir = resolveStateDir()) {
+	try {
+		const value = JSON.parse(readFileSync(pathFor(id, name, stateDir), "utf8"));
+		return value.revision === revision && [
+			"ready",
+			"authorization_required",
+			"error"
+		].includes(value.status) ? value.status : "not_tested";
+	} catch {
+		return "not_tested";
+	}
+}
+function clearPluginMcpHealth(id, name, stateDir = resolveStateDir()) {
+	rmSync(pathFor(id, name, stateDir), { force: true });
+}
+function recordPluginMcpHealth(raw, status) {
+	const plugin = raw?.xopcPlugin;
+	if (!plugin) return;
+	try {
+		writeTextAtomicSync(pathFor(plugin.id, plugin.serverName, resolveStateDir()), JSON.stringify({
+			revision: plugin.revision,
+			status
+		}));
+	} catch (error) {
+		log.warn({
+			err: error,
+			pluginId: plugin.id
+		}, "Could not persist MCP connection status");
+	}
+}
+//#endregion
+export { clearPluginMcpHealth, readPluginMcpHealth, recordPluginMcpHealth };

package/dist/src/extensions/agent-plugins/inventory.d.ts

@@ -0,0 +1,53 @@
+import { type InstalledAgentPlugin } from './store.js';
+export declare function agentPluginInventoryRow(plugin: InstalledAgentPlugin): {
+    id: string;
+    pluginId: string;
+    format: "agent-plugin";
+    name: string;
+    version: string;
+    description: string;
+    source: string;
+    active: boolean;
+    activationEligible: boolean;
+    readiness: "ready" | "blocked" | "degraded" | "setup_required";
+    hasUi: boolean;
+    hasConfigSchema: boolean;
+    canRollback: boolean;
+    components: {
+        skills: {
+            name: string;
+        }[];
+        mcp: {
+            name: string;
+            id: string;
+            type: "sse" | "streamable-http" | "stdio";
+        }[];
+    };
+    diagnostics: import("./validation.js").PluginDiagnostic[];
+};
+export declare function listAgentPluginInventory(): {
+    id: string;
+    pluginId: string;
+    format: "agent-plugin";
+    name: string;
+    version: string;
+    description: string;
+    source: string;
+    active: boolean;
+    activationEligible: boolean;
+    readiness: "ready" | "blocked" | "degraded" | "setup_required";
+    hasUi: boolean;
+    hasConfigSchema: boolean;
+    canRollback: boolean;
+    components: {
+        skills: {
+            name: string;
+        }[];
+        mcp: {
+            name: string;
+            id: string;
+            type: "sse" | "streamable-http" | "stdio";
+        }[];
+    };
+    diagnostics: import("./validation.js").PluginDiagnostic[];
+}[];

package/dist/src/extensions/agent-plugins/inventory.js

@@ -0,0 +1,34 @@
+import { pluginServerId } from "./validation.js";
+import { AgentPluginStore } from "./store.js";
+//#region src/extensions/agent-plugins/inventory.ts
+function agentPluginInventoryRow(plugin) {
+	return {
+		id: `plugin:${plugin.id}`,
+		pluginId: plugin.id,
+		format: plugin.format,
+		name: plugin.manifest.name,
+		version: plugin.manifest.version,
+		description: plugin.manifest.description,
+		source: "agent-plugin",
+		active: plugin.receipt.enabled && plugin.readiness !== "blocked",
+		activationEligible: plugin.receipt.enabled,
+		readiness: plugin.readiness,
+		hasUi: false,
+		hasConfigSchema: false,
+		canRollback: !!plugin.receipt.previous,
+		components: {
+			skills: plugin.skills.map((skill) => ({ name: skill.name })),
+			mcp: Object.entries(plugin.servers).map(([name, server]) => ({
+				name,
+				id: pluginServerId(plugin.id, name),
+				type: server.type
+			}))
+		},
+		diagnostics: plugin.diagnostics
+	};
+}
+function listAgentPluginInventory() {
+	return new AgentPluginStore().list().map(agentPluginInventoryRow);
+}
+//#endregion
+export { agentPluginInventoryRow, listAgentPluginInventory };

package/dist/src/extensions/agent-plugins/mcp-adapter.d.ts

@@ -0,0 +1,3 @@
+import { AgentPluginStore, type InstalledAgentPlugin } from './store.js';
+import { type PluginDiagnostic } from './validation.js';
+export declare function materializePluginServers(plugin: InstalledAgentPlugin, store?: AgentPluginStore, diagnostics?: PluginDiagnostic[]): Record<string, Record<string, unknown>>;

package/dist/src/extensions/agent-plugins/mcp-adapter.js

@@ -0,0 +1,47 @@
+import { containedPath, expandPluginVariables, pluginServerId, resolvePluginCwd } from "./validation.js";
+import { AgentPluginStore } from "./store.js";
+import { applyPluginAuthBinding, readPluginAuthBinding } from "./auth.js";
+import { resolve } from "node:path";
+//#region src/extensions/agent-plugins/mcp-adapter.ts
+function materializePluginServers(plugin, store = new AgentPluginStore(), diagnostics = []) {
+	const root = plugin.rootDir;
+	const data = store.dataDir(plugin.id);
+	const servers = Object.create(null);
+	for (const [name, server] of Object.entries(plugin.servers)) try {
+		const origin = {
+			id: plugin.id,
+			serverName: name,
+			rootDir: root,
+			dataDir: data,
+			revision: plugin.receipt.revision
+		};
+		const raw = server.type !== "stdio" ? {
+			...server,
+			xopcPlugin: origin,
+			...server.type === "streamable-http" && !Object.keys(server.headers ?? {}).some((key) => key.toLowerCase() === "authorization") ? {
+				auth: { type: "oauth" },
+				xopcAutoAuth: true
+			} : {}
+		} : {
+			type: "stdio",
+			xopcPlugin: origin,
+			command: server.command.startsWith("./") ? containedPath(root, resolve(root, server.command)) : server.command,
+			args: server.args?.map((value) => expandPluginVariables(value, root, data)),
+			env: {
+				...Object.fromEntries(Object.entries(server.env ?? {}).map(([key, value]) => [key, expandPluginVariables(value, root, data)])),
+				PLUGIN_ROOT: root,
+				PLUGIN_DATA: data
+			},
+			cwd: resolvePluginCwd(server.cwd, root, data)
+		};
+		servers[pluginServerId(plugin.id, name)] = applyPluginAuthBinding(raw, readPluginAuthBinding(store, plugin.id, name, server));
+	} catch (error) {
+		diagnostics.push({
+			component: `mcp:${name}`,
+			message: error instanceof Error ? error.message : String(error)
+		});
+	}
+	return servers;
+}
+//#endregion
+export { materializePluginServers };

package/dist/src/extensions/agent-plugins/sources.d.ts

@@ -0,0 +1,5 @@
+import type { Config } from '../../config/schema.js';
+export declare function isAgentPluginArchive(buffer: Buffer): boolean;
+export declare function withAgentPluginArchive<T>(buffer: Buffer, fn: (local: string) => T): T;
+/** Resolve remote artifacts only for explicit inspect/install requests, never during discovery. */
+export declare function withAgentPluginSource<T>(source: string, config: Config | undefined, fn: (local: string) => T): Promise<T>;

package/dist/src/extensions/agent-plugins/sources.js

@@ -0,0 +1,72 @@
+import { createPluginHttpFetch } from "../../agent/mcp/plugin-http-fetch.js";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import AdmZip from "adm-zip";
+//#region src/extensions/agent-plugins/sources.ts
+function isAgentPluginArchive(buffer) {
+	const entries = new AdmZip(buffer).getEntries();
+	const paths = entries.map((entry) => entry.entryName.replace(/\/$/, ""));
+	const nativeMetadata = (path) => {
+		const entry = entries.find((item) => item.entryName === path);
+		if (!entry) return false;
+		if (entry.header.size > 1024 * 1024) throw new Error("Package metadata exceeds 1 MiB");
+		return Boolean(JSON.parse(entry.getData().toString("utf8"))?.xopc?.extension);
+	};
+	if (paths.includes("xopc.extension.json")) return false;
+	if (paths.includes("plugin.json")) return !nativeMetadata("package.json");
+	const first = new Set(paths.map((path) => path.split("/")[0]));
+	if (first.size !== 1) return false;
+	const root = [...first][0];
+	return paths.includes(`${root}/plugin.json`) && !paths.includes(`${root}/xopc.extension.json`) && !nativeMetadata(`${root}/package.json`);
+}
+function withAgentPluginArchive(buffer, fn) {
+	const dir = mkdtempSync(join(tmpdir(), "xopc-plugin-download-"));
+	try {
+		const file = join(dir, "plugin.zip");
+		writeFileSync(file, buffer);
+		return fn(file);
+	} finally {
+		rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** Resolve remote artifacts only for explicit inspect/install requests, never during discovery. */
+async function withAgentPluginSource(source, config, fn) {
+	if (!source.startsWith("https://") && !source.startsWith("store:")) return fn(source);
+	let buffer;
+	if (source.startsWith("store:")) {
+		const { resolveExtensionZipDownloadUrl, resolveExtensionsStoreBaseUrl, downloadExtensionStoreZipBuffer, verifyStoreArtifactSha256 } = await import("../../agent/skills/marketplace/adapters/store/store-api-client.js");
+		const spec = source.slice(6);
+		const match = /^([a-z0-9.-]+)(?:@([^/]+))?$/.exec(spec);
+		if (!match) throw new Error("Expected store:<package>[@version]");
+		const base = resolveExtensionsStoreBaseUrl(config);
+		const artifact = await resolveExtensionZipDownloadUrl(base, match[1], match[2]);
+		buffer = await downloadExtensionStoreZipBuffer(base, artifact.downloadUrl);
+		verifyStoreArtifactSha256(buffer, artifact.sha256);
+	} else {
+		const url = new URL(source);
+		const response = await createPluginHttpFetch(url, {})(url, { signal: AbortSignal.timeout(3e4) });
+		if (!response.ok || !response.body) throw new Error(`Plugin download failed (${response.status})`);
+		const reader = response.body.getReader();
+		const chunks = [];
+		let size = 0;
+		try {
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				size += value.length;
+				if (size > 50 * 1024 * 1024) throw new Error("Plugin download exceeds 50 MiB");
+				chunks.push(Buffer.from(value));
+			}
+		} finally {
+			await reader.cancel();
+		}
+		buffer = Buffer.concat(chunks);
+	}
+	return withAgentPluginArchive(buffer, fn);
+}
+//#endregion
+export { isAgentPluginArchive, withAgentPluginArchive, withAgentPluginSource };

package/dist/src/extensions/agent-plugins/store.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { type PluginInspection } from './validation.js';
+declare const receiptSchema: z.ZodObject<{
+    id: z.ZodString;
+    revision: z.ZodString;
+    source: z.ZodString;
+    installedAt: z.ZodString;
+    enabled: z.ZodBoolean;
+    integrity: z.ZodString;
+    capabilities: z.ZodArray<z.ZodString>;
+    previous: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        revision: z.ZodString;
+        source: z.ZodString;
+        installedAt: z.ZodString;
+        enabled: z.ZodBoolean;
+        integrity: z.ZodString;
+        capabilities: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginReceipt = z.infer<typeof receiptSchema>;
+export interface InstalledAgentPlugin extends PluginInspection {
+    id: string;
+    format: 'agent-plugin';
+    receipt: PluginReceipt;
+    readiness: 'ready' | 'setup_required' | 'degraded' | 'blocked';
+}
+export interface PluginInstallPlan extends PluginInspection {
+    integrity: string;
+    reviewHash: string;
+    addedCapabilities: string[];
+    installed: boolean;
+}
+export declare class AgentPluginStore {
+    readonly stateDir: string;
+    constructor(stateDir?: string);
+    private receiptsDir;
+    revisionKey(): string;
+    dataDir(id: string): string;
+    private revisionDir;
+    private receiptPath;
+    receipt(id: string): PluginReceipt | undefined;
+    private write;
+    private mutate;
+    get(id: string): InstalledAgentPlugin | undefined;
+    list(): InstalledAgentPlugin[];
+    active(): InstalledAgentPlugin[];
+    inspect(source: string): PluginInstallPlan;
+    private plan;
+    install(source: string, options?: {
+        reviewHash?: string;
+        replace?: boolean;
+        expectedId?: string;
+        sourceLabel?: string;
+    }): InstalledAgentPlugin;
+    setEnabled(id: string, enabled: boolean): InstalledAgentPlugin;
+    rollback(id: string): InstalledAgentPlugin;
+    remove(id: string, removeData?: boolean): void;
+    private withSource;
+}
+export {};