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

package/lib/provider-config-format.js

@@ -0,0 +1,51 @@
+// Network-enabled catalogs use an outer envelope which older loaders reject.
+import { CATALOG_NETWORK, checkedNetworkRequirement, sameNetworkRequirement } from './network-policy.js';
+
+const fail = message => { throw Object.assign(new Error(message), { code: 'IRIS_PROVIDER_CONFIG_INVALID' }); };
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function markedCatalog(catalog, requirement) {
+  if (!object(catalog) || !Array.isArray(catalog.providers) || catalog.providers.some(provider => !object(provider))) {
+    fail('Provider 配置内容无效');
+  }
+  const ids = new Set();
+  for (const provider of catalog.providers) {
+    if (typeof provider.id !== 'string' || !provider.id.trim() || provider.id.length > 256 || /[\x00-\x1f\x7f]/.test(provider.id) || ids.has(provider.id)) fail('网络目录需要明确、唯一且不含控制字符的供应商身份');
+    ids.add(provider.id);
+  }
+  const identity = Object.freeze(checkedNetworkRequirement(requirement));
+  return { ...catalog, [CATALOG_NETWORK]: identity,
+    providers: catalog.providers.map(provider => ({ ...provider, [CATALOG_NETWORK]: identity })) };
+}
+
+export function decodeProviderConfig(parsed) {
+  if (object(parsed) && Object.hasOwn(parsed, 'providers') && Object.hasOwn(parsed, 'networkRequirement')) fail('网络目录不能与旧根 providers 字段混用，拒绝忽略网络要求');
+  if (!object(parsed) || Object.hasOwn(parsed, 'providers')) return parsed;
+  if (parsed.schemaVersion !== 1 || Object.keys(parsed).length !== 3
+      || !Object.hasOwn(parsed, 'networkRequirement') || !Object.hasOwn(parsed, 'catalog')) {
+    fail('Provider 网络配置包装版本或字段无效；请使用兼容版本，原文件不会自动迁移');
+  }
+  return markedCatalog(parsed.catalog, parsed.networkRequirement);
+}
+
+export function encodeProviderConfig(catalog) {
+  const requirement = catalog?.[CATALOG_NETWORK];
+  if (requirement === undefined) {
+    if (catalog?.providers?.some(provider => provider?.[CATALOG_NETWORK] !== undefined)) fail('Provider 网络配置身份丢失，拒绝写回旧格式');
+    return catalog;
+  }
+  const checked = checkedNetworkRequirement(requirement);
+  for (const provider of catalog.providers) {
+    const identity = provider?.[CATALOG_NETWORK];
+    if (identity !== undefined && !sameNetworkRequirement(checked, identity)) fail('Provider 与目录的网络配置身份不一致');
+  }
+  const { [CATALOG_NETWORK]: _identity, ...contents } = catalog;
+  return { schemaVersion: 1, networkRequirement: checked, catalog: contents };
+}
+
+/** Return a new marked runtime catalog; callers explicitly write a new file. */
+export function wrapProviderCatalog(catalog, requirement) {
+  const original = encodeProviderConfig(catalog);
+  const contents = catalog?.[CATALOG_NETWORK] === undefined ? original : original.catalog;
+  return markedCatalog(JSON.parse(JSON.stringify(contents)), requirement);
+}

package/lib/provider-config-service.js

@@ -16,15 +16,18 @@ import { refreshModelDirectory } from './model-directory-service.js';
 import { projectProviderSettings, applyProviderSettings, applyFunctionPolicies } from './provider-settings.js';
 import { checkedComfyWorkflow, compileComfyWorkflow, projectComfyWorkflow } from './comfyui-workflow.js';
 import { createComfyUiClient } from './comfyui-client.js';
+import { applyCredentialPatch, assertProviderCredential, resolveProviderCredential, createProviderSecretScrubber } from './provider-credentials.js';
 import { inspectComfyWorkflow } from './comfyui-inspection.js';
+import { encodeProviderConfig } from './provider-config-format.js';
+import { providerNetworkRequirement, sameNetworkRequirement, networkPolicyError } from './network-policy.js';
 
 const fail = message => { throw Object.assign(new Error(message), { code: 'IRIS_CONFIG_INPUT_INVALID' }); };
 const hash = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
 // Owner edits change configuration, while task health and directory caches can
 // advance independently. Saves still load fresh records and use a byte CAS under
 // the file lock, preserving the latest runtime evidence.
