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

package/lib/network-config-service.js

@@ -0,0 +1,123 @@
+// Owner CLI resources and explicit bindings. Editing never sends network traffic.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { atomicCreatePrivate, atomicWritePrivate, ensurePrivateDir, privateSibling } from './private-storage.js';
+import { NETWORK_CONFIG_VERSION, NETWORK_ROUTING_CONFIG_VERSION, NETWORK_CONFIG_MAX_BYTES, networkConfigFail as fail, networkFields, normalizeNetworkNode, normalizeNetworkPool, validateNetworkConfig, projectNetworkConfig } from './network-config.js';
+
+const digest = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+function absolute(file) {
+  if (typeof file !== 'string' || !path.isAbsolute(file)) fail('IRIS_NETWORK_CONFIG_INVALID', 'network-config 必须是显式绝对路径');
+}
+function io(action) {
+  try { return action(); }
+  catch (error) {
+    if (typeof error.code !== 'string' || typeof error.syscall !== 'string') throw error;
+    const detail = /^[A-Z][A-Z0-9_]{0,39}$/.test(error.code) ? `（${error.code}）` : '';
+    fail('IRIS_NETWORK_CONFIG_IO', `网络配置文件操作失败${detail}，请检查目录权限、可用空间与文件状态；原文件和已有备份不会自动清理`);
+  }
+}
+export function readNetworkConfig(file) {
+  absolute(file);
+  const info = io(() => fs.lstatSync(file));
+  if (!info.isFile() || info.isSymbolicLink()) fail('IRIS_NETWORK_CONFIG_INVALID', 'network-config 必须是普通文件，不能使用符号链接');
+  if (process.platform !== 'win32' && (info.mode & 0o077) !== 0) fail('IRIS_NETWORK_CONFIG_PERMISSIONS', 'network-config 权限过宽，请限制为仅当前用户可读写');
+  if (info.size > NETWORK_CONFIG_MAX_BYTES) fail('IRIS_NETWORK_CONFIG_INVALID', 'network-config 不能超过1 MiB');
+  const bytes = io(() => fs.readFileSync(file));
+  if (bytes.length > NETWORK_CONFIG_MAX_BYTES) fail('IRIS_NETWORK_CONFIG_INVALID', 'network-config 不能超过1 MiB');
+  let parsed;
+  try { parsed = JSON.parse(bytes.toString('utf8')); }
+  catch (_) { fail('IRIS_NETWORK_CONFIG_INVALID', 'network-config 不是有效 JSON；请修正原文件，不会自动回退'); }
+  return { config: validateNetworkConfig(parsed), bytes, revision: digest(bytes) };
+}
+
+const READS = ['show', 'check', 'nodes.list', 'pools.list', 'bindings.list'];
+const WRITES = ['nodes.add', 'nodes.set', 'nodes.remove', 'pools.add', 'pools.set', 'pools.remove', 'bindings.set', 'bindings.remove'];
+export function executeNetworkConfigCommand(file, command, input = {}, { signal, env = process.env } = {}) {
+  absolute(file); signal?.throwIfAborted();
+  if (['init', 'routing.init', 'routing.copy'].includes(command)) {
+    const copy = command === 'routing.copy', routing = command !== 'init';
+    networkFields(input, copy ? ['source'] : [], copy ? ['source'] : []);
+    const source = copy ? readNetworkConfig(input.source).config : undefined;
+    const config = { schemaVersion: routing ? NETWORK_ROUTING_CONFIG_VERSION : NETWORK_CONFIG_VERSION,
+      configId: crypto.randomUUID(), generation: 1, nodes: source?.nodes || [], pools: source?.pools || [], ...(routing ? { bindings: [] } : {}) };
+    io(() => {
+      ensurePrivateDir(path.dirname(file));
+      try { atomicCreatePrivate(file, JSON.stringify(config, null, 2) + '\n'); }
+      catch (error) { if (error.code === 'EEXIST') fail('IRIS_NETWORK_CONFIG_EXISTS', '网络配置已存在，初始化不会覆盖；请先读取并核对'); throw error; }
+    });
+    const saved = readNetworkConfig(file);
+    return { command, created: true, ...projectNetworkConfig(saved.config, saved.revision, env) };
+  }
+  if (!READS.includes(command) && !WRITES.includes(command)) fail('IRIS_NETWORK_CONFIG_INVALID', '不支持的网络配置命令');
+  const before = readNetworkConfig(file);
+  if (command.startsWith('bindings.') && before.config.schemaVersion !== NETWORK_ROUTING_CONFIG_VERSION) {
+    fail('IRIS_NETWORK_CONFIG_VERSION', '绑定只用于显式新建的 v2 网络配置；可用 routing.copy 另存新文件，原文件不会自动迁移');
+  }
+  if (READS.includes(command)) {
+    networkFields(input, []);
+    return { command, ...(command === 'check' ? { valid: true, networkTested: false } : {}), ...projectNetworkConfig(before.config, before.revision, env) };
+  }
+  const [group, verb] = command.split('.'), field = group === 'nodes' ? 'node' : 'pool';
+  const fields = group === 'bindings' ? ['expectedRevision', 'catalogId', 'providerId', ...(verb === 'set' ? ['poolId'] : ['confirm'])]
+    : verb === 'remove' ? ['expectedRevision', 'id', 'confirm'] : ['expectedRevision', field];
+  networkFields(input, fields, fields);
+  if (input.expectedRevision !== before.revision) fail('IRIS_NETWORK_CONFIG_CHANGED', '网络配置已变化，请重新读取后核对编辑');
+  const next = structuredClone(before.config), records = next[group];
+  if (group === 'bindings') {
+    const index = records.findIndex(binding => binding.catalogId === input.catalogId && binding.providerId === input.providerId);
+    if (verb === 'remove') {
+      if (input.confirm !== true) fail('IRIS_NETWORK_CONFIG_INVALID', '删除绑定需要明确 confirm:true');
+      if (index < 0) fail('IRIS_NETWORK_CONFIG_NOT_FOUND', '所选绑定不存在');
+      records.splice(index, 1);
+    } else {
+      const binding = { catalogId: input.catalogId, providerId: input.providerId, poolId: input.poolId };
+      if (index < 0) records.push(binding); else records[index] = binding;
+    }
+  } else if (verb === 'remove') {
+    if (input.confirm !== true) fail('IRIS_NETWORK_CONFIG_INVALID', '删除资源需要明确 confirm:true');
+    const index = records.findIndex(record => record.id === input.id);
+    if (index < 0) fail('IRIS_NETWORK_CONFIG_NOT_FOUND', '所选网络资源不存在');
+    if (group === 'nodes' && next.pools.some(pool => pool.candidates.some(candidate => candidate.kind === 'node' && candidate.nodeId === input.id))) {
+      fail('IRIS_NETWORK_CONFIG_IN_USE', '节点仍被池引用；请先显式编辑或移除引用，停用的池也保留引用');
+    }
+    if (group === 'pools' && next.bindings?.some(binding => binding.poolId === input.id)) {
+      fail('IRIS_NETWORK_CONFIG_IN_USE', '池仍被供应商绑定引用；请先显式解除绑定，停用的池也保留引用');
+    }
+    records.splice(index, 1);
+  } else {
+    const supplied = input[field];
+    networkFields(supplied, group === 'nodes' ? ['id', 'label', 'enabled', 'protocol', 'host', 'port', 'auth'] : ['id', 'label', 'enabled', 'mode', 'candidates'], ['id']);
+    const index = records.findIndex(record => record.id === supplied.id);
+    if (verb === 'add' && index !== -1) fail('IRIS_NETWORK_CONFIG_EXISTS', '同类网络资源 ID 已存在，不能覆盖');
+    if (verb === 'set' && index === -1) fail('IRIS_NETWORK_CONFIG_NOT_FOUND', '所选网络资源不存在');
+    const normalize = group === 'nodes' ? normalizeNetworkNode : normalizeNetworkPool;
+    const record = normalize(verb === 'set' ? { ...records[index], ...supplied } : supplied);
+    if (verb === 'set') records[index] = record; else records.push(record);
+  }
+  const validated = validateNetworkConfig(next);
+  const changed = JSON.stringify(validated) !== JSON.stringify(before.config);
+  let fd;
+  try { fd = io(() => {
+    try { return fs.openSync(file + '.lock', 'wx', 0o600); }
+    catch (error) { if (error.code === 'EEXIST') fail('IRIS_NETWORK_CONFIG_BUSY', '网络配置正在修改或留有未核查的锁；不会自动删除或抢占，请核查写入进程'); throw error; }
+  });
+    // Revalidate the schema before CAS; a newer writer must never be downgraded.
+    const current = readNetworkConfig(file);
+    if (current.revision !== before.revision) fail('IRIS_NETWORK_CONFIG_CHANGED', '网络配置在编辑期间变化，请重新读取后核对');
+    signal?.throwIfAborted();
+    if (!changed) return { command, changed: false, ...projectNetworkConfig(current.config, current.revision, env) };
+    if (validated.generation === Number.MAX_SAFE_INTEGER) fail('IRIS_NETWORK_CONFIG_INVALID', '网络配置修订已超出支持范围');
+    validated.generation++;
+    const encoded = Buffer.from(JSON.stringify(validated, null, 2) + '\n');
+    if (encoded.length > NETWORK_CONFIG_MAX_BYTES) fail('IRIS_NETWORK_CONFIG_INVALID', 'network-config 不能超过1 MiB');
+    const backupPath = privateSibling(file, 'backup');
+    io(() => {
+      fs.writeFileSync(backupPath, before.bytes, { flag: 'wx', mode: 0o600 });
+      atomicWritePrivate(file, encoded);
+    });
+    return { command, changed: true, backupPath, ...projectNetworkConfig(validated, digest(encoded), env) };
+  } finally {
+    if (fd !== undefined) io(() => { try { fs.closeSync(fd); } finally { fs.unlinkSync(file + '.lock'); } });
+  }
+}

