@mokuyoaxis/dsh-iris 0.2.7 → 0.3.0-alpha.1

package/lib/core-connection-store.js

@@ -0,0 +1,277 @@
+// Explicit owner-managed connection profiles. The business Core root and static grants are untouched.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createCoreRuntime } from './core-runtime.js';
+import { atomicCreatePrivate, atomicWritePrivate } from './private-storage.js';
+import { checkedClientConnection, checkedConnectionScopes, checkedDeclaredClient, readPrivateConnectionJson, connectionFail, CONNECTION_SCOPES } from './core-connections.js';
+import { checkedBridgeCapabilities, checkedBridgeTools, selectedBridgeTools } from './core-bridge-selection.js';
+import { exportMcpConfiguration } from './mcp-config.js';
+import { checkedConnectionTemplate } from './connection-template.js';
+import { connectionSkillResources } from './connection-skill.js';
+import { bridgeToolsForScopes } from './core-bridge-tools.js';
+import { resolveMcpConfigurationChoice, formatMcpConfiguration } from './mcp-delivery.js';
+import { checkedPluginSelection } from './plugin-selection.js';
+
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+const sha = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+const json = value => JSON.stringify(value, null, 2) + '\n';
+const inside = (parent, file) => { const relative = path.relative(parent, file); return !relative || !path.isAbsolute(relative) && relative !== '..' && !relative.startsWith('..' + path.sep); };
+const invalid = message => connectionFail('IRIS_CONNECTION_INPUT_INVALID', message);
+function privateDirectory(directory, create = false) {
+  if (create && !fs.existsSync(directory)) fs.mkdirSync(directory, { mode: 0o700 });
+  const stat = fs.lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || process.platform !== 'win32' && stat.mode & 0o077) {
+    connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '连接管理目录必须是私有普通目录');
+  }
+}
+function profile(input) {
+  const { label, scopes, capabilities } = input;
+  if (typeof label !== 'string' || !label.trim() || label.length > 80 || /[\x00-\x1f\x7f]/.test(label)) invalid('请输入 1–80 字符的连接名称');
+  checkedConnectionScopes(scopes); checkedBridgeCapabilities(capabilities);
+  const pluginOperations = checkedPluginSelection(input.pluginOperations);
+  const tools = input.tools === undefined ? selectedBridgeTools(capabilities, undefined, pluginOperations) : checkedBridgeTools(input.tools);
+  if (tools.some(name => !selectedBridgeTools(capabilities, undefined, pluginOperations).includes(name))) invalid('工具不属于所选功能');
+  return { label: label.trim(), scopes: [...scopes], capabilities: [...capabilities], tools, ...(pluginOperations.length ? { pluginOperations } : {}) };
+}
+function only(value, names) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !names.includes(key))) invalid('连接请求包含不支持的字段');
+}
+
+export function createManagedConnectionStore({ directory, dataRoot, rootId, getOrigin,
+  availableScopes = CONNECTION_SCOPES, availableTools, onChange = () => {}, beforeCreate = () => {} }) {
+  if (typeof directory !== 'string' || !path.isAbsolute(directory)) invalid('连接管理目录须为显式根外绝对路径');
+  checkedConnectionScopes(availableScopes);
+  const records = new Map(), hashes = new Map(), templates = new Map(), archived = new Map();
+  let root, owner, state = 'new', disposal;
+  const fileFor = id => path.join(root, 'profiles', id + '.json');
+  const archiveFor = id => path.join(root, 'archived', id + '.json');
+  function grant(record) {
+    return { rootId, connectionId: record.connectionId, adapterId: 'iris.mcp', harnessKind: 'generic', label: record.label,
+      accessToken: record.accessToken, scopes: [...record.scopes], capabilities: [...record.capabilities], tools: [...record.tools],
+      ...(record.pluginOperations?.length ? { pluginOperations: structuredClone(record.pluginOperations) } : {}) };
+  }
+  function checked(record) {
+    only(record, ['schemaVersion', 'rootId', 'connectionId', 'accessToken', 'label', 'scopes', 'capabilities', 'tools',
+      'revision', 'createdAt', 'updatedAt', 'revokedAt', 'creationDigest', 'lastContact', 'pluginOperations']);
+    if (record.schemaVersion !== 0 || record.rootId !== rootId || !UUID.test(record.connectionId)
+        || !Number.isSafeInteger(record.revision) || record.revision < 1 || !/^[a-f0-9]{64}$/.test(record.creationDigest)
+        || record.revokedAt !== null && typeof record.revokedAt !== 'string'
+        || ![record.createdAt, record.updatedAt, ...(record.revokedAt !== null ? [record.revokedAt] : [])].every(value => typeof value === 'string' && Number.isFinite(Date.parse(value)))) {
+      connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '连接档案版本、身份或修订无效');
+    }
+    profile(record);
+    const { scopes: _scopes, ...identity } = grant(record);
+    checkedClientConnection({ schemaVersion: 0, origin: 'http://127.0.0.1:1', ...identity });
+    if (record.lastContact !== null) {
+      const contact = record.lastContact;
+      if (!contact || Object.keys(contact).sort().join(',') !== 'at,clientInfo,source,transport' || contact.source !== 'client-declared'
+          || !['stdio', 'http'].includes(contact.transport) || typeof contact.at !== 'string' || !Number.isFinite(Date.parse(contact.at))) {
+        connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '客户端声明记录无效');
+      }
+      checkedDeclaredClient(contact.clientInfo);
+    }
+    return record;
+  }
+  function open() { if (state !== 'open') connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '连接管理尚未开启或已关闭'); }
+  function read(id) {
+    open();
+    if (!UUID.test(id)) invalid('连接身份无效');
+    const record = records.get(id);
+    if (!record) connectionFail('IRIS_CONNECTION_NOT_FOUND', '没有此可管理连接');
+    readPrivateConnectionJson(fileFor(id));
+    if (sha(fs.readFileSync(fileFor(id))) !== hashes.get(id)) connectionFail('IRIS_CONNECTION_CONFIG_CHANGED', '档案在服务外被修改，请停用服务后核对，未覆盖文件');
+    return record;
+  }
+  function persist(record, create = false) {
+    const bytes = json(record);
+    (create ? atomicCreatePrivate : atomicWritePrivate)(fileFor(record.connectionId), bytes);
+    records.set(record.connectionId, structuredClone(record)); hashes.set(record.connectionId, sha(bytes));
+    onChange(record.revokedAt ? null : grant(record), record.connectionId);
+  }
+  function readArchive(id) {
+    read(id); readPrivateConnectionJson(archiveFor(id));
+    if (sha(fs.readFileSync(archiveFor(id))) !== archived.get(id)) {
+      connectionFail('IRIS_CONNECTION_CONFIG_CHANGED', '删除档案在服务外被修改，已保留现场');
+    }
+  }
+  async function start() {
+    if (state !== 'new') invalid('连接管理只能显式启动一次');
+    const parent = fs.realpathSync(path.dirname(directory));
+    root = path.join(parent, path.basename(directory));
+    const physicalRoot = path.join(fs.realpathSync.native(parent), path.basename(directory)), physicalDataRoot = fs.realpathSync.native(dataRoot);
+    if (inside(physicalDataRoot, physicalRoot) || inside(physicalRoot, physicalDataRoot)) invalid('连接管理目录与 Core 数据根须相互独立');
+    privateDirectory(root, true);
+    const markerFile = path.join(root, 'store.json');
+    if (!fs.existsSync(markerFile)) {
+      if (fs.readdirSync(root).length) connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '现有非空目录不是 Iris 连接管理目录');
+      atomicCreatePrivate(markerFile, json({ schemaVersion: 0, rootId }));
+    }
+    const marker = readPrivateConnectionJson(markerFile);
+    if (Object.keys(marker).length !== 2 || marker.schemaVersion !== 0 || marker.rootId !== rootId) connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '连接管理目录属于其他数据空间或版本');
+    for (const name of ['profiles', 'clients', 'ownership', 'templates', 'archived']) privateDirectory(path.join(root, name), true);
+    owner = createCoreRuntime({ dataRoot: path.join(root, 'ownership'), mode: 'writer' });
+    try {
+      owner.start();
+      for (const name of fs.readdirSync(path.join(root, 'profiles'))) {
+        if (!/^[a-f0-9-]{36}\.json$/.test(name)) connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '连接档案目录存在未知文件，已保留现场');
+        const file = path.join(root, 'profiles', name), record = checked(readPrivateConnectionJson(file));
+        if (name !== record.connectionId + '.json') connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '连接档案身份与文件名不一致');
+        records.set(record.connectionId, record); hashes.set(record.connectionId, sha(fs.readFileSync(file)));
+      }
+      for (const name of fs.readdirSync(path.join(root, 'archived'))) {
+        if (!/^[a-f0-9-]{36}\.json$/.test(name)) connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '删除档案目录存在未知文件，已保留现场');
+        const file = path.join(root, 'archived', name), record = checked(readPrivateConnectionJson(file)), digest = sha(fs.readFileSync(file));
+        if (name !== record.connectionId + '.json' || !record.revokedAt || digest !== hashes.get(record.connectionId)) {
+          connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '删除档案与已撤销连接不一致，已保留现场');
+        }
+        archived.set(record.connectionId, digest);
+      }
+      for (const name of fs.readdirSync(path.join(root, 'templates'))) {
+        if (!/^[a-f0-9]{64}\.json$/.test(name) || templates.size >= 64) connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '模板目录存在未知文件或超过 64 项，已保留现场');
+        const file = path.join(root, 'templates', name), template = checkedConnectionTemplate(readPrivateConnectionJson(file));
+        if (sha(json(template)) + '.json' !== name || fs.readFileSync(file, 'utf8') !== json(template)) connectionFail('IRIS_CONNECTION_CONFIG_CHANGED', '模板内容与身份不一致，已保留现场');
+        templates.set(name.slice(0, -5), template);
+      }
+      state = 'open'; return activeGrants();
+    } catch (error) { await owner.dispose(); state = 'failed'; throw error; }
+  }
+  function activeGrants() { return [...records.values()].filter(value => !value.revokedAt).map(grant); }
+  function list() {
+    open();
+    return [...records.values()].filter(record => !archived.has(record.connectionId)).sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.connectionId.localeCompare(b.connectionId))
+      .map(({ accessToken: _secret, creationDigest: _input, ...record }) => ({ ...structuredClone(record),
+      managed: true, state: record.revokedAt ? 'revoked' : record.lastContact ? 'used' : 'pending', harnessInstalled: 'unknown' }));
+  }
+  function create(input) {
+    only(input, ['key', 'label', 'scopes', 'capabilities', 'tools', 'pluginOperations']);
+    if (!UUID.test(input.key)) invalid('新建连接需要稳定 UUID');
+    const value = profile(input), creationDigest = sha(JSON.stringify(value));
+    open();
+    if (archived.has(input.key)) { readArchive(input.key); connectionFail('IRIS_CONNECTION_REVOKED', '此创建标识的连接已删除，请使用新标识新建连接'); }
+    if (records.has(input.key)) {
+      const existing = read(input.key);
+      if (existing.creationDigest !== creationDigest) connectionFail('IRIS_CONNECTION_CONFIG_CHANGED', '此创建标识已用于另一套连接配置');
+      return { connectionId: existing.connectionId, idempotentReplay: true };
+    }
+    beforeCreate(input.key);
+    const now = new Date().toISOString();
+    persist({ schemaVersion: 0, rootId, connectionId: input.key, accessToken: crypto.randomBytes(32).toString('base64url'),
+      ...value, revision: 1, createdAt: now, updatedAt: now, revokedAt: null, creationDigest, lastContact: null }, true);
+    return { connectionId: input.key, idempotentReplay: false };
+  }
+  function update(id, input) {
+    only(input, ['expectedRevision', 'label', 'scopes', 'capabilities', 'tools', 'pluginOperations']);
+    const value = profile(input), record = read(id);
+    if (record.revokedAt) connectionFail('IRIS_CONNECTION_REVOKED', '此连接已撤销，请新建连接');
+    if (input.expectedRevision !== record.revision) connectionFail('IRIS_CONNECTION_CONFIG_CHANGED', '连接已改变，请刷新后重新编辑');
+    const { pluginOperations: _oldPlugins, ...original } = record;
+    persist({ ...original, ...value, revision: record.revision + 1, updatedAt: new Date().toISOString() });
+    return { connectionId: id, revision: record.revision + 1 };
+  }
+  function revoke(id, input) {
+    only(input, ['expectedRevision']);
+    const record = read(id);
+    if (record.revokedAt) return { connectionId: id, revoked: true, idempotentReplay: true };
+    if (input.expectedRevision !== record.revision) connectionFail('IRIS_CONNECTION_CONFIG_CHANGED', '连接已改变，请刷新后撤销');
+    const now = new Date().toISOString();
+    persist({ ...record, revision: record.revision + 1, updatedAt: now, revokedAt: now });
+    return { connectionId: id, revoked: true };
+  }
+  function remove(id, input) {
+    only(input, ['expectedRevision']);
+    const record = read(id);
+    if (archived.has(id)) { readArchive(id); return { connectionId: id, deleted: true, idempotentReplay: true }; }
+    if (input.expectedRevision !== record.revision) connectionFail('IRIS_CONNECTION_CONFIG_CHANGED', '连接已改变，请刷新后删除');
+    // Revoke durably before marking the record deleted. A failed archive leaves a visible, revoked connection.
+    if (!record.revokedAt) revoke(id, input);
+    privateDirectory(path.join(root, 'archived'));
+    const bytes = fs.readFileSync(fileFor(id));
+    atomicCreatePrivate(archiveFor(id), bytes);
+    archived.set(id, sha(bytes));
+    return { connectionId: id, deleted: true, idempotentReplay: false };
+  }
+  function observe(id, contact) {
+    if (!records.has(id)) return;
+    const record = read(id);
+    if (record.revokedAt) return;
+    // Display facts are checkpointed at first use, identity changes, and at most once a minute thereafter.
+    if (record.lastContact && JSON.stringify(record.lastContact.clientInfo) === JSON.stringify(contact.clientInfo)
+        && record.lastContact.transport === contact.transport && Date.parse(contact.at) - Date.parse(record.lastContact.at) < 60000) return;
+    const next = { ...record, lastContact: contact };
+    const bytes = json(next); atomicWritePrivate(fileFor(id), bytes);
+    records.set(id, next); hashes.set(id, sha(bytes));
+  }
+  function listTemplates() {
+    open();
+    return [...templates.entries()].map(([templateId, template]) => {
+      const file = path.join(root, 'templates', templateId + '.json');
+      readPrivateConnectionJson(file);
+      if (fs.readFileSync(file, 'utf8') !== json(template)) connectionFail('IRIS_CONNECTION_CONFIG_CHANGED', '模板在服务外被修改，已保留现场');
+      return { templateId, ...structuredClone(template) };
+    });
+  }
+  function importTemplate(input) {
+    const template = checkedConnectionTemplate(input); open();
+    const templateId = sha(json(template));
+    if (templates.has(templateId)) { listTemplates(); return { templateId, idempotentReplay: true }; }
+    if (templates.size >= 64) connectionFail('IRIS_CONNECTION_BUSY', '模板已达 64 项，请使用现有模板或手动选择格式');
+    atomicCreatePrivate(path.join(root, 'templates', templateId + '.json'), json(template));
+    templates.set(templateId, template); return { templateId, idempotentReplay: false };
+  }
+  function resolveExport(input) {
+    only(input, ['transport', 'format', 'templateId', 'presetId']);
+    if (input.templateId !== undefined) {
+      if (Object.keys(input).length !== 1 || typeof input.templateId !== 'string') invalid('模板不能与手动格式混用');
+      const template = listTemplates().find(item => item.templateId === input.templateId);
+      if (!template) invalid('没有此接入模板');
+      return { transport: template.transport, format: template.format };
+    }
+    if (input.presetId !== undefined) {
+      if (Object.keys(input).length !== 1) invalid('接入预设不能与模板或手动格式混用');
+      return resolveMcpConfigurationChoice(input);
+    }
+    if (Object.keys(input).length !== 2 || input.transport === undefined || input.format === undefined) invalid('请选择明确的传输与格式');
+    return resolveMcpConfigurationChoice(input);
+  }
+  function activeRecord(id) {
+    const record = read(id);
+    if (record.revokedAt) connectionFail('IRIS_CONNECTION_REVOKED', '已撤销连接不能导出');
+    return record;
+  }
+  function exportSkill(id, input) {
+    only(input, []);
+    const record = activeRecord(id), scopes = record.scopes.filter(scope => availableScopes.includes(scope));
+    const tools = bridgeToolsForScopes(scopes, record.capabilities, record.tools, record.pluginOperations).map(tool => tool.name)
+      .filter(name => availableTools === undefined || availableTools.includes(name));
+    if (!tools.length) invalid('此连接没有当前可用的工具，无法生成 Skill');
+    const { bundle, bytes } = connectionSkillResources({ schemaVersion: 0, kind: 'iris-mcp-skill', rootId,
+      connectionId: id, revision: record.revision, label: record.label, scopes, capabilities: record.capabilities, tools,
+      ...(record.pluginOperations?.length ? { pluginOperations: record.pluginOperations } : {}) });
+    return { bundle, preview: bytes['SKILL.md'].toString('utf8') };
+  }
+  function exportConfig(id, input) {
+    const choice = resolveExport(input), record = activeRecord(id);
+    const { scopes: savedScopes, ...identity } = grant(record);
+    const scopes = savedScopes.filter(scope => availableScopes.includes(scope));
+    const client = checkedClientConnection({ schemaVersion: 0, origin: getOrigin(), ...identity,
+      tools: identity.tools.filter(name => availableTools === undefined || availableTools.includes(name)) });
+    if (choice.transport === 'http') {
+      const entry = { url: getOrigin() + '/mcp', headers: { Authorization: 'Bearer ' + client.accessToken } };
+      return { ...formatMcpConfiguration(entry, choice), containsCredentials: true };
+    }
+    const content = json(client), clientFile = path.join(root, 'clients', sha(content) + '.json');
+    if (fs.existsSync(clientFile)) {
+      readPrivateConnectionJson(clientFile);
+      if (fs.readFileSync(clientFile, 'utf8') !== content) connectionFail('IRIS_CONNECTION_CONFIG_CHANGED', '导出副本被修改，已保留，未覆盖');
+    } else atomicCreatePrivate(clientFile, content);
+    const entry = exportMcpConfiguration({ connectionFile: clientFile, scopes, format: 'entry' });
+    return { ...formatMcpConfiguration(entry, choice), containsCredentials: false };
+  }
+  function dispose() {
+    if (!disposal) { state = 'closing'; disposal = Promise.resolve(owner?.dispose()).then(() => { records.clear(); hashes.clear(); templates.clear(); archived.clear(); state = 'closed'; }); }
+    return disposal;
+  }
+  return Object.freeze({ start, activeGrants, list, create, update, revoke, remove, observe,
+    listTemplates, importTemplate, resolveExport, exportSkill, exportConfig, dispose });
+}

