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

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 };
+}

package/lib/network-routing.js

@@ -0,0 +1,283 @@
+// Instance-owned routing. CONNECT preflight never sends a business request.
+import net from 'node:net';
+import crypto from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { readNetworkConfig } from './network-config-service.js';
+import { networkNodeCredentialStatus, NETWORK_ROUTING_CONFIG_VERSION } from './network-config.js';
+import { checkedNetworkRequirement, networkPolicyError, createNetworkAttemptBudget } from './network-policy.js';
+import { createProviderNetworkClient, inheritedProviderFetch } from './provider-network.js';
+import { ProviderContractError } from './provider-contract.js';
+
+const hash = value => crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const authority = url => `${url.hostname}:${url.port || (url.protocol === 'https:' ? 443 : 80)}`;
+const nodeUri = node => `${node.protocol}://${net.isIP(node.host) === 6 ? '[' + node.host + ']' : node.host}:${node.port}`;
+const PREFLIGHT_ERRORS = new Set([
+  'ECONNREFUSED', 'ECONNRESET', 'ECONNABORTED', 'EHOSTUNREACH', 'ENETUNREACH', 'ENETDOWN', 'EAI_AGAIN', 'ENOTFOUND',
+  'ETIMEDOUT', 'EPIPE', 'EADDRNOTAVAIL', 'EACCES', 'EPERM', 'IRIS_NETWORK_CONNECT_REJECTED',
+  'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_HEADERS_OVERFLOW', 'UND_ERR_SOCKET', 'UND_ERR_ABORTED', 'UND_ERR_PRX_TLS',
+  'DEPTH_ZERO_SELF_SIGNED_CERT', 'SELF_SIGNED_CERT_IN_CHAIN', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'UNABLE_TO_GET_ISSUER_CERT', 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY', 'CERT_HAS_EXPIRED', 'CERT_NOT_YET_VALID', 'CERT_REVOKED',
+  'ERR_TLS_CERT_ALTNAME_INVALID', 'ERR_TLS_HANDSHAKE_TIMEOUT'
+]);
+const preflightUnavailable = error => PREFLIGHT_ERRORS.has(error.code) || /^(?:ERR_SSL_|HPE_)[A-Z0-9_]+$/.test(error.code || '')
+  || ['AbortError', 'TimeoutError'].includes(error.name);
+function failure(context, code, message, category = 'network') {
+  const operation = context.operation || 'submit';
+  const notAccepted = ['submit', 'prepareInput', 'discover', 'vision'].includes(operation);
+  return Object.assign(new ProviderContractError(message, { providerCode: code, category, stage: notAccepted ? 'prepare' : operation,
+    acceptance: notAccepted ? 'not_accepted' : 'accepted' }), { code });
+}
+
+async function directPreflight(url, signal, timeoutMs) {
+  signal?.throwIfAborted();
+  const combined = signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs);
+  await new Promise((resolve, reject) => {
+    const socket = net.connect({ host: url.hostname.replace(/^\[|\]$/g, ''), port: Number(url.port || (url.protocol === 'https:' ? 443 : 80)) });
+    const aborted = () => socket.destroy(combined.reason);
+    combined.addEventListener('abort', aborted, { once: true });
+    const cleanup = () => combined.removeEventListener('abort', aborted);
+    socket.once('error', error => { cleanup(); reject(error); });
+    socket.once('connect', () => { cleanup(); socket.destroy(); resolve(); });
+    if (combined.aborted) aborted();
+  });
+}
+
+function transportFetchInput(transport, input, options) {
+  // Node's built-in fetch and the installed Undici use different Web IDL brands.
+  // Convert only at the explicit transport boundary; inherited fetch stays native.
+  if (input instanceof Request) {
+    const request = new Request(input, options);
+    return { input: new transport.Request(request.url, request), options: { signal: request.signal } };
+  }
+  if (options.body instanceof FormData) {
+    const body = new transport.FormData();
+    for (const [name, value] of options.body) body.append(name, value);
+    return { input, options: { ...options, body } };
+  }
+  return { input, options };
+}
+
+export function createProviderNetworkManager({ networkConfigPath, onRoute, tls, proxyTls, scheduler, preflightTimeoutMs = 3000,
+  loadTransport = () => {
+    // Initialize Node's own fetch classes/default dispatcher without a request.
+    // Undici must inherit an existing dispatcher rather than create its own default.
+    void globalThis.Request;
+    return import('undici');
+  } } = {}) {
+  if (onRoute !== undefined && typeof onRoute !== 'function') throw new TypeError('onRoute 必须是函数');
+  if (typeof loadTransport !== 'function' || !Number.isInteger(preflightTimeoutMs) || preflightTimeoutMs < 1 || preflightTimeoutMs > 30000) throw new TypeError('网络客户端装配参数无效');
+  const clients = new Map(), retiring = new Set();
+  let closing = false, disposal, transport, revision, cleanupFailed = false;
+  function retire(client) {
+    const pending = client.dispose();
+    retiring.add(pending);
+    void pending.then(() => retiring.delete(pending), () => { cleanupFailed = true; retiring.delete(pending); });
+  }
+  function remember(slot, key, client, routed = false) {
+    const previous = clients.get(slot);
+    clients.set(slot, { key, client, routed });
+    if (previous) retire(previous.client);
+    return client;
+  }
+  const library = () => transport ||= Promise.resolve().then(loadTransport).catch(() => {
+    throw failure({ operation: 'discover' }, 'IRIS_NETWORK_CLIENT_UNAVAILABLE', '代理客户端未安装或无法加载；请使用包含所需生产依赖的完整 Iris 安装，不会退回直连', 'invalid_request');
+  });
+  async function scheduledFetch(fetch, dispatcher, input, options, context) {
+    const managed = scheduler.dispatcher(dispatcher, context, options.signal);
+    try { return await fetch(input, { ...options, dispatcher: managed }); }
+    catch (error) {
+      const queuedFailure = [error, error.cause].some(value => typeof value?.code === 'string' && value.code.startsWith('IRIS_SCHEDULER_'));
+      if (managed.dispatches === 0 && (queuedFailure || options.signal?.aborted)) {
+        const original = typeof error.cause?.code === 'string' && error.cause.code.startsWith('IRIS_SCHEDULER_') ? error.cause : error;
+        throw failure(context, typeof original.code === 'string' && original.code.startsWith('IRIS_SCHEDULER_') ? original.code : 'IRIS_SCHEDULER_ABORTED',
+          '请求在本地调度期间停止，业务请求尚未派发', options.signal?.aborted ? 'aborted' : 'rate_limit');
+      }
+      throw error;
+    }
+  }
+
+  function resolveProviderNetwork({ providerId, modelRef, networkRequirement } = {}) {
+    if (closing) throw networkPolicyError('IRIS_PROVIDER_NETWORK_CLOSED', '网络管理实例已关闭');
+    if (networkRequirement === undefined) {
+      if (!scheduler) return undefined;
+      const key = JSON.stringify(['scheduled-inherit', providerId, modelRef]);
+      if (clients.has(key)) return clients.get(key).client;
+      const scope = new AsyncLocalStorage();
+      const base = createProviderNetworkClient({ async fetchPort(input, options = {}) {
+        const context = scope.getStore();
+        if (!context) throw networkPolicyError('IRIS_NETWORK_OPERATION_REQUIRED', '调度客户端必须在完整操作内调用');
+        const { getGlobalDispatcher } = await library();
+        return scheduledFetch(inheritedProviderFetch, getGlobalDispatcher(), input, options, context);
+      } });
+      const client = Object.freeze({ ...base, run(action, context = {}) {
+        return base.run(fetch => scope.run({ providerId, modelRef, ...context }, () => action(fetch)));
+      } });
+      return remember(key, key, client);
+    }
+    const requirement = Object.freeze(checkedNetworkRequirement(networkRequirement));
+    if (typeof providerId !== 'string' || !providerId.trim() || providerId.length > 256 || /[\x00-\x1f\x7f]/.test(providerId)) throw networkPolicyError('IRIS_NETWORK_CONTEXT_REQUIRED', '网络解析需要明确的供应商身份');
+    if (!networkConfigPath) throw networkPolicyError('IRIS_NETWORK_CONTEXT_REQUIRED', '此供应商配置需要明确的 network-config，不会使用默认出口');
+    const saved = readNetworkConfig(networkConfigPath), config = saved.config;
+    if (config.schemaVersion !== NETWORK_ROUTING_CONFIG_VERSION || config.configId !== requirement.configId) {
+      throw networkPolicyError('IRIS_NETWORK_CONFIG_MISMATCH', '网络配置版本或身份与供应商目录不符，不会借用其他配置');
+    }
+    if (revision !== saved.revision) {
+      revision = saved.revision;
+      for (const [slot, entry] of clients) if (entry.routed) {
+        clients.delete(slot); retire(entry.client);
+      }
+    }
+    const binding = config.bindings.find(value => value.catalogId === requirement.catalogId && value.providerId === providerId);
+    const pool = binding ? config.pools.find(value => value.id === binding.poolId) : undefined;
+    if (binding && (!pool?.enabled || !pool.candidates.length)) throw networkPolicyError('IRIS_NETWORK_POOL_UNAVAILABLE', '显式绑定的出口池为空或已停用，不会隐式继承或直连');
+    const secrets = pool ? pool.candidates.flatMap(candidate => {
+      const node = candidate.kind === 'node' && config.nodes.find(value => value.id === candidate.nodeId);
+      return node?.auth ? [process.env[node.auth.usernameEnv], process.env[node.auth.passwordEnv]] : [];
+    }) : [];
+    const slot = hash([requirement, providerId, ...(scheduler ? [modelRef] : [])]);
+    const key = hash([saved.revision, requirement, providerId, ...(scheduler ? [modelRef] : []), secrets]);
+    const cached = clients.get(slot);
+    if (cached?.key === key) return cached.client;
+    const scope = new AsyncLocalStorage(), dispatchers = new Map();
+    // Capture only this client's explicitly referenced values; later resolutions
+    // use a new client if credentials rotate, while admitted operations can drain.
+    const nodeIds = new Set(pool?.candidates.filter(candidate => candidate.kind === 'node').map(candidate => candidate.nodeId) || []);
+    const nodes = new Map(config.nodes.filter(node => nodeIds.has(node.id)).map(node => [node.id, { ...node, credentialStatus: networkNodeCredentialStatus(node),
+      ...(node.auth ? { token: `Basic ${Buffer.from(`${process.env[node.auth.usernameEnv] || ''}:${process.env[node.auth.passwordEnv] || ''}`).toString('base64')}` } : {}) }]));
+
+    async function choose(url, options, context) {
+      if (!pool) return { route: 'inherit' };
+      const budget = context.networkBudget || createNetworkAttemptBudget();
+      for (const candidate of pool.candidates) {
+        if (options.signal?.aborted) throw failure(context, 'IRIS_NETWORK_ABORTED', '业务请求发送前已取消出口预检', 'aborted');
+        const probeKey = JSON.stringify([key, url.origin, candidate]);
+        if (budget.probes.has(probeKey)) {
+          const previous = await budget.probes.get(probeKey);
+          if (previous) return previous;
+          continue;
+        }
+        const node = candidate.kind === 'node' ? nodes.get(candidate.nodeId) : undefined;
+        if (candidate.kind === 'node' && (!node?.enabled || !['none', 'ready'].includes(node.credentialStatus))) {
+          budget.probes.set(probeKey, Promise.resolve(null)); continue;
+        }
+        if (!budget.remaining) continue;
+        budget.remaining--;
+        let complete;
+        const result = new Promise(resolve => { complete = resolve; });
+        budget.probes.set(probeKey, result);
+        try {
+          if (candidate.kind === 'direct') {
+            await directPreflight(url, options.signal, preflightTimeoutMs);
+            const selected = { route: 'direct', poolId: pool.id }; complete(selected); return selected;
+          }
+          const { Client } = await library();
+          const probe = new Client(nodeUri(node), { connect: proxyTls, connectTimeout: preflightTimeoutMs });
+          try {
+            const signal = options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(preflightTimeoutMs)]) : AbortSignal.timeout(preflightTimeoutMs);
+            const connected = await probe.connect({ path: authority(url), signal,
+              headers: { ...(node.token ? { 'proxy-authorization': node.token } : {}), host: authority(url) } });
+            connected.socket.destroy();
+            if (connected.statusCode !== 200) throw Object.assign(new Error('CONNECT rejected'), { code: 'IRIS_NETWORK_CONNECT_REJECTED' });
+          } finally { await probe.destroy(); }
+          const selected = { route: 'proxy', poolId: pool.id, nodeId: node.id }; complete(selected); return selected;
+        } catch (error) {
+          complete(null);
+          if (options.signal?.aborted) throw failure(context, 'IRIS_NETWORK_ABORTED', '业务请求发送前已取消出口预检', 'aborted');
+          if (error.code === 'IRIS_NETWORK_CLIENT_UNAVAILABLE') throw error;
+          if (!preflightUnavailable(error)) throw error;
+          // Only the independent connection preflight may select another route.
+        }
+      }
+      throw failure(context, 'IRIS_NETWORK_POOL_EXHAUSTED', '出口池没有通过连接预检的候选；未发送业务请求，也未隐式直连');
+    }
+
+    async function dispatcherFor(selected) {
+      const id = selected.nodeId || 'direct';
+      if (!dispatchers.has(id)) {
+        const pending = library().then(({ Agent, ProxyAgent }) => {
+          const node = selected.nodeId && nodes.get(selected.nodeId);
+          return node ? new ProxyAgent({ uri: nodeUri(node), token: node.token, requestTls: tls, proxyTls,
+            connectTimeout: preflightTimeoutMs, proxyTunnel: true }) : new Agent({ connect: tls, connectTimeout: preflightTimeoutMs });
+        });
+        dispatchers.set(id, pending);
+        void pending.catch(() => { if (dispatchers.get(id) === pending) dispatchers.delete(id); });
+      }
+      return dispatchers.get(id);
+    }
+
+    const base = createProviderNetworkClient({
+      async fetchPort(input, options = {}) {
+        const state = scope.getStore();
+        if (!state) throw networkPolicyError('IRIS_NETWORK_OPERATION_REQUIRED', '显式网络客户端必须在完整操作内调用');
+        if (state.context.taskId && typeof state.context.recordNetworkRoute !== 'function') {
+          throw failure(state.context, 'IRIS_NETWORK_EVIDENCE_REQUIRED', 'Task 出站需要 Core 提供路线持久化端口，已停止派发', 'local_io');
+        }
+        if (input instanceof Request && options.signal === undefined) options = { ...options, signal: input.signal };
+        const url = new URL(input instanceof Request ? input.url : input);
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw failure(state.context, 'IRIS_NETWORK_TARGET_INVALID', '出站目标需要不含认证信息的 HTTP(S) 地址', 'invalid_request');
+        state.selection ||= choose(url, options, state.context);
+        const selected = await state.selection;
+        const dispatcher = selected.route === 'inherit' ? undefined : await dispatcherFor(selected);
+        const fact = { ...requirement, configGeneration: config.generation, configRevision: saved.revision, providerId,
+          operation: state.context.operation || 'discover', ...selected, ...(state.context.attemptId ? { attemptId: state.context.attemptId } : {}) };
+        if (state.context.recordNetworkRoute) {
+          try { await state.context.recordNetworkRoute(fact); }
+          catch (error) {
+            throw failure(state.context, /^IRIS_(?:TASK|NETWORK)_/.test(error.code || '') ? error.code : 'IRIS_NETWORK_ROUTE_WRITE_FAILED',
+              error.code === 'IRIS_NETWORK_ROUTE_LIMIT' ? '原 Task 的路线事实已达限额，已停止派发并保留历史'
+                : '路线事实未能持久化，已停止出站；请检查存储和原 Task 身份', 'local_io');
+          }
+        }
+        if (onRoute) {
+          try { await onRoute(fact, state.context); }
+          catch (error) {
+            if (!/^IRIS_(?:TASK|NETWORK)_/.test(error.code || '')) throw error;
+            throw failure(state.context, error.code, error.code === 'IRIS_NETWORK_ROUTE_LIMIT'
+              ? '原 Task 的路线事实已达限额，已停止派发并保留历史'
+              : '路线事实未能持久化，已停止出站；请检查存储和原 Task 身份', 'local_io');
+          }
+        }
+        // Once business dispatch starts, errors remain conservatively ambiguous.
+        // Neither the next proxy nor a direct connection may replay this request.
+        try {
+          if (!dispatcher) {
+            if (!scheduler) return await inheritedProviderFetch(input, options);
+            const { getGlobalDispatcher } = await library();
+            return await scheduledFetch(inheritedProviderFetch, getGlobalDispatcher(), input, options, { providerId, modelRef, ...state.context });
+          }
+          const transport = await library(), request = transportFetchInput(transport, input, options);
+          if (scheduler) return await scheduledFetch(transport.fetch, dispatcher, request.input, request.options, { providerId, modelRef, ...state.context });
+          return await transport.fetch(request.input, { ...request.options, dispatcher });
+        } catch (error) {
+          if (typeof error.code === 'string' && error.code.startsWith('IRIS_SCHEDULER_')) throw error;
+          if (options.signal?.aborted) throw options.signal.reason;
+          throw Object.assign(new TypeError('出站请求失败；出口已选定，未自动重放请求'), { code: 'IRIS_NETWORK_TRANSPORT', cause: error });
+        }
+      },
+      async close() {
+        const results = await Promise.allSettled([...dispatchers.values()].map(async value => (await value).close()));
+        if (results.some(value => value.status === 'rejected')) throw new Error('部分网络连接未能正常释放');
+      }
+    });
+    const client = Object.freeze({ ...base, networkRequirement: requirement, providerId, ...(pool ? { poolId: pool.id } : {}),
+      run(action, context = {}) {
+        return base.run(fetch => scope.run({ context, selection: null }, () => action(fetch)));
+      } });
+    return remember(slot, key, client, true);
+  }
+
+  function dispose() {
+    if (!disposal) {
+      closing = true;
+      disposal = (async () => {
+        const results = await Promise.allSettled([
+          ...[...clients.values()].map(entry => entry.client.dispose()), ...retiring
+        ]);
+        clients.clear();
+        if (cleanupFailed || results.some(value => value.status === 'rejected')) throw new Error('网络管理实例释放失败');
+      })();
+    }
+    return disposal;
+  }
+  return Object.freeze({ resolveProviderNetwork, dispose, scheduler });
+}