package/lib/network-config.js

@@ -0,0 +1,127 @@
+// Private, explicit network resources. This schema does not activate routing.
+import { isIP } from 'node:net';
+import { redactProviderMessage } from './provider-contract.js';
+
+export const NETWORK_CONFIG_VERSION = 1;
+export const NETWORK_ROUTING_CONFIG_VERSION = 2;
+export const NETWORK_CONFIG_MAX_BYTES = 1024 * 1024;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const ENV = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+export function networkConfigFail(code, message) { throw Object.assign(new Error(message), { code }); }
+const invalid = message => networkConfigFail('IRIS_NETWORK_CONFIG_INVALID', message);
+export function networkFields(value, allowed, required = []) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+      || Object.keys(value).some(key => !allowed.includes(key)) || required.some(key => !Object.hasOwn(value, key))) {
+    invalid('网络配置字段不符合约定，请检查对应对象的字段名称与必填项');
+  }
+}
+
+function identity(value) {
+  if (typeof value !== 'string' || !ID.test(value)) invalid('资源 ID 须为1–64字符的字母、数字、点、短横线或下划线，且以字母或数字开头');
+  return value;
+}
+function label(value) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 120 || /[\x00-\x1f\x7f]/.test(value)) invalid('资源名称须为非空且最多120字符的单行文本');
+  return value.trim();
+}
+
+export function normalizeNetworkNode(value) {
+  networkFields(value, ['id', 'label', 'enabled', 'protocol', 'host', 'port', 'auth'], ['id', 'protocol', 'host', 'port']);
+  const id = identity(value.id);
+  if (!['http', 'https'].includes(value.protocol)) invalid('代理协议当前只接受 http 或 https；协议声明不代表已完成连通测试');
+  if (typeof value.host !== 'string' || !value.host || value.host.length > 253 || /[\s/\\@?#%]/.test(value.host)
+      || !Number.isInteger(value.port) || value.port < 1 || value.port > 65535) invalid('代理 host 和 port 无效；请分开填写主机与1–65535端口，不填写认证 URL');
+  let host = value.host;
+  if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1);
+  if (host.includes(':') && isIP(host) !== 6) invalid('代理 IPv6 地址无效');
+  try {
+    const url = new URL(`${value.protocol}://${isIP(host) === 6 ? '[' + host + ']' : host}:${value.port}`);
+    if (!url.hostname || url.username || url.password || url.pathname !== '/' || url.search || url.hash) invalid('代理 host 无效');
+    host = url.hostname.replace(/^\[|\]$/g, '');
+  } catch (error) {
+    if (error.code === 'IRIS_NETWORK_CONFIG_INVALID') throw error;
+    invalid('代理 host 无效');
+  }
+  if (value.enabled !== undefined && typeof value.enabled !== 'boolean') invalid('enabled 必须是布尔值');
+  let auth;
+  if (value.auth !== undefined && value.auth !== null) {
+    networkFields(value.auth, ['usernameEnv', 'passwordEnv'], ['usernameEnv', 'passwordEnv']);
+    if (![value.auth.usernameEnv, value.auth.passwordEnv].every(name => typeof name === 'string' && ENV.test(name))) invalid('代理认证只接受成对的用户名/密码环境变量名');
+    auth = { usernameEnv: value.auth.usernameEnv, passwordEnv: value.auth.passwordEnv };
+  }
+  return { id, label: label(value.label === undefined ? id : value.label), enabled: value.enabled ?? true, protocol: value.protocol, host, port: value.port, ...(auth ? { auth } : {}) };
+}
+
+export function normalizeNetworkPool(value) {
+  networkFields(value, ['id', 'label', 'enabled', 'mode', 'candidates'], ['id', 'mode', 'candidates']);
+  const id = identity(value.id);
+  if (!['fixed', 'ordered'].includes(value.mode) || !Array.isArray(value.candidates)
+      || value.candidates.length > (value.mode === 'fixed' ? 1 : 16)) invalid('池需要 fixed（最多1候选）或 ordered（最多16候选），空候选仅为草稿');
+  if (value.enabled !== undefined && typeof value.enabled !== 'boolean') invalid('enabled 必须是布尔值');
+  const seen = new Set();
+  const candidates = value.candidates.map(candidate => {
+    networkFields(candidate, ['kind', 'nodeId'], ['kind']);
+    let next, key;
+    if (candidate.kind === 'node') { next = { kind: 'node', nodeId: identity(candidate.nodeId) }; key = 'node:' + next.nodeId; }
+    else if (candidate.kind === 'direct' && !Object.hasOwn(candidate, 'nodeId')) { next = { kind: 'direct' }; key = 'direct'; }
+    else invalid('池候选必须是明确的 node 引用或 direct');
+    if (seen.has(key)) invalid('池中不能重复引用同一节点或直连候选');
+    seen.add(key); return next;
+  });
+  return { id, label: label(value.label === undefined ? id : value.label), enabled: value.enabled ?? true, mode: value.mode, candidates };
+}
+
+export function validateNetworkConfig(value) {
+  if (![NETWORK_CONFIG_VERSION, NETWORK_ROUTING_CONFIG_VERSION].includes(value?.schemaVersion)) networkConfigFail('IRIS_NETWORK_CONFIG_VERSION', '不支持此网络配置版本；请使用兼容版本，原文件不会自动迁移或覆盖');
+  const routing = value.schemaVersion === NETWORK_ROUTING_CONFIG_VERSION;
+  const fields = ['schemaVersion', 'configId', 'generation', 'nodes', 'pools', ...(routing ? ['bindings'] : [])];
+  networkFields(value, fields, fields);
+  if (typeof value.configId !== 'string' || !UUID.test(value.configId) || !Number.isSafeInteger(value.generation) || value.generation < 1
+      || !Array.isArray(value.nodes) || !Array.isArray(value.pools) || value.nodes.length > 256 || value.pools.length > 256) invalid('网络配置身份、修订或资源列表无效（节点/池各最多256项）');
+  const nodes = value.nodes.map(normalizeNetworkNode), pools = value.pools.map(normalizeNetworkPool);
+  const ids = new Set(nodes.map(node => node.id));
+  if (ids.size !== nodes.length || new Set(pools.map(pool => pool.id)).size !== pools.length) invalid('同类资源 ID 不能重复');
+  for (const pool of pools) for (const candidate of pool.candidates) {
+    if (candidate.kind === 'node' && !ids.has(candidate.nodeId)) invalid('池引用了不存在的节点；请先添加节点或显式编辑候选');
+  }
+  let bindings;
+  if (routing) {
+    if (!Array.isArray(value.bindings) || value.bindings.length > 1024) invalid('网络绑定必须是最多1024项的列表');
+    const seen = new Set(), poolIds = new Set(pools.map(pool => pool.id));
+    bindings = value.bindings.map(binding => {
+      networkFields(binding, ['catalogId', 'providerId', 'poolId'], ['catalogId', 'providerId', 'poolId']);
+      if (typeof binding.catalogId !== 'string' || !UUID.test(binding.catalogId)
+          || typeof binding.providerId !== 'string' || !binding.providerId.trim() || binding.providerId.length > 256
+          || /[\x00-\x1f\x7f]/.test(binding.providerId)) invalid('绑定需要有效的目录身份与供应商 ID');
+      const poolId = identity(binding.poolId), key = JSON.stringify([binding.catalogId, binding.providerId]);
+      if (seen.has(key) || !poolIds.has(poolId)) invalid('绑定重复或引用了不存在的池');
+      seen.add(key);
+      return { catalogId: binding.catalogId, providerId: binding.providerId, poolId };
+    });
+  }
+  return { schemaVersion: value.schemaVersion, configId: value.configId, generation: value.generation, nodes, pools, ...(routing ? { bindings } : {}) };
+}
+
+export function networkNodeCredentialStatus(node, env = process.env) {
+  if (!node.auth) return 'none';
+  const values = [env[node.auth.usernameEnv], env[node.auth.passwordEnv]];
+  if (values.some(value => typeof value !== 'string' || !value.length)) return 'missing';
+  return values.some(value => value.length > 4096 || /[\x00-\x1f\x7f]/.test(value)) || values[0].includes(':') ? 'invalid' : 'ready';
+}
+
+export function projectNetworkConfig(config, revision, env = process.env) {
+  const secrets = [...new Set(config.nodes.flatMap(node => node.auth ? [env[node.auth.usernameEnv], env[node.auth.passwordEnv]] : [])
+    .filter(value => typeof value === 'string' && value.length))].sort((a, b) => b.length - a.length);
+  const display = value => redactProviderMessage(secrets.reduce((text, secret) => text.split(secret).join('[redacted]'), value));
+  const nodes = config.nodes.map(node => ({ ...node, label: display(node.label), host: display(node.host), credentialStatus: networkNodeCredentialStatus(node, env),
+    referencedBy: config.pools.filter(pool => pool.candidates.some(candidate => candidate.kind === 'node' && candidate.nodeId === node.id)).map(pool => pool.id) }));
+  const pools = config.pools.map(pool => ({ ...pool, label: display(pool.label),
+    ...(config.bindings ? { referencedBy: config.bindings.filter(binding => binding.poolId === pool.id).map(({ catalogId, providerId }) => ({ catalogId, providerId })) } : {}),
+    status: !pool.enabled ? 'disabled' : !pool.candidates.length ? 'empty'
+    : pool.candidates.some(candidate => candidate.kind === 'direct' || nodes.some(node => node.id === candidate.nodeId && node.enabled && ['none', 'ready'].includes(node.credentialStatus))) ? 'configured' : 'unavailable' }));
+  return { schemaVersion: config.schemaVersion, configId: config.configId, generation: config.generation, revision,
+    ...(config.bindings ? { routingConfigured: config.bindings.length > 0, runtimeStatus: 'not_observed' } : { routingActive: false }), nodes, pools,
+    ...(config.bindings ? { bindings: config.bindings.map(binding => ({ ...binding })) } : {}) };
+}