-function settingsRevision(catalog) {
-  return hash(JSON.stringify({ ...catalog, providers: catalog.providers.map(({ health, modelDirectory, ...provider }) => provider) }));
+export function settingsRevision(catalog) {
+  return hash(JSON.stringify(encodeProviderConfig({ ...catalog, providers: catalog.providers.map(({ health, modelDirectory, ...provider }) => provider) })));
 }
 const safe = value => redactProviderMessage(String(value || '').replace(/https?:\/\/[^\s<>"']+/gi, '[URL]'));
 const text = value => { if (typeof value !== 'string' || !value.trim()) fail('ID 必须是非空字符串'); return value.trim(); };
@@ -34,18 +37,20 @@ const caps = value => {
 };
 
 function assignmentSnapshot(catalog) {
+  const scrub = createProviderSecretScrubber(catalog.providers), label = value => safe(scrub(value));
   const pool = modelPool(catalog.providers, { includeHostVision: true });
   return Object.fromEntries(Object.entries(catalog.assignments || {}).map(([capability, value]) => {
     const policy = functionPolicy(value, capability);
     const refs = policy.models.map(ref => resolvePoolModel(pool, ref, capability));
-    return [safe(capability), { mode: policy.mode, hostVision: policy.hostVision,
-      model_refs: refs.filter(Boolean).map(model => safe(model.ref)), invalidRefs: refs.filter(ref => !ref).length }];
+    return [label(capability), { mode: policy.mode, hostVision: policy.hostVision,
+      model_refs: refs.filter(Boolean).map(model => label(model.ref)), invalidRefs: refs.filter(ref => !ref).length }];
   }));
 }
 
 export function configSnapshot(catalog, registry) {
-  return { ...providerCatalogSnapshot(catalog), models: catalog.providers.flatMap(provider => providerModels(provider).map(model => ({
-    ref: safe(model.ref), providerId: safe(provider.id), id: safe(model.id), capabilities: model.capabilities,
+  const scrub = createProviderSecretScrubber(catalog.providers), label = value => safe(scrub(value));
+  return scrub({ ...providerCatalogSnapshot(catalog), models: catalog.providers.flatMap(provider => providerModels(provider).map(model => ({
+    ref: label(model.ref), providerId: label(provider.id), id: label(model.id), capabilities: model.capabilities,
     ...(model.catalogStatus ? { catalogStatus: model.catalogStatus } : {}),
     ...(model.unavailableCapabilities ? { unavailableCapabilities: model.unavailableCapabilities } : {}),
     ...(model.imageProtocol !== undefined ? { imageProtocol: model.imageProtocol } : {}),
@@ -55,14 +60,28 @@ export function configSnapshot(catalog, registry) {
       comfyWorkflow: projectComfyWorkflow(provider.models.find(entry => entry?.id === model.id).comfyWorkflow) } : {}),
     ...(model.capabilities.includes('vision') ? { visionInputEffective: visionInputLimits(provider, model.id) } : {}),
     ...(model.capabilities.includes('image-gen') ? { imageRouting: selectImageProtocol(provider, model.id, registry) } : {}),
-    verified: Object.fromEntries(Object.entries(model.verified || {}).map(([capability, value]) => [capability, { ok: value.ok === true, at: safe(value.at), category: safe(value.category) }])),
+    verified: Object.fromEntries(Object.entries(model.verified || {}).map(([capability, value]) => [capability, { ok: value.ok === true, at: label(value.at), category: label(value.category) }])),
     ...(model.rateLimited ? { rateLimited: true, rateLimitedAt: modelRateLimit(provider, model.id).at,
       ...(modelRateLimit(provider, model.id).until ? { retryAt: modelRateLimit(provider, model.id).until }
         : { reason: modelRateLimit(provider, model.id).reason }) } : {})
-  }))), assignments: assignmentSnapshot(catalog), routing: catalogCapabilitySnapshot(catalog, registry) };
+  }))), assignments: assignmentSnapshot(catalog), routing: catalogCapabilitySnapshot(catalog, registry) });
 }
 
-export async function executeConfigCommand(configPath, command, input = {}, { signal, probe, registry } = {}) {
+export async function executeConfigCommand(configPath, command, input = {}, { signal, probe, registry, resolveProviderNetwork } = {}) {
+  if (resolveProviderNetwork !== undefined && typeof resolveProviderNetwork !== 'function') throw new TypeError('resolveProviderNetwork 必须是函数');
+  const networkFor = (provider, modelRef) => {
+    const requirement = providerNetworkRequirement(provider);
+    const network = resolveProviderNetwork?.({ providerId: provider.id, modelRef, provider, networkRequirement: requirement });
+    if (requirement && (!network || !sameNetworkRequirement(requirement, network.networkRequirement) || network.providerId !== provider.id)) throw networkPolicyError('IRIS_NETWORK_CONTEXT_REQUIRED', '此目录需要匹配的显式网络配置，未装配的检查不会默认直连');
+    return network;
+  };
+  const adapterFor = provider => {
+    const network = networkFor(provider);
+    return createConfiguredProviderAdapter(provider, { registry, ...(network !== undefined ? { network } : {}) });
+  };
+  const assertRemovable = provider => {
+    if (providerNetworkRequirement(provider) && networkFor(provider)?.poolId !== undefined) throw networkPolicyError('IRIS_NETWORK_CONFIG_IN_USE', '此供应商仍有出口绑定；请先明确解除绑定，再删除连接');
+  };
   if (command === 'init') {
     if (!path.isAbsolute(configPath)) fail('provider-config 必须是绝对路径');
     ensurePrivateDir(path.dirname(configPath));
@@ -71,7 +90,7 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
   }
   const catalog = loadProviderCatalog(configPath);
   const before = fs.readFileSync(configPath);
-  if (JSON.stringify(JSON.parse(before)) !== JSON.stringify(catalog)) throw Object.assign(new Error('配置在读取期间发生变化，请重试'), { code: 'IRIS_CONFIG_CHANGED' });
+  if (JSON.stringify(JSON.parse(before)) !== JSON.stringify(encodeProviderConfig(catalog))) throw Object.assign(new Error('配置在读取期间发生变化，请重试'), { code: 'IRIS_CONFIG_CHANGED' });
   if (command === 'settings.show') return projectProviderSettings(catalog, settingsRevision(catalog), registry);
   if (['settings.policies', 'settings.enabled', 'settings.remove'].includes(command)) {
     const fields = command === 'settings.policies' ? ['expectedRevision', 'assignments'] : command === 'settings.enabled'
@@ -88,6 +107,7 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
         matches[0].enabled = input.enabled;
       } else {
         if (input.confirm !== true) fail('请明确确认删除此供应商');
+        assertRemovable(matches[0]);
         const pool = modelPool(catalog.providers, { includeHostVision: true });
         for (const [cap, assignment] of Object.entries(catalog.assignments || {})) {
           const policy = functionPolicy(assignment, cap);
@@ -109,15 +129,18 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
     const ref = draft ? null : parseModelRef(settings ? input.modelRef : input.model_ref);
     if (draft ? typeof input.providerId !== 'string' || input.modelRef !== undefined : !ref || input.providerId !== undefined) fail('需要明确的模型，或已保存连接与工作流草稿');
     const matches = catalog.providers.filter(provider => provider.id === (draft ? input.providerId : ref.providerId));
+    if (matches.length === 1 && matches[0].enabled !== false) assertProviderCredential(matches[0]);
     if (matches.length !== 1 || !isConfiguredProvider(matches[0]) || !draft && !matches[0].models?.some(model => model.id === ref.modelId)) fail('请先配置并启用明确的工作流连接');
-    const provider = draft ? { ...matches[0], comfyWorkflow: checkedComfyWorkflow(input.comfyWorkflow) } : providerForImageModel(matches[0], ref.modelId, registry);
+    const provider = resolveProviderCredential(draft ? { ...matches[0], comfyWorkflow: checkedComfyWorkflow(input.comfyWorkflow) } : providerForImageModel(matches[0], ref.modelId, registry));
+    const scrub = createProviderSecretScrubber([matches[0], provider]);
     if (provider.mediaProtocol !== 'comfyui') fail('此检查仅用于 ComfyUI 工作流');
     const workflow = compileComfyWorkflow(provider.comfyWorkflow, { workflow_parameters: settings ? input.workflowParameters : input.workflow_parameters });
-    const report = await inspectComfyWorkflow(createComfyUiClient(provider), workflow, { signal });
+    const network = networkFor(provider, settings ? input.modelRef : input.model_ref);
+    const inspect = () => inspectComfyWorkflow(createComfyUiClient(provider, network ? { fetchPort: network.fetch, network } : {}), workflow, { signal });
+    const report = await (network ? network.run(inspect, { operation: 'discover' }) : inspect());
     signal?.throwIfAborted();
     if (settingsRevision(loadProviderCatalog(configPath)) !== settingsRevision(catalog)) throw Object.assign(new Error('检查期间配置已变化，请重新检查'), { code: 'IRIS_CONFIG_CHANGED' });
-    const key = providerApiKey(provider);
-    return { ...JSON.parse(key ? JSON.stringify(report).split(key).join('[redacted]') : JSON.stringify(report)), revision: settingsRevision(catalog) };
+    return { ...scrub(report), revision: settingsRevision(catalog) };
   }
   if (command === 'settings.save' || command === 'settings.discover') {
     if (!input || typeof input.expectedRevision !== 'string' || input.expectedRevision !== settingsRevision(catalog)) {
@@ -126,12 +149,14 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
     if (command === 'settings.discover') {
       if (Object.keys(input).some(key => !['expectedRevision', 'providerId'].includes(key))) fail('目录请求包含不支持的字段');
       const found = catalog.providers.filter(item => item.id === input.providerId);
+      if (found.length === 1 && found[0].enabled !== false) assertProviderCredential(found[0]);
       if (found.length !== 1 || !isConfiguredProvider(found[0])) fail('请先保存并启用有认证配置的连接');
-      const discovered = await invokeProviderOperation(createConfiguredProviderAdapter(found[0], { registry }), 'discover', { signal, timeoutMs: 10000 });
+      const runtimeProvider = resolveProviderCredential(found[0]);
+      const discovered = await invokeProviderOperation(adapterFor(runtimeProvider), 'discover', { signal, timeoutMs: 10000 });
       signal?.throwIfAborted();
       if (settingsRevision(loadProviderCatalog(configPath)) !== settingsRevision(catalog)) throw Object.assign(new Error('目录读取期间配置已变化'), { code: 'IRIS_CONFIG_CHANGED' });
       return { contractVersion: 0, revision: settingsRevision(catalog), models: discovered.models.slice(0, 256).map(model => ({
-        id: safe(text(typeof model === 'string' ? model : model.id)).split(found[0].apiKey || '\u0000').join('[redacted]'), capabilities: capabilitiesOfDiscoveredModel(model)
+        id: safe(text(typeof model === 'string' ? model : model.id).split(providerApiKey(runtimeProvider) || '\u0000').join('[redacted]')), capabilities: capabilitiesOfDiscoveredModel(model)
       })), truncated: discovered.models.length > 256, persisted: false };
     }
     applyProviderSettings(catalog, input, registry);
@@ -164,7 +189,9 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
     return { valid: issues.length === 0, issues: [...new Set(issues)] };
   }
   if (command === 'models.list') return { models: configSnapshot(catalog, registry).models };
-  if (command === 'assignments.list') return { ...catalogCapabilitySnapshot(catalog, registry), assignments: assignmentSnapshot(catalog) };
+  if (command === 'assignments.list') return createProviderSecretScrubber(catalog.providers)({
+    ...catalogCapabilitySnapshot(catalog, registry), assignments: assignmentSnapshot(catalog)
+  });
   let result = { command, changed: true };
   const initialPool = modelPool(catalog.providers);
   let provider;
@@ -179,7 +206,7 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
     if (!value || typeof value !== 'object' || Array.isArray(value)) fail('需要 provider 对象');
     const id = text(value.id);
     if (command === 'providers.add' ? Boolean(provider) : !provider) fail(command === 'providers.add' ? 'Provider 已存在' : 'Provider 不存在');
-    const updated = { ...(provider || {}), ...value, id };
+    const updated = applyCredentialPatch(provider, { ...value, id });
     if (updated.visionInput !== undefined) updated.visionInput = normalizeVisionInputLimits(updated.visionInput) || null;
     let url;
     try { url = new URL(updated.baseUrl); } catch (_) { fail('baseUrl 必须是 HTTP(S) 地址'); }
@@ -211,6 +238,7 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
     else catalog.providers.push(updated);
   } else if (command === 'providers.remove') {
     if (!provider) fail('Provider 不存在');
+    assertRemovable(provider);
     catalog.providers.splice(catalog.providers.indexOf(provider), 1);
   } else if (command.startsWith('models.')) {
     if (!provider) fail('Provider 不存在');
@@ -220,7 +248,7 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
       : providerModels(provider).map(({ id, capabilities }) => ({ id, capabilities }));
     let entry = entries.find(model => model.id === modelId);
     if (command === 'models.discover') {
-      const discovered = await invokeProviderOperation(createConfiguredProviderAdapter(provider, { registry }), 'discover', { signal, timeoutMs: 15000 });
+      const discovered = await invokeProviderOperation(adapterFor(provider), 'discover', { signal, timeoutMs: 15000 });
       const models = discovered.models.map(model => ({ id: text(typeof model === 'string' ? model : model.id), capabilities: capabilitiesOfDiscoveredModel(model), source: 'discovered' }));
       result = { command, changed: input.apply === true, total: models.length, mediaCount: models.filter(model => model.capabilities.length).length, models: models.map(model => ({ ...model, id: safe(model.id) })) };
       if (input.apply !== true) return result;
@@ -363,11 +391,13 @@ export function recordCatalogAvailability(configPath, { providerId, modelId, cap
 }
 
 /** 新的自动请求按需读取目录；只读CLI命令与手选/停用不走这里。 */
-export async function refreshCatalogDirectories(configPath, catalog, capability, { signal, registry } = {}) {
+export async function refreshCatalogDirectories(configPath, catalog, capability, { signal, registry, resolveProviderNetwork } = {}) {
+  if (resolveProviderNetwork !== undefined && typeof resolveProviderNetwork !== 'function') throw new TypeError('resolveProviderNetwork 必须是函数');
   if (functionPolicy(catalog.assignments?.[capability], capability).mode !== 'auto') return [];
   return Promise.all(catalog.providers.filter(provider => isConfiguredProvider(provider)
     && providerModels(provider).some(model => model.capabilities.includes(capability))).map(provider =>
-    refreshModelDirectory(provider, { signal, registry, save: directory => {
+    refreshModelDirectory(provider, { signal, registry,
+      ...(resolveProviderNetwork ? { network: resolveProviderNetwork({ providerId: provider.id, provider, networkRequirement: providerNetworkRequirement(provider) }) } : {}), save: directory => {
       const fresh = loadProviderCatalog(configPath);
       const before = fs.readFileSync(configPath);
       const current = fresh.providers.find(item => item.id === provider.id);
@@ -392,7 +422,7 @@ function writeConfigChange(configPath, catalog, before, result, { backup = true
       fs.writeFileSync(backupPath, before, { flag: 'wx', mode: 0o600 });
       result.backupPath = backupPath;
     }
-    atomicWritePrivate(configPath, JSON.stringify(catalog, null, 2) + '\n');
+    atomicWritePrivate(configPath, JSON.stringify(encodeProviderConfig(catalog), null, 2) + '\n');
     return result;
   } finally { fs.closeSync(fd); fs.unlinkSync(lock); }
 }

package/lib/provider-context.d.ts

@@ -0,0 +1,90 @@
+/** Provider author boundary v1; independent from Plugin/Adapter v0 and persistent Task formats. */
+export const PROVIDER_FACTORY_CONTEXT_VERSION: 1;
+export type ProviderCapability = 'image' | 'video' | 'tts' | 'music' | 'transcribe';
+export type ProviderMethod = 'discover' | 'submit' | 'poll' | 'cancel' | 'download' | 'mapError';
+export type ProviderAcceptance = 'not_accepted' | 'accepted' | 'unknown';
+export type ProviderStage = 'validate' | 'prepare' | 'upload' | 'submit' | 'response' | 'poll' | 'cancel' | 'download' | 'persist' | 'emit';
+export type ProviderErrorCategory = 'invalid_request' | 'authentication' | 'quota' | 'rate_limit' | 'network' | 'timeout' | 'aborted' | 'provider' | 'protocol' | 'local_io' | 'unknown';
+export interface ProviderErrorRecord {
+  readonly stage: ProviderStage;
+  readonly category: ProviderErrorCategory;
+  readonly acceptance: ProviderAcceptance;
+  readonly retryable: boolean;
+  readonly safeMessage: string;
+  readonly httpStatus?: number;
+  readonly providerCode?: string;
+}
+export interface ProviderNetwork {
+  /** Borrowed Core port: only inside an awaited lifecycle method, including all body reads and child requests. */
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+export interface ProviderFactoryContext {
+  readonly contractVersion: 1;
+  readonly network: Readonly<ProviderNetwork>;
+  /** Selected raw model ID when Core is resolving an existing Task. */
+  readonly modelId?: string;
+}
+export interface ProviderConnection {
+  readonly id: string;
+  readonly baseUrl?: string;
+  readonly mediaBaseUrl?: string;
+  /** Runtime value resolved by Core. Never persist the connection or read another credential source. */
+  readonly apiKey?: string;
+  readonly auth?: string;
+  readonly [field: string]: unknown;
+}
+export interface ProviderOperationContext {
+  readonly signal?: AbortSignal;
+  readonly taskId?: string;
+  readonly attemptId?: string;
+  readonly modelRef?: string;
+  readonly providerId?: string;
+  readonly attempt?: Readonly<{ id: string; ordinal: number; providerId: string; model: string }>;
+}
+export interface ProviderImageInput { readonly bytes: Uint8Array; readonly mediaType: string; }
+export interface ProviderSubmitRequest {
+  readonly capability: ProviderCapability;
+  /** Raw supplier model ID, never providerId::modelId. */
+  readonly model: string;
+  readonly input: Readonly<Record<string, unknown> & { image?: ProviderImageInput }>;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}
+export type ProviderArtifact = Readonly<{ kind: 'remote-url'; url: string; mediaType?: string }>
+  | Readonly<{ kind: 'inline-base64'; data: string; mediaType?: string }>;
+export type ProviderSubmissionResult = Readonly<{ kind: 'accepted'; remoteTaskId: string }>
+  | Readonly<{ kind: 'completed'; artifacts: readonly ProviderArtifact[]; value?: unknown }>
+  | Readonly<{ kind: 'not_accepted' | 'acceptance_unknown'; error: Error | Partial<ProviderErrorRecord> }>;
+export interface ProviderRemoteRequest {
+  readonly capability: ProviderCapability;
+  readonly remoteTaskId: string;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}
+export type ProviderPollResult = Readonly<{ kind: 'pending'; progress?: string }>
+  | Readonly<{ kind: 'succeeded'; artifacts: readonly ProviderArtifact[]; value?: unknown }>
+  | Readonly<{ kind: 'failed' | 'canceled' | 'unknown'; error?: Error | Partial<ProviderErrorRecord>; message?: string }>;
+export type ProviderCancelResult = Readonly<{ kind: 'canceled' }>
+  | Readonly<{ kind: 'not_supported'; reason?: string }>
+  | Readonly<{ kind: 'unknown'; error?: Error | Partial<ProviderErrorRecord>; message?: string }>;
+export interface ProviderDownloadRequest {
+  readonly capability: ProviderCapability;
+  readonly artifact: ProviderArtifact;
+  /** Core-owned staging path; write only this new file, never Core metadata or another root. */
+  readonly targetPath: string;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}
+export interface ProviderDiscoveryRequest { readonly signal?: AbortSignal; readonly timeoutMs?: number; }
+export interface ProviderDiscoveryResult {
+  readonly models: readonly (string | Readonly<{ id: string; capabilities?: readonly string[] }>)[];
+}
+export interface ProviderOperations {
+  submit(request: ProviderSubmitRequest, context: ProviderOperationContext): ProviderSubmissionResult | Promise<ProviderSubmissionResult>;
+  /** Synchronous. The any input retains v0 identity mappers; returned records are normalized by Core. */
+  mapError(error: any, context: Partial<ProviderErrorRecord>): Error | Partial<ProviderErrorRecord> | undefined;
+  discover?(request: ProviderDiscoveryRequest, context: ProviderOperationContext): ProviderDiscoveryResult | Promise<ProviderDiscoveryResult>;
+  poll?(request: ProviderRemoteRequest, context: ProviderOperationContext): ProviderPollResult | Promise<ProviderPollResult>;
+  cancel?(request: ProviderRemoteRequest, context: ProviderOperationContext): ProviderCancelResult | Promise<ProviderCancelResult>;
+  download?(request: ProviderDownloadRequest, context: ProviderOperationContext): Readonly<{ bytes: number }> | Promise<Readonly<{ bytes: number }>>;
+}

package/lib/provider-context.js

@@ -0,0 +1,42 @@
+// Public author context, backed by Core-owned clients. No proxy/resource-management ports.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { ProviderContractError } from './provider-contract.js';
+import { assertProviderNetwork } from './provider-network.js';
+import { providerNetworkRequirement, sameNetworkRequirement, networkPolicyError } from './network-policy.js';
+import { modelRef } from './models.js';
+
+export const PROVIDER_FACTORY_CONTEXT_VERSION = 1;
+const managed = new WeakSet();
+export function markProviderContextAdapter(adapter) { managed.add(adapter); return adapter; }
+export function hasProviderContext(adapter) { return managed.has(adapter); }
+
+/** Only the registry creates a context; callers borrow fetch for one awaited lifecycle method. */
+export function createProviderContext(provider, options, inheritedNetwork) {
+  if (options?.modelId !== undefined && typeof options.modelId !== 'string') throw new TypeError('Provider modelId 必须是字符串');
+  const requirement = providerNetworkRequirement(provider);
+  if (requirement && (!options?.network || !sameNetworkRequirement(requirement, options.network.networkRequirement)
+      || options.network.providerId !== provider.id)) {
+    throw networkPolicyError('IRIS_NETWORK_CONTEXT_REQUIRED', '统一 Provider 需要原配置匹配的网络上下文，不会借用默认出口');
+  }
+  const network = assertProviderNetwork(options?.network === undefined ? inheritedNetwork() : options.network), scope = new AsyncLocalStorage();
+  const fetch = (...args) => {
+    if (!scope.getStore()?.active) {
+      throw Object.assign(new ProviderContractError('Provider 网络端口只可在当前完整生命周期方法内使用；请等待正文和子请求完成', {
+        stage: 'prepare', category: 'invalid_request', acceptance: 'not_accepted', providerCode: 'IRIS_PROVIDER_CONTEXT_OPERATION_REQUIRED'
+      }), { code: 'IRIS_PROVIDER_CONTEXT_OPERATION_REQUIRED' });
+    }
+    return network.fetch(...args);
+  };
+  const context = Object.freeze({ contractVersion: PROVIDER_FACTORY_CONTEXT_VERSION, network: Object.freeze({ fetch }),
+    ...(options?.modelId !== undefined ? { modelId: options.modelId } : {}) });
+  function invoke(name, action, args) {
+    const request = args[0], operation = { ...args[1], providerId: provider.id, operation: name };
+    if (!operation.modelRef && typeof request?.model === 'string') operation.modelRef = modelRef(provider.id, request.model);
+    return network.run(() => scope.run({ active: true }, async () => {
+      const current = scope.getStore();
+      try { return await action(...args); }
+      finally { current.active = false; }
+    }), operation);
+  }
+  return { context, invoke };
+}

package/lib/provider-credentials.js

@@ -0,0 +1,97 @@
+// Explicit process-environment references. Never mutate/persist resolved providers.
+import { ProviderContractError } from './provider-contract.js';
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const fail = (code, message) => { throw Object.assign(new Error(message), { code }); };
+
+function validateEnvironmentCredential(provider) {
+  if (provider?.apiKeyEnv === undefined) return;
+  if (typeof provider.apiKeyEnv !== 'string' || !ENV_NAME.test(provider.apiKeyEnv)) {
+    fail('IRIS_CONFIG_INPUT_INVALID', 'apiKeyEnv 必须是最多128字符的环境变量名');
+  }
+  if (provider.apiKey !== undefined || provider.dshProvider !== undefined) {
+    fail('IRIS_CONFIG_INPUT_INVALID', '环境凭据引用不能与内联密钥或 DSH 连接引用同时保存');
+  }
+}
+
+/** Persistent sources remain exclusive; Host-resolved copies never pass this storage boundary. */
+export function validateProviderCredential(provider) {
+  for (const field of ['baseUrl', 'mediaBaseUrl', 'apiKey']) {
+    if (provider?.[field] !== undefined && typeof provider[field] !== 'string') {
+      fail('IRIS_CONFIG_INPUT_INVALID', field + ' 必须是字符串');
+    }
+  }
+  validateEnvironmentCredential(provider);
+  if (provider?.dshProvider !== undefined
+      && (['apiKey', 'apiKeyEnv', 'baseUrl'].some(field => provider[field] !== undefined)
+        || provider.mediaBaseUrl !== undefined && provider.mediaBaseUrl !== '')) {
+    fail('IRIS_CONFIG_INPUT_INVALID', 'DSH 连接引用不能同时保存内联密钥、环境引用或手动 Base URL（含媒体地址）；请新建手动供应商');
+  }
+}
+
+export function providerCredentialStatus(provider) {
+  if (provider?.apiKeyEnv === undefined) return typeof provider?.apiKey === 'string' && provider.apiKey.trim() ? 'ready' : 'missing';
+  const value = process.env[provider.apiKeyEnv];
+  if (typeof value !== 'string' || !value.trim()) return 'missing';
+  return value.length > 8192 || /[^\x20-\x7e]/.test(value) ? 'invalid' : 'ready';
+}
+
+/** Non-throwing for status/cache projections. Network boundaries assert readiness. */
+export function providerCredentialValue(provider) {
+  if (provider?.apiKeyEnv === undefined) return String(provider?.apiKey || '');
+  return providerCredentialStatus(provider) === 'ready' ? process.env[provider.apiKeyEnv].trim() : '';
+}
+
+export function assertProviderCredential(provider) {
+  // Runtime inputs may be ephemeral DSH copies with a resolved URL/key; stored sources were checked on read/write.
+  validateEnvironmentCredential(provider);
+  if (provider?.apiKeyEnv !== undefined && provider.auth !== 'none' && providerCredentialStatus(provider) !== 'ready') {
+    fail('IRIS_PROVIDER_CREDENTIAL_UNAVAILABLE', '环境凭据未就绪：请检查 Core 进程中的指定变量，值须为非空、最多8192字符的可打印 ASCII 文本');
+  }
+}
+
+/** An explicit source edit replaces the previous source, never two at once. */
+export function applyCredentialPatch(previous, patch) {
+  const next = { ...previous, ...patch };
+  if (Object.hasOwn(patch, 'apiKeyEnv') && !Object.hasOwn(patch, 'apiKey')) delete next.apiKey;
+  if (Object.hasOwn(patch, 'apiKey') && !Object.hasOwn(patch, 'apiKeyEnv')) delete next.apiKeyEnv;
+  validateProviderCredential(next);
+  return next;
+}
+
+/** Legacy/custom transports receive one call's key through their existing API. */
+export function resolveProviderCredential(provider) {
+  assertProviderCredential(provider);
+  if (provider.apiKeyEnv === undefined) return provider;
+  const { apiKeyEnv, ...runtime } = provider;
+  return { ...runtime, apiKey: provider.auth === 'none' ? '' : providerCredentialValue(provider) };
+}
+
+/** Capture explicitly configured sources once, including retained auth:none keys. */
+export function createProviderSecretScrubber(providers) {
+  const keys = providers.flatMap(provider => {
+    const raw = provider.apiKeyEnv === undefined ? provider.apiKey : process.env[provider.apiKeyEnv];
+    return typeof raw === 'string' && raw ? [...new Set([raw, raw.trim()].filter(Boolean))] : [];
+  }).sort((a, b) => b.length - a.length);
+  const scrub = item => typeof item === 'string' ? keys.reduce((text, key) => text.split(key).join('[redacted]'), item)
+    : Array.isArray(item) ? item.map(scrub) : item && typeof item === 'object'
+      ? Object.fromEntries(Object.entries(item).map(([key, entry]) => [scrub(key), scrub(entry)])) : item;
+  return scrub;
+}
+
+export function scrubProviderSecrets(value, providers) {
+  return createProviderSecretScrubber(providers)(value);
+}
+
+/** Discovery metadata is untrusted; never turn an echoed key into a model ID. */
+export function assertDiscoveryCredentials(value, key) {
+  const models = Array.isArray(value) ? value : value?.models;
+  if (!key || !Array.isArray(models)) return;
+  if (models.some(model => {
+    const id = String(typeof model === 'string' ? model : model?.id || '').trim();
+    return id.includes(key);
+  })) {
+    throw new ProviderContractError('模型目录包含认证内容，已拒绝读取与保存；请检查上游服务', {
+      stage: 'response', category: 'protocol', acceptance: 'not_accepted', providerCode: 'IRIS_PROVIDER_DIRECTORY_CREDENTIALS'
+    });
+  }
+}

package/lib/provider-diagnostics.js

@@ -4,6 +4,7 @@ import { isConfiguredProvider, supportsModelCapability } from './provider-protoc
 import { healthObservationState, newestHealthEvidence, modelRateLimit } from './provider-health.js';
 import { listCoreTasks, findFlowTask } from './core-tasks.js';
 import { flowReferences } from './flow-store.js';
+import { providerCredentialStatus, scrubProviderSecrets } from './provider-credentials.js';
 
 /** Uses the same routing and health rules as submissions. No discovery, network calls or writes. */
 export function projectProviderDiagnostics(catalog, registry) {
@@ -15,7 +16,9 @@ export function projectProviderDiagnostics(catalog, registry) {
       const evidence = observation || (legacy ? { [legacy.ok ? 'lastSuccess' : ['auth', 'authentication', 'permission'].includes(legacy.category) ? 'lastFailure' : 'lastTransient']: legacy } : undefined);
       const limit = modelRateLimit(provider, model.id);
       const latest = newestHealthEvidence(evidence);
-      const reason = provider.enabled === false ? 'provider_disabled' : !isConfiguredProvider(provider) ? 'connection_unconfigured'
+      const reason = provider.enabled === false ? 'provider_disabled'
+        : provider.auth !== 'none' && provider.apiKeyEnv && providerCredentialStatus(provider) !== 'ready' ? 'credential_unavailable'
+          : !isConfiguredProvider(provider) ? 'connection_unconfigured'
         : route.mode === 'disabled' ? 'function_disabled' : model.source === 'discovered' ? 'unconfirmed'
           : !supportsModelCapability(provider, model.id, route.capability, { registry }) ? 'protocol_unsupported'
             : model.unavailableCapabilities?.includes(route.capability) ? 'model_missing' : limit ? limit.until ? 'cooling' : 'quota'
@@ -31,10 +34,7 @@ export function projectProviderDiagnostics(catalog, registry) {
       verified: models.filter(model => model.eligible && model.state === 'verified').length, models };
   });
   const result = { contractVersion: 0, capabilities };
-  const keys = catalog.providers.map(provider => provider.apiKey).filter(key => typeof key === 'string' && key);
-  const scrub = value => typeof value === 'string' ? keys.reduce((text, key) => text.split(key).join('[redacted]'), value)
-    : Array.isArray(value) ? value.map(scrub) : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).map(([key, item]) => [key, scrub(item)])) : value;
-  return scrub(result);
+  return scrubProviderSecrets(result, catalog.providers);
 }
 
 /** Current root only, under the caller's Core lease; unknown/corrupt records must fail visibly. */

package/lib/provider-health.js

@@ -3,7 +3,7 @@ import { isKnownCapability } from './capability.js';
 import { isModelNotFound, modelAvailabilityBinding, modelUnavailable } from './model-directory.js';
 
 const HEALTH_SENSITIVE_FIELDS = new Set([
-  'auth', 'type', 'baseUrl', 'mediaBaseUrl', 'apiKey', 'mediaProtocol',
+  'auth', 'type', 'baseUrl', 'mediaBaseUrl', 'apiKey', 'apiKeyEnv', 'mediaProtocol',
   'imageModel', 'videoModel', 'ttsModel', 'transcribeModel', 'visionModel'
 ]);
 
@@ -51,14 +51,18 @@ export const PROVIDER_HEALTH_STATES = Object.freeze([
 
 const DEFINITIVE_FAILURES = new Set(['authentication', 'auth', 'permission']);
 export const MODEL_RATE_LIMIT_COOLDOWN_MS = 60000;
+// Bound supplier hints to Node's supported timer range, including their persisted ISO deadline.
+export const MAX_MODEL_RATE_LIMIT_COOLDOWN_MS = 2_147_483_647;
+const MAX_DATE_MS = 8_640_000_000_000_000;
+const boundedCooldown = delay => Math.min(MAX_MODEL_RATE_LIMIT_COOLDOWN_MS, Math.max(1000, delay));
 
 export function retryAfterDelay(value, now = Date.now()) {
   const raw = String(value ?? '').trim();
   if (!raw) return MODEL_RATE_LIMIT_COOLDOWN_MS;
   const seconds = Number(raw);
-  if (Number.isFinite(seconds) && seconds >= 0) return Math.max(1000, seconds * 1000);
+  if (Number.isFinite(seconds) && seconds >= 0) return boundedCooldown(seconds * 1000);
   const at = Date.parse(raw);
-  return Number.isFinite(at) && at > now ? at - now : MODEL_RATE_LIMIT_COOLDOWN_MS;
+  return Number.isFinite(at) && at > now ? boundedCooldown(at - now) : MODEL_RATE_LIMIT_COOLDOWN_MS;
 }
 
 /** 百炼“免费额度用完即停”返回 403，不应误归类为 Key 无效。 */
@@ -94,12 +98,13 @@ export function recordModelRateLimit(provider, modelId, result) {
   provider.health.rateLimits ||= [];
   const at = Date.parse(result.at || '');
   const timestamp = Number.isFinite(at) ? at : Date.now();
-  const delay = Number.isFinite(result.retryAfterMs) ? result.retryAfterMs : MODEL_RATE_LIMIT_COOLDOWN_MS;
+  const delay = Number.isFinite(result.retryAfterMs) && result.retryAfterMs >= 0
+    ? boundedCooldown(result.retryAfterMs) : MODEL_RATE_LIMIT_COOLDOWN_MS;
   provider.health.rateLimits = provider.health.rateLimits.filter(item => item.modelId !== modelId);
   provider.health.rateLimits.push({ modelId,
     at: new Date(timestamp).toISOString(),
     source: result.source === 'probe' ? 'probe' : 'task', category, httpStatus: status,
-    ...(reason ? { reason } : { until: result.until || new Date(timestamp + Math.max(1000, delay)).toISOString() }) });
+    ...(reason ? { reason } : { until: result.until || new Date(Math.min(MAX_DATE_MS, timestamp + delay)).toISOString() }) });
   return true;
 }
 

package/lib/provider-monitor.js

@@ -3,12 +3,13 @@ import { loadProviderCatalog } from './provider-catalog.js';
 import { executeConfigCommand } from './provider-config-service.js';
 import { modelDirectoryBinding } from './model-directory.js';
 import { selectMediaProtocol, isConfiguredProvider } from './provider-protocol.js';
+import { assertProviderCredential } from './provider-credentials.js';
 
 const AUTOMATIC = new Set(['dashscope', 'openai-images', 'openai-chat-images', 'openai-responses-images', 'gemini-web-music', 'comfyui']);
-const errorCode = error => ['IRIS_CONFIG_CHANGED', 'IRIS_CONFIG_BUSY', 'IRIS_PROVIDER_OPERATION_UNSUPPORTED'].includes(error.code) ? error.code
+const errorCode = error => /^IRIS_NETWORK_/.test(error.code || '') || ['IRIS_CONFIG_CHANGED', 'IRIS_CONFIG_BUSY', 'IRIS_PROVIDER_OPERATION_UNSUPPORTED'].includes(error.code) ? error.code
   : ['authentication', 'permission', 'network', 'timeout', 'protocol', 'rate_limit', 'provider', 'aborted'].includes(error.category) ? error.category : 'connection_failed';
 const fail = (code, message) => { throw Object.assign(new Error(message), { code }); };
-export function createProviderMonitor({ configPath, registry, setTimer = setTimeout, clearTimer = clearTimeout }) {
+export function createProviderMonitor({ configPath, registry, resolveProviderNetwork, setTimer = setTimeout, clearTimer = clearTimeout }) {
   const records = new Map(), pending = new Set(); let closed = false;
   const catalog = () => { if (closed) fail('IRIS_PROVIDER_MONITOR_CLOSED', '连接检查已关闭'); return loadProviderCatalog(configPath); };
   function record(providerId, provider = catalog().providers.find(item => item.id === providerId)) {
@@ -31,13 +32,14 @@ export function createProviderMonitor({ configPath, registry, setTimer = setTime
   }
   async function check(providerId, expectedRevision, { signal } = {}) {
     const { provider, item } = record(providerId);
+    if (provider.enabled !== false) assertProviderCredential(provider);
     if (!isConfiguredProvider(provider)) fail('IRIS_CONFIG_INPUT_INVALID', '请先保存并启用供应商连接');
     if (item.pending) fail('IRIS_API_BUSY', '此供应商正在检查，请等待结果');
     const controller = item.controller = new AbortController();
     const started = Date.now();
     const job = (async () => {
       try {
-        const result = await executeConfigCommand(configPath, 'settings.discover', { expectedRevision, providerId }, { registry,
+        const result = await executeConfigCommand(configPath, 'settings.discover', { expectedRevision, providerId }, { registry, resolveProviderNetwork,
           signal: AbortSignal.any([controller.signal, ...(signal ? [signal] : [])]) });
         item.last = { ok: true, at: new Date().toISOString(), elapsedMs: Date.now() - started, modelCount: result.models.length };
       } catch (error) {