package/lib/core-connections.js

@@ -0,0 +1,225 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { inspectExecutionRoot } from './operation-store.js';
+import { checkedBridgeCapabilities, checkedBridgeTools, selectedBridgeTools, DEFAULT_BRIDGE_CAPABILITIES, LEGACY_BRIDGE_TOOLS_V0 } from './core-bridge-selection.js';
+import { CORE_SCOPE_DEFINITIONS } from './core-capability-catalog.js';
+import { checkedPluginSelection, hasPluginSelection } from './plugin-selection.js';
+
+export const CONNECTION_CONTRACT_VERSION = 0;
+export const CONNECTION_SCOPES = Object.freeze(CORE_SCOPE_DEFINITIONS.map(scope => scope.id));
+export const HARNESS_ADAPTERS = Object.freeze([
+  Object.freeze({ adapterId: 'iris.mcp', harnessKinds: ['kimi', 'generic'], transport: 'stdio-to-local-http', contractVersions: [0] }),
+  Object.freeze({ adapterId: 'iris.dsh-service', harnessKinds: ['dsh'], transport: 'local-http', contractVersions: [0] })
+]);
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+const TOKEN = /^[A-Za-z0-9_-]{43}$/;
+const hash = value => crypto.createHash('sha256').update(value).digest();
+export function connectionFail(code, message) { throw Object.assign(new Error(message), { code }); }
+function exact(value, fields, optional = []) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !fields.includes(key) && !optional.includes(key))
+      || !fields.every(field => Object.hasOwn(value, field))) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '连接配置字段无效');
+}
+export function checkedCoreOrigin(value) {
+  const match = typeof value === 'string' && /^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})$/.exec(value);
+  if (!match || Number(match[1]) > 65535) {
+    connectionFail('IRIS_CONNECTION_INPUT_INVALID', 'Core 地址必须是 http://127.0.0.1:端口，不含路径或凭据');
+  }
+  return value;
+}
+function checkedIdentity(value) {
+  const adapter = HARNESS_ADAPTERS.find(item => item.adapterId === value.adapterId);
+  if (!adapter?.harnessKinds.includes(value.harnessKind) || !UUID.test(value.connectionId) || !UUID.test(value.rootId)
+      || typeof value.label !== 'string' || !value.label.trim() || value.label.length > 80
+      || /[\x00-\x1f\x7f]/.test(value.label)) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '接入身份或标签无效');
+}
+function checkedScopes(scopes) {
+  if (!Array.isArray(scopes) || !scopes.includes('read') || scopes.length > CONNECTION_SCOPES.length || new Set(scopes).size !== scopes.length
+      || scopes.some(scope => !CONNECTION_SCOPES.includes(scope))) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '连接权限必须包含 read，且仅允许已知的有限范围');
+}
+export { checkedScopes as checkedConnectionScopes };
+export function checkedDeclaredClient(value) {
+  exact(value, ['name', 'version'], ['title']);
+  for (const item of Object.values(value)) {
+    if (typeof item !== 'string' || !item.trim() || item.length > 160 || /[\x00-\x1f\x7f]/.test(item)) {
+      connectionFail('IRIS_CONNECTION_INPUT_INVALID', '客户端声明需要有界名称与版本');
+    }
+  }
+  return structuredClone(value);
+}
+export function projectedMcpClient(value) {
+  if (!value || typeof value.name !== 'string' || typeof value.version !== 'string') return null;
+  const text = item => item.replace(/[\x00-\x1f\x7f]/g, ' ').trim().slice(0, 160) || 'unknown';
+  return { name: text(value.name), version: text(value.version), ...(typeof value.title === 'string' && value.title.trim() ? { title: text(value.title) } : {}) };
+}
+export function readPrivateConnectionJson(file) {
+  if (typeof file !== 'string' || !path.isAbsolute(file)) connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '连接文件必须为显式绝对路径');
+  let stat, value;
+  try {
+    stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 64 * 1024 || process.platform !== 'win32' && stat.mode & 0o077) throw new Error('private file required');
+    value = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (_) { connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '连接文件不可读、格式损坏或权限过宽'); }
+  return value;
+}
+export function checkedClientConnection(value) {
+  exact(value, ['schemaVersion', 'origin', 'rootId', 'connectionId', 'adapterId', 'harnessKind', 'label', 'accessToken'], ['capabilities', 'tools', 'pluginOperations']);
+  if (value.schemaVersion !== 0 || !TOKEN.test(value.accessToken)) connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '连接凭据版本或格式不受支持');
+  checkedIdentity(value); checkedCoreOrigin(value.origin);
+  checkedPluginSelection(value.pluginOperations);
+  return { ...structuredClone(value), capabilities: checkedBridgeCapabilities(value.capabilities === undefined ? DEFAULT_BRIDGE_CAPABILITIES : value.capabilities),
+    tools: checkedBridgeTools(value.tools === undefined ? LEGACY_BRIDGE_TOOLS_V0 : value.tools) };
+}
+export function readConnectionGrants(file) {
+  const value = readPrivateConnectionJson(file);
+  exact(value, ['schemaVersion', 'grants']);
+  if (value.schemaVersion !== 0 || !Array.isArray(value.grants) || !value.grants.length || value.grants.length > 32) {
+    connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '需要 1–32 个显式连接授权');
+  }
+  const ids = new Set(), tokens = new Set();
+  for (const grant of value.grants) {
+    exact(grant, ['rootId', 'connectionId', 'adapterId', 'harnessKind', 'label', 'accessToken', 'scopes'], ['capabilities', 'tools', 'pluginOperations']);
+    checkedIdentity(grant); checkedScopes(grant.scopes);
+    checkedPluginSelection(grant.pluginOperations);
+    checkedBridgeCapabilities(grant.capabilities === undefined ? DEFAULT_BRIDGE_CAPABILITIES : grant.capabilities);
+    checkedBridgeTools(grant.tools === undefined ? LEGACY_BRIDGE_TOOLS_V0 : grant.tools);
+    if (!TOKEN.test(grant.accessToken) || ids.has(grant.connectionId) || tokens.has(grant.accessToken)) connectionFail('IRIS_CONNECTION_CONFIG_INVALID', '连接身份或凭据重复/无效');
+    ids.add(grant.connectionId); tokens.add(grant.accessToken);
+  }
+  return value.grants.map(grant => ({ ...structuredClone(grant), capabilities: [...(grant.capabilities ?? DEFAULT_BRIDGE_CAPABILITIES)],
+    tools: [...(grant.tools ?? LEGACY_BRIDGE_TOOLS_V0)] }));
+}
+/** Explicit new pairing directory. No harness configuration discovery or modification. */
+export function createConnectionPair({ dataRoot, directory, origin, harnessKind = 'generic', label, scopes = ['read'], capabilities = DEFAULT_BRIDGE_CAPABILITIES, tools, pluginOperations } = {}) {
+  checkedCoreOrigin(origin); checkedScopes(scopes);
+  checkedBridgeCapabilities(capabilities);
+  pluginOperations = checkedPluginSelection(pluginOperations);
+  tools = tools === undefined ? selectedBridgeTools(capabilities, undefined, pluginOperations) : checkedBridgeTools(tools);
+  if (tools.some(name => !selectedBridgeTools(capabilities, undefined, pluginOperations).includes(name))) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '工具不属于所选功能分组');
+  if (typeof dataRoot !== 'string' || !path.isAbsolute(dataRoot)) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '需要明确的 v1 数据根绝对路径');
+  const adapterId = harnessKind === 'dsh' ? 'iris.dsh-service' : 'iris.mcp';
+  const root = fs.realpathSync.native(dataRoot), marker = inspectExecutionRoot(root);
+  const client = { schemaVersion: 0, origin, rootId: marker.rootId, connectionId: crypto.randomUUID(), adapterId, harnessKind, label,
+    accessToken: crypto.randomBytes(32).toString('base64url'), capabilities: [...capabilities], tools: [...tools], ...(pluginOperations.length ? { pluginOperations } : {}) };
+  checkedClientConnection(client);
+  if (typeof directory !== 'string' || !path.isAbsolute(directory)) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '输出目录须为新的绝对路径');
+  const relative = path.relative(root, path.join(fs.realpathSync.native(path.dirname(directory)), path.basename(directory)));
+  if (!relative || !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative)) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '连接凭据须存放在数据根之外');
+  fs.mkdirSync(directory, { mode: 0o700 });
+  const serverFile = path.join(directory, 'server-grants.json'), clientFile = path.join(directory, 'client.json');
+  const { schemaVersion: _version, origin: _origin, ...grant } = client;
+  fs.writeFileSync(serverFile, JSON.stringify({ schemaVersion: 0, grants: [{ ...grant, scopes }] }, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+  fs.writeFileSync(clientFile, JSON.stringify(client, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+  return { contractVersion: 0, connectionId: client.connectionId, adapterId, harnessKind, scopes, capabilities, tools, serverFile, clientFile };
+}
+
+/** Authenticated, per-connection and per-runtime facts. No filesystem or Provider access. */
+export function createConnectionRegistry(grants, availableScopes, { onClientInfo = () => {}, availableCapabilities, availableTools } = {}) {
+  const configured = new Map(grants.map(grant => {
+    const { accessToken, ...publicGrant } = grant;
+    return [grant.connectionId, { ...structuredClone(publicGrant), capabilities: [...(grant.capabilities ?? DEFAULT_BRIDGE_CAPABILITIES)],
+      tools: [...(grant.tools ?? LEGACY_BRIDGE_TOOLS_V0)], tokenDigest: hash(accessToken), instances: new Map() }];
+  }));
+  function identify(connectionId, token) {
+    const grant = configured.get(connectionId);
+    if (!grant || !TOKEN.test(token) || !crypto.timingSafeEqual(hash(token), grant.tokenDigest)) connectionFail('IRIS_CONNECTION_AUTH_REQUIRED', '连接身份或凭据无效');
+    return grant.connectionId;
+  }
+  function handshake(connectionId, value) {
+    exact(value, ['contractVersion', 'adapterId', 'harnessKind', 'runtimeInstanceId', 'harnessVersion', 'requestedScopes'], ['requestedCapabilities', 'requestedTools', 'requestedPluginOperations']);
+    const grant = configured.get(connectionId);
+    if (value.contractVersion !== 0) connectionFail('IRIS_CONNECTION_VERSION_UNSUPPORTED', '连接契约版本不受支持');
+    if (value.adapterId !== grant.adapterId || value.harnessKind !== grant.harnessKind || !UUID.test(value.runtimeInstanceId)
+        || typeof value.harnessVersion !== 'string' || value.harnessVersion.length > 80 || /[\x00-\x1f\x7f]/.test(value.harnessVersion)) {
+      connectionFail('IRIS_CONNECTION_INPUT_INVALID', '握手身份不符合本地授权');
+    }
+    checkedScopes(value.requestedScopes);
+    const capabilities = checkedBridgeCapabilities(value.requestedCapabilities === undefined ? grant.capabilities : value.requestedCapabilities);
+    const tools = checkedBridgeTools(value.requestedTools === undefined ? grant.tools : value.requestedTools);
+    const pluginOperations = checkedPluginSelection(value.requestedPluginOperations === undefined ? grant.pluginOperations : value.requestedPluginOperations);
+    if (pluginOperations.some(pin => !hasPluginSelection(grant.pluginOperations || [], pin))) connectionFail('IRIS_CONNECTION_CAPABILITY_DENIED', '插件业务或版本不在明确授权中');
+    if (value.requestedScopes.some(scope => !grant.scopes.includes(scope) || !availableScopes.includes(scope))) {
+      connectionFail('IRIS_CONNECTION_CAPABILITY_DENIED', '请求的能力未获授权或服务未开启');
+    }
+    if (capabilities.some(id => !grant.capabilities.includes(id) || availableCapabilities && !availableCapabilities.includes(id)) || tools.some(name => !grant.tools.includes(name))) {
+      connectionFail('IRIS_CONNECTION_CAPABILITY_DENIED', '请求的功能或工具未获本地授权');
+    }
+    if (!grant.instances.has(value.runtimeInstanceId) && grant.instances.size >= 8) {
+      const retired = [...grant.instances.values()].find(instance => instance.state === 'disconnected');
+      if (retired) grant.instances.delete(retired.runtimeInstanceId);
+      else connectionFail('IRIS_CONNECTION_BUSY', '该连接实例数量已达上限，请由 owner 明确断开旧实例');
+    }
+    const now = new Date().toISOString(), instance = { runtimeInstanceId: value.runtimeInstanceId, harnessVersion: value.harnessVersion,
+      connectedAt: now, lastSeenAt: now, state: 'connected', scopes: [...value.requestedScopes], capabilities,
+      tools: selectedBridgeTools(capabilities, tools, pluginOperations).filter(name => availableTools === undefined || availableTools.includes(name)),
+      ...(pluginOperations.length ? { pluginOperations } : {}),
+      verification: 'handshake', liveness: 'not_probed' };
+    grant.instances.set(value.runtimeInstanceId, instance);
+    return { contractVersion: 0, rootId: grant.rootId, connectionId, adapterId: grant.adapterId, harnessKind: grant.harnessKind,
+      instance: structuredClone(instance), remoteHostPorts: [], connectionFeatures: ['client-info'] };
+  }
+  function authorize(connectionId, runtimeInstanceId, scope, tool) {
+    const grant = configured.get(connectionId), instance = grant?.instances.get(runtimeInstanceId);
+    if (!instance || instance.state !== 'connected') connectionFail('IRIS_CONNECTION_HANDSHAKE_REQUIRED', '请先完成本次服务的连接握手');
+    if (!instance.scopes.includes(scope)) connectionFail('IRIS_CONNECTION_CAPABILITY_DENIED', '此连接未获该操作权限');
+    if (tool && !instance.tools.includes(tool)) connectionFail('IRIS_CONNECTION_CAPABILITY_DENIED', '此功能或工具未被用户选择');
+    instance.lastSeenAt = new Date().toISOString();
+    return [...instance.scopes];
+  }
+  function disconnect(connectionId, runtimeInstanceId) {
+    const instance = configured.get(connectionId)?.instances.get(runtimeInstanceId);
+    if (!instance) connectionFail('IRIS_CONNECTION_HANDSHAKE_REQUIRED', '没有此连接实例');
+    instance.state = 'disconnected'; instance.lastSeenAt = new Date().toISOString();
+    return { contractVersion: 0, disconnected: true };
+  }
+  function list(connectionId) {
+    return { contractVersion: 0, adapters: structuredClone(HARNESS_ADAPTERS), connections: [...configured.values()]
+      .filter(grant => connectionId === undefined || grant.connectionId === connectionId)
+      .map(({ tokenDigest: _secret, instances, ...grant }) => ({ ...structuredClone(grant), configured: true,
+        harnessInstalled: 'unknown', instances: [...instances.values()].map(instance => structuredClone(instance)) })) };
+  }
+  function dispose() { for (const grant of configured.values()) grant.tokenDigest.fill(0); configured.clear(); }
+  function selection(connectionId, runtimeInstanceId) {
+    const instance = configured.get(connectionId).instances.get(runtimeInstanceId);
+    return { capabilities: [...instance.capabilities], tools: [...instance.tools], ...(instance.pluginOperations?.length ? { pluginOperations: structuredClone(instance.pluginOperations) } : {}) };
+  }
+  function clientInfo(connectionId, runtimeInstanceId, value) {
+    exact(value, ['clientInfo', 'transport']);
+    const info = checkedDeclaredClient(value.clientInfo);
+    if (!['stdio', 'http'].includes(value.transport)) connectionFail('IRIS_CONNECTION_INPUT_INVALID', 'MCP 传输声明无效');
+    const instance = configured.get(connectionId)?.instances.get(runtimeInstanceId);
+    if (!instance || instance.state !== 'connected') connectionFail('IRIS_CONNECTION_HANDSHAKE_REQUIRED', '请先连接当前实例');
+    const contact = { clientInfo: info, transport: value.transport, source: 'client-declared', at: new Date().toISOString() };
+    onClientInfo(connectionId, contact);
+    instance.declaredClient = contact; instance.lastSeenAt = contact.at;
+    return { contractVersion: 0, recorded: true };
+  }
+  function setGrant(grant) {
+    const old = configured.get(grant.connectionId), { accessToken, ...publicGrant } = grant;
+    const same = old && crypto.timingSafeEqual(old.tokenDigest, hash(accessToken))
+      && ['adapterId', 'harnessKind', 'scopes', 'capabilities', 'tools', 'pluginOperations'].every(key => JSON.stringify(old[key]) === JSON.stringify(publicGrant[key]));
+    if (old) old.tokenDigest.fill(0);
+    configured.set(grant.connectionId, { ...structuredClone(publicGrant), tokenDigest: hash(accessToken), instances: same ? old.instances : new Map() });
+    return { authorizationChanged: !same };
+  }
+  function revoke(connectionId) {
+    const grant = configured.get(connectionId);
+    if (grant) { grant.tokenDigest.fill(0); configured.delete(connectionId); }
+  }
+  function identifyMcp(token) {
+    if (!TOKEN.test(token)) connectionFail('IRIS_CONNECTION_AUTH_REQUIRED', '需要明确的 MCP 连接凭据');
+    const tokenDigest = hash(token);
+    const grant = [...configured.values()].find(item => crypto.timingSafeEqual(tokenDigest, item.tokenDigest));
+    if (!grant) connectionFail('IRIS_CONNECTION_AUTH_REQUIRED', 'MCP 连接凭据无效');
+    if (grant.adapterId !== 'iris.mcp') connectionFail('IRIS_CONNECTION_CAPABILITY_DENIED', '此凭据没有授权 MCP 接入');
+    const { tokenDigest: _secret, instances: _instances, ...publicGrant } = grant;
+    return structuredClone(publicGrant);
+  }
+  function authorizePlugin(connectionId, dependency) {
+    const grant = configured.get(connectionId);
+    if (!grant?.scopes.includes('execute') || !grant.tools.includes('iris_core_plugin_call') || !hasPluginSelection(grant.pluginOperations || [], dependency)) {
+      connectionFail('IRIS_CONNECTION_CAPABILITY_DENIED', '原连接的插件业务执行授权已缩减或撤销');
+    }
+  }
+  return Object.freeze({ identify, identifyMcp, handshake, authorize, authorizePlugin, selection, disconnect, list, clientInfo, setGrant, revoke, dispose });
+}

package/lib/core-maintenance.js

@@ -5,8 +5,9 @@ import { inspectCoreArtifact, refreshCoreArtifactInventory } from './core-artifa
 import { assertFlowTaskMatches, inspectCoreTask, listCoreTasks } from './core-tasks.js';
 import { atomicWritePrivate } from './private-storage.js';
 import { readDeliveryCache } from './core-delivery-cache.js';
-import { flowReferences } from './flow-store.js';
+import { flowReferences, flowStep } from './flow-store.js';
 import { creationReferences } from './creation-request-store.js';
+import { operationReferences } from './operation-store.js';
 
 const TASK = /^task_[a-f0-9]{24}$/;
 const ARTIFACT = /^artifact_[a-f0-9]{24}$/;
@@ -55,7 +56,7 @@ function inventory(root) {
     .map(name => inspectCoreArtifact(root, name.slice(0, -5)));
   const flows = flowReferences(root);
   for (const reference of flows) {
-    if (reference.run.edit.claimed && !tasks.some(task => task.id === reference.run.edit.taskId)) {
+    if (flowStep(reference.run).claimed && !tasks.some(task => task.id === flowStep(reference.run).taskId)) {
       fail('IRIS_FLOW_TASK_CONFLICT', '流程已建立的 Task 丢失，停止管理');
     }
   }
@@ -64,7 +65,7 @@ function inventory(root) {
     if (!reference) fail('IRIS_FLOW_TASK_CONFLICT', '流程 Task 的 Run 记录丢失，停止管理');
     assertFlowTaskMatches(task, reference.run);
   }
-  return { tasks, artifacts, flows, creations: creationReferences(root) };
+  return { tasks, artifacts, flows, creations: creationReferences(root), operations: operationReferences(root) };
 }
 
 function ids(value, pattern, label) {
@@ -78,6 +79,10 @@ export function planCoreDeletion(root, input) {
   if (!taskIds.length && !artifactIds.length) fail('IRIS_COMMAND_INPUT_INVALID', '请明确指定 Task 或 Artifact ID');
   const existing = inventory(root), selectedTasks = new Set(taskIds), selectedArtifacts = new Set(artifactIds);
   const blockers = [], files = [];
+  for (const reference of existing.operations) {
+    for (const id of reference.taskIds) if (selectedTasks.has(id)) blockers.push({ id, referencedBy: reference.operationId, reason: 'operation_task_reference' });
+    for (const id of reference.artifactIds) if (selectedArtifacts.has(id)) blockers.push({ id, referencedBy: reference.operationId, reason: 'operation_artifact_reference' });
+  }
   for (const reference of existing.creations) {
     for (const id of reference.taskIds) if (selectedTasks.has(id)) blockers.push({ id, referencedBy: reference.requestId, reason: 'creation_task_reference' });
     for (const id of reference.artifactIds) if (selectedArtifacts.has(id)) blockers.push({ id, referencedBy: reference.requestId, reason: 'creation_artifact_reference' });
@@ -136,6 +141,7 @@ export function planCoreCleanup(root, { older_than_ms = 3600000 } = {}) {
   if (!Number.isSafeInteger(older_than_ms) || older_than_ms < 60000) fail('IRIS_COMMAND_INPUT_INVALID', 'older_than_ms 至少为 60000');
   const existing = inventory(root);
   const referenced = new Set(existing.artifacts.map(artifact => artifact.id));
+  for (const reference of existing.operations) for (const id of reference.artifactIds) referenced.add(id);
   for (const reference of existing.creations) for (const id of reference.artifactIds) referenced.add(id);
   for (const reference of existing.flows) for (const id of reference.artifactIds) referenced.add(id);
   for (const artifact of existing.artifacts) for (const edge of artifact.relations) referenced.add(edge.artifactId);

package/lib/core-runtime.js

@@ -14,6 +14,7 @@ import {
 } from './core-contract.js';
 import { ensurePrivateDir } from './private-storage.js';
 import { listCreationRequests } from './creation-request-store.js';
+import { readAllOperations } from './operation-store.js';
 import { WRITER_LEASE_DIR, WRITER_INTENT_FILE, publishLeaseRecord, readWriterLease,
   removeWriterIntent, retireLeaseDirectory, writerOwnerStatus } from './core-writer-lease.js';
 
@@ -164,7 +165,7 @@ export function createCoreRuntime(input) {
     const candidateRoot = physicalDataRoot(options);
     const candidateLease = options.mode === 'writer' ? acquireWriterLease(candidateRoot, instanceId) : null;
     if (candidateLease) {
-      try { listCreationRequests(candidateRoot); }
+      try { listCreationRequests(candidateRoot); readAllOperations(candidateRoot); }
       catch (error) {
         try { releaseWriterLease(candidateLease); }
         catch (cleanupError) {