package/lib/network-doctor.js

@@ -0,0 +1,94 @@
+// Explicit GET diagnostics in the caller's Core process, never a media probe.
+import net from 'node:net';
+import { performance } from 'node:perf_hooks';
+import { loadProviderCatalog } from './provider-catalog.js';
+import { providerMediaBaseUrl } from './provider-protocol.js';
+import { networkManagementSettings } from './network-management.js';
+import { networkFields } from './network-config.js';
+import { providerNetworkRequirement, sameNetworkRequirement, networkPolicyError } from './network-policy.js';
+import { inheritedProviderFetch } from './provider-network.js';
+import { readProviderText } from './provider-response.js';
+import { settingsRevision } from './provider-config-service.js';
+
+export const NETWORK_PROBE_TIMEOUT_MS = 8000, NETWORK_PROBE_MAX_BYTES = 16 * 1024;
+const proxyNames = ['HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'all_proxy', 'no_proxy'];
+export function networkEnvironmentFacts({ env = process.env, execArgv = process.execArgv } = {}) {
+  const nodeFlagRequested = execArgv.includes('--use-env-proxy') || /(?:^|\s)--use-env-proxy(?:\s|$)/.test(env.NODE_OPTIONS || '') || env.NODE_USE_ENV_PROXY === '1';
+  return { variables: Object.fromEntries(proxyNames.map(name => [name, Boolean(env[name])])), nodeFlagRequested,
+    inheritedPolicy: 'unknown', systemTunnel: 'unknown',
+    note: '变量存在或Node开关被请求不等于所有请求已代理；宿主fetch/dispatcher和系统TUN的实际路径未由静态检查证明。' };
+}
+export function networkDoctor(options) {
+  const report = { contractVersion: 0, observedAt: new Date().toISOString(), source: 'core-process',
+    process: { node: process.version, platform: process.platform, arch: process.arch },
+    environment: networkEnvironmentFacts(), networkTested: false };
+  try { return { ...report, settings: networkManagementSettings(options), configuration: { state: 'readable' } }; }
+  catch (error) {
+    if (!/^IRIS_(?:NETWORK|PROVIDER)_/.test(error.code || '')) throw error;
+    return { ...report, settings: null, configuration: { state: 'invalid', issue: error.code,
+      message: '指定的网络或供应商配置无法读取；请核对文件版本、格式、权限与错误码。未自动修复或联网。' } };
+  }
+}
+
+export async function probeNetworkRoute(options, input, { signal } = {}) {
+  const fields = ['expectedRevision', 'expectedProviderRevision', 'providerId', 'target', ...(input?.target === 'provider' ? [] : ['url'])];
+  networkFields(input, fields, fields);
+  if (!['provider', 'custom', 'ip'].includes(input.target)) throw networkPolicyError('IRIS_NETWORK_PROBE_INVALID', '请选择供应商地址、自定义GET或IP观察');
+  if (input.target !== 'provider' && (typeof input.url !== 'string' || !input.url || input.url.length > 2048)) throw networkPolicyError('IRIS_NETWORK_PROBE_INVALID', '测试URL须为最多2048字符的文本');
+  const settings = networkManagementSettings(options);
+  if (input.expectedRevision !== settings.network?.revision || input.expectedProviderRevision !== settings.catalog.revision) {
+    throw networkPolicyError('IRIS_NETWORK_CONFIG_CHANGED', '网络或供应商目录已变化，请重新读取后测试');
+  }
+  if (['mismatch', 'missing_network'].includes(settings.catalog.state)) throw networkPolicyError('IRIS_NETWORK_CONFIG_MISMATCH', '供应商与网络配置不匹配，未进行测试');
+  if (!settings.providers.some(provider => provider.id === input.providerId)) throw networkPolicyError('IRIS_NETWORK_PROVIDER_NOT_FOUND', '测试需要当前目录中的明确供应商');
+  const catalog = loadProviderCatalog(options.providerConfigPath), provider = catalog.providers.find(item => item.id === input.providerId);
+  if (settingsRevision(catalog) !== input.expectedProviderRevision) throw networkPolicyError('IRIS_NETWORK_PROVIDER_CHANGED', '供应商目录已变化，未进行测试');
+  if (!provider) throw networkPolicyError('IRIS_NETWORK_PROVIDER_NOT_FOUND', '测试需要当前目录中的明确供应商');
+  let target;
+  try { target = new URL(input.target === 'provider' ? providerMediaBaseUrl(provider) : input.url); }
+  catch (_) { throw networkPolicyError('IRIS_NETWORK_PROBE_INVALID', '测试地址需要有效的HTTP(S) URL'); }
+  if (!['http:', 'https:'].includes(target.protocol) || target.username || target.password || target.hash) {
+    throw networkPolicyError('IRIS_NETWORK_PROBE_INVALID', '测试地址只接受不含认证信息或片段的HTTP(S) URL');
+  }
+  const combined = AbortSignal.any([AbortSignal.timeout(NETWORK_PROBE_TIMEOUT_MS), ...(signal ? [signal] : [])]);
+  const started = performance.now(); let route = null, dispatchStarted = false, status = null, responseReceived = false;
+  const report = () => ({ contractVersion: 0, source: 'core-process', observedAt: new Date().toISOString(),
+    providerId: provider.id, target: { kind: input.target, origin: target.origin }, elapsedMs: Math.round(performance.now() - started),
+    timeoutMs: NETWORK_PROBE_TIMEOUT_MS, maxBytes: NETWORK_PROBE_MAX_BYTES, requestLimit: 1, requestLimitKind: 'application_get',
+    dispatchStarted, responseReceived, httpStatus: status, route,
+    note: '只表示本次目标与路线；不证明其他服务、所有任务或系统TUN行为。不携带供应商Key，不生成媒体。' });
+  try {
+    const requirement = providerNetworkRequirement(provider);
+    const network = requirement ? options.resolveProviderNetwork?.({ providerId: provider.id, networkRequirement: requirement }) : undefined;
+    if (requirement && (!network || network.providerId !== provider.id || !sameNetworkRequirement(requirement, network.networkRequirement))) throw networkPolicyError('IRIS_NETWORK_CONTEXT_REQUIRED', '测试需要匹配的Core网络上下文，不会静默直连');
+    const action = async fetch => {
+      combined.throwIfAborted();
+      if (!network) { dispatchStarted = true; route = { route: 'inherit', providerId: provider.id, legacy: true }; }
+      const response = await fetch(target.href, { method: 'GET', redirect: 'error', credentials: 'omit', signal: combined,
+        headers: { Accept: input.target === 'ip' ? 'application/json' : '*/*' } });
+      status = response.status; responseReceived = true;
+      const text = await readProviderText(response, { maxBytes: NETWORK_PROBE_MAX_BYTES, stage: 'discover', acceptance: 'not_accepted' });
+      let observedIp;
+      if (input.target === 'ip' && response.ok) {
+        let value; try { value = JSON.parse(text); } catch (_) { /* Report a limited observation, never the response body. */ }
+        if (value && typeof value.ip === 'string' && net.isIP(value.ip)) observedIp = value.ip;
+        else return { ...report(), ok: false, reachable: true, issue: 'IRIS_NETWORK_IP_NOT_OBSERVED' };
+      }
+      return { ...report(), ok: response.ok, reachable: true, ...(observedIp ? { observedIp } : {}),
+        ...(!response.ok ? { issue: 'IRIS_NETWORK_TARGET_HTTP_ERROR' } : {}) };
+    };
+    return network ? await network.run(action, { operation: 'discover', recordNetworkRoute: fact => {
+      dispatchStarted = true;
+      route = { route: fact.route, providerId: fact.providerId, ...(fact.poolId ? { poolId: fact.poolId } : {}),
+        ...(fact.nodeId ? { nodeId: fact.nodeId } : {}), configGeneration: fact.configGeneration, configRevision: fact.configRevision };
+    } }) : await action(inheritedProviderFetch);
+  } catch (error) {
+    signal?.throwIfAborted();
+    const code = error.providerCode || error.code;
+    if (!(error instanceof TypeError && !error.code) && !['AbortError', 'TimeoutError'].includes(error.name)
+        && !/^IRIS_NETWORK_/.test(code || '') && code !== 'IRIS_PROVIDER_RESPONSE_TOO_LARGE') throw error;
+    return { ...report(), ok: false, reachable: responseReceived,
+      issue: combined.aborted ? 'IRIS_NETWORK_PROBE_TIMEOUT' : code === 'IRIS_PROVIDER_RESPONSE_TOO_LARGE' ? 'IRIS_NETWORK_PROBE_TOO_LARGE'
+        : /^IRIS_NETWORK_/.test(code || '') ? code : 'IRIS_NETWORK_PROBE_FAILED' };
+  }
+}

package/lib/network-management.js

@@ -0,0 +1,51 @@
+// Owner-only composition over the existing resource store. No implicit enrollment.
+import fs from 'node:fs';
+import { readNetworkConfig, executeNetworkConfigCommand } from './network-config-service.js';
+import { networkFields, projectNetworkConfig } from './network-config.js';
+import { loadProviderCatalog } from './provider-catalog.js';
+import { projectProviderSettings } from './provider-settings.js';
+import { settingsRevision } from './provider-config-service.js';
+import { providerNetworkRequirement, networkPolicyError } from './network-policy.js';
+
+export const NETWORK_MANAGEMENT_ACTIONS = Object.freeze(['init', 'nodes/add', 'nodes/set', 'nodes/remove',
+  'pools/add', 'pools/set', 'pools/remove', 'bindings/set', 'bindings/remove']);
+
+export function networkManagementSettings({ networkConfigPath, providerConfigPath, registry }) {
+  let saved;
+  try { fs.lstatSync(networkConfigPath); saved = readNetworkConfig(networkConfigPath); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const catalog = providerConfigPath ? loadProviderCatalog(providerConfigPath) : undefined;
+  const requirement = providerNetworkRequirement(catalog);
+  const revision = catalog ? settingsRevision(catalog) : null;
+  const state = !catalog ? 'absent' : !requirement ? 'legacy' : !saved ? 'missing_network'
+    : saved.config.schemaVersion !== 2 || saved.config.configId !== requirement.configId ? 'mismatch' : 'ready';
+  const network = saved ? projectNetworkConfig(saved.config, saved.revision) : null;
+  const settings = catalog ? projectProviderSettings(catalog, revision, registry) : undefined;
+  const providers = (settings?.providers || []).map(provider => {
+    const binding = state === 'ready' && saved.config.bindings.find(item => item.catalogId === requirement.catalogId && item.providerId === provider.id);
+    const pool = binding && network.pools.find(item => item.id === binding.poolId);
+    return { id: provider.id, name: provider.name, enabled: provider.enabled,
+      route: { state: ['mismatch', 'missing_network'].includes(state) ? 'blocked' : !binding ? 'inherit' : pool.status === 'configured' ? 'pool' : 'blocked',
+        ...(pool ? { poolId: pool.id, poolLabel: pool.label, poolStatus: pool.status, mode: pool.mode } : {}),
+        ...(state === 'legacy' ? { legacy: true } : {}) } };
+  });
+  return { contractVersion: 0, storage: saved ? 'ready' : 'missing', network,
+    catalog: { state, revision, ...(requirement ? { configId: requirement.configId, catalogId: requirement.catalogId } : {}) }, providers };
+}
+
+export function manageNetworkResources(options, action, input, { signal } = {}) {
+  if (!NETWORK_MANAGEMENT_ACTIONS.includes(action)) throw new TypeError('未知网络管理操作');
+  let command = action === 'init' ? 'routing.init' : action.replace('/', '.');
+  if (action === 'bindings/set') {
+    networkFields(input, ['expectedRevision', 'expectedProviderRevision', 'providerId', 'poolId'],
+      ['expectedRevision', 'expectedProviderRevision', 'providerId', 'poolId']);
+    const settings = networkManagementSettings(options);
+    if (settings.catalog.state !== 'ready') throw networkPolicyError('IRIS_NETWORK_CATALOG_REQUIRED', '绑定需要匹配的v2网络文件和供应商目录；请先按指引另存启用，不自动迁移');
+    if (input.expectedProviderRevision !== settings.catalog.revision) throw networkPolicyError('IRIS_NETWORK_PROVIDER_CHANGED', '供应商目录已变化，请重新读取后核对绑定');
+    if (!settings.providers.some(provider => provider.id === input.providerId)) throw networkPolicyError('IRIS_NETWORK_PROVIDER_NOT_FOUND', '所选供应商不在当前目录');
+    input = { expectedRevision: input.expectedRevision, catalogId: settings.catalog.catalogId, providerId: input.providerId, poolId: input.poolId };
+  }
+  const changed = executeNetworkConfigCommand(options.networkConfigPath, command, input, { signal });
+  return { contractVersion: 0, changed: changed.created === true || changed.changed === true,
+    settings: networkManagementSettings(options) };
+}

package/lib/network-policy.js

@@ -0,0 +1,19 @@
+// Nonsecret identity shared by persisted records and owned Provider assembly.
+export const CATALOG_NETWORK = Symbol('iris.catalog-network');
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+export function checkedNetworkRequirement(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+      || Object.keys(value).length !== 3 || Object.keys(value).some(key => !['schemaVersion', 'configId', 'catalogId'].includes(key))
+      || value.schemaVersion !== 1 || !UUID.test(value.configId) || !UUID.test(value.catalogId)) {
+    throw Object.assign(new Error('网络要求身份或版本无效'), { code: 'IRIS_NETWORK_REQUIREMENT_INVALID' });
+  }
+  return { schemaVersion: 1, configId: value.configId, catalogId: value.catalogId };
+}
+export function sameNetworkRequirement(a, b) {
+  return a === undefined || b === undefined ? a === b : a.schemaVersion === b.schemaVersion && a.configId === b.configId && a.catalogId === b.catalogId;
+}
+export function providerNetworkRequirement(provider) { return provider?.[CATALOG_NETWORK]; }
+export function createNetworkAttemptBudget() { return { remaining: 16, probes: new Map() }; }
+export function networkPolicyError(code, message, stage = 'validate') {
+  return Object.assign(new Error(message), { code, stage, category: 'invalid_request', acceptance: 'not_accepted' });
+}

package/lib/network-route-evidence.js

@@ -0,0 +1,38 @@
+// Nonsecret dispatch intentions. These records do not prove receipt or public IP.
+import { checkedNetworkRequirement } from './network-policy.js';
+
+export const MAX_NETWORK_ROUTE_FACTS = 128;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const ATTEMPT = /^attempt_[a-f0-9]{24}$/;
+const SHA = /^[a-f0-9]{64}$/;
+const OPERATIONS = ['discover', 'prepareInput', 'submit', 'poll', 'download', 'cancel', 'vision'];
+const FIELDS = ['schemaVersion', 'configId', 'catalogId', 'configGeneration', 'configRevision', 'providerId', 'operation', 'route', 'poolId', 'nodeId', 'attemptId'];
+const invalid = () => { throw Object.assign(new Error('网络路线事实包含无效身份、阶段或未允许字段'), { code: 'IRIS_NETWORK_ROUTE_INVALID' }); };
+
+export function checkedNetworkRouteFact(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !FIELDS.includes(key))
+      || value.schemaVersion !== 1 || !Number.isSafeInteger(value.configGeneration) || value.configGeneration < 1 || !SHA.test(value.configRevision)
+      || typeof value.providerId !== 'string' || !value.providerId || value.providerId.length > 256 || /[\x00-\x1f\x7f]/.test(value.providerId)
+      || !OPERATIONS.includes(value.operation) || !['inherit', 'direct', 'proxy'].includes(value.route)
+      || value.poolId !== undefined && !ID.test(value.poolId) || value.nodeId !== undefined && !ID.test(value.nodeId)
+      || value.attemptId !== undefined && !ATTEMPT.test(value.attemptId)
+      || value.route === 'proxy' && (!value.poolId || !value.nodeId)
+      || value.route !== 'proxy' && value.nodeId !== undefined || value.route === 'inherit' && value.poolId !== undefined) invalid();
+  try { checkedNetworkRequirement({ schemaVersion: 1, configId: value.configId, catalogId: value.catalogId }); }
+  catch (_) { invalid(); }
+  return { schemaVersion: 1, configId: value.configId, catalogId: value.catalogId,
+    configGeneration: value.configGeneration, configRevision: value.configRevision, providerId: value.providerId,
+    operation: value.operation, route: value.route,
+    ...(value.poolId !== undefined ? { poolId: value.poolId } : {}), ...(value.nodeId !== undefined ? { nodeId: value.nodeId } : {}),
+    ...(value.attemptId !== undefined ? { attemptId: value.attemptId } : {}) };
+}
+
+export const networkRouteFactKey = value => JSON.stringify(checkedNetworkRouteFact(value));
+export function checkedNetworkRouteRecord(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) invalid();
+  const { firstAt, lastAt, requestCount, phase, ...fact } = value;
+  const checked = checkedNetworkRouteFact(fact);
+  const iso = time => typeof time === 'string' && Number.isFinite(Date.parse(time)) && new Date(time).toISOString() === time;
+  if (phase !== 'dispatch_started' || !iso(firstAt) || !iso(lastAt) || lastAt < firstAt || !Number.isSafeInteger(requestCount) || requestCount < 1) invalid();
+  return { ...checked, phase, firstAt, lastAt, requestCount };
+}