@twinsearth/fang-dsh-plugin 0.0.0-stage → 3.3.4

package/src/lib/sse-parser.mjs

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+// dsh-Fang v2.6.5 — 增量 SSE 解析器（母体侧 SSE 传输的帧语法层）。
+//
+// 语义（与 docs/FUZZ-SSE-PARSER.md 的不变量一致）：
+//   * 只按 `\n` 切行；行尾若有且仅有一个 `\r` 则裁掉（CRLF 支持，lone-CR 当作 data 字符）；
+//   * 空行 = 帧边界：只有 dataLines 非空才产出帧（纯 id/event/注释帧被丢弃）；
+//   * `:` 开头为注释（心跳），忽略；`id` / `event` / `data` 之外字段忽略（`retry` 也忽略）；
+//   * 冒号后一个空格可选；多行 data 用 `\n` 拼接；dispatch 后重置 id/event/data；
+//   * flush() 丢弃未完成的残帧（EOF 语义），不产出帧。
+export class SseParser {
+  constructor() {
+    this.buffer = ''
+    this.curId = undefined
+    this.curEvent = undefined
+    this.dataLines = []
+  }
+
+  /**
+   * 喂入一段字符串，返回本次能解析出的完整帧。
+   * @param {unknown} chunk
+   * @returns {Array<{id?: string, event?: string, data: string}>}
+   */
+  push(chunk) {
+    this.buffer += String(chunk ?? '')
+    const frames = []
+    let start = 0
+    while (start < this.buffer.length) {
+      const nl = this.buffer.indexOf('\n', start)
+      if (nl === -1) break
+      let line = this.buffer.slice(start, nl)
+      if (line.endsWith('\r')) line = line.slice(0, -1)
+      start = nl + 1
+      const frame = this._processLine(line)
+      if (frame) frames.push(frame)
+    }
+    this.buffer = this.buffer.slice(start)
+    return frames
+  }
+
+  /**
+   * 流结束：按 SSE 规范丢弃未完成的半帧（没有空行边界的 data 不 dispatch）。
+   * @returns {[]}
+   */
+  flush() {
+    this.buffer = ''
+    this.curId = undefined
+    this.curEvent = undefined
+    this.dataLines = []
+    return []
+  }
+
+  /** @private */
+  _processLine(line) {
+    if (line === '') {
+      if (this.dataLines.length === 0) {
+        this.curId = undefined
+        this.curEvent = undefined
+        return null
+      }
+      const frame = { data: this.dataLines.join('\n') }
+      if (this.curId !== undefined) frame.id = this.curId
+      if (this.curEvent !== undefined) frame.event = this.curEvent
+      this.curId = undefined
+      this.curEvent = undefined
+      this.dataLines = []
+      return frame
+    }
+
+    if (line.startsWith(':')) return null // 注释 / 心跳
+
+    const colon = line.indexOf(':')
+    let field = line
+    let value = ''
+    if (colon >= 0) {
+      field = line.slice(0, colon)
+      value = line.slice(colon + 1)
+      if (value.startsWith(' ')) value = value.slice(1)
+    }
+
+    switch (field) {
+      case 'id':
+        this.curId = value
+        break
+      case 'event':
+        this.curEvent = value
+        break
+      case 'data':
+        this.dataLines.push(value)
+        break
+      default:
+        break // retry / 未知字段：忽略
+    }
+    return null
+  }
+}
+
+/** @param {object} [options] 保留参数位；返回新的 SseParser。 */
+export function createSseParser(options = {}) {
+  void options
+  return new SseParser()
+}

package/src/lib/ssrf-guard.mjs

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// ssrf-guard — AI / 出站端点的最小 SSRF 防护：
+//   * 字面量私网 IP：默认拒绝，除非显式 allowlist
+//   * 云元数据地址/主机名：永远拒绝（allowlist 也不能放行）
+//   * hostname：配置时只做语法检查；请求前做一次 DNS 解析，
+//     解析到私网/元数据则拒绝（防“公网域名解析到内网”的常见 SSRF）
+//
+// 诚实边界：DNS 预检与 fetch 的真实解析之间仍有 TOCTOU 窗口（DNS rebinding），
+// Node fetch 没有 pinned-lookup 接口；因此这里只做“高置信拦截”，不宣称完备。
+import net from 'node:net'
+import dns from 'node:dns/promises'
+
+const METADATA_HOSTS = new Set([
+  'metadata.google.internal',
+  'metadata.goog',
+  'instance-data',
+])
+
+const METADATA_ADDRESSES = new Set([
+  '169.254.169.254', // AWS / GCP / Azure IMDS
+  '100.100.100.200', // Alibaba Cloud
+  '192.0.0.192', // Oracle Cloud
+  'fd00:ec2::254', // AWS IPv6 IMDS
+])
+
+export function normalizeHost(value) {
+  let host = String(value ?? '').trim().toLowerCase()
+  if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1)
+  return host.replace(/\.$/, '')
+}
+
+export function isMetadataAddress(value) {
+  return METADATA_ADDRESSES.has(normalizeHost(value))
+}
+
+export function isMetadataHost(value) {
+  return METADATA_HOSTS.has(normalizeHost(value))
+}
+
+const inV4Range = (parts, base, bits) => {
+  if (!Array.isArray(parts) || parts.length !== 4) return false
+  let value = 0
+  for (const part of parts) value = (value << 8) | part
+  const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0
+  return (value & mask) === (base & mask)
+}
+
+function ipv4Parts(ip) {
+  const parts = ip.split('.').map(Number)
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return null
+  return parts
+}
+
+function ipv4ToInt(parts) {
+  return (((parts[0] << 24) >>> 0) + (parts[1] << 16) + (parts[2] << 8) + parts[3]) >>> 0
+}
+
+export function isPrivateIpv4(ip) {
+  const parts = ipv4Parts(ip)
+  if (!parts) return false
+  const value = ipv4ToInt(parts)
+  // RFC1918
+  if (inV4Range(parts, ipv4ToInt([10, 0, 0, 0]), 8)) return true
+  if (inV4Range(parts, ipv4ToInt([172, 16, 0, 0]), 12)) return true
+  if (inV4Range(parts, ipv4ToInt([192, 168, 0, 0]), 16)) return true
+  // loopback / link-local / unspecified
+  if (inV4Range(parts, ipv4ToInt([127, 0, 0, 0]), 8)) return true
+  if (inV4Range(parts, ipv4ToInt([169, 254, 0, 0]), 16)) return true
+  if (inV4Range(parts, ipv4ToInt([0, 0, 0, 0]), 8)) return true
+  // CGNAT / benchmark / multicast / reserved
+  if (inV4Range(parts, ipv4ToInt([100, 64, 0, 0]), 10)) return true
+  if (inV4Range(parts, ipv4ToInt([198, 18, 0, 0]), 15)) return true
+  if (inV4Range(parts, ipv4ToInt([198, 51, 100, 0]), 24)) return true
+  if (inV4Range(parts, ipv4ToInt([203, 0, 113, 0]), 24)) return true
+  if (((value & 0xF0000000) >>> 0) === 0xE0000000) return true // multicast
+  if (((value & 0xF0000000) >>> 0) === 0xF0000000) return true // reserved
+  return false
+}
+
+function ipv6Groups(ip) {
+  const raw = normalizeHost(ip)
+  if (!raw.includes(':')) return null
+  const [head, tail] = raw.split('::')
+  const parse = (segment) => segment.length === 0 ? [] : segment.split(':')
+  let groups = []
+  if (raw.includes('::')) groups = [...parse(head), ...Array(8 - parse(head).length - parse(tail ?? '').length).fill('0'), ...parse(tail ?? '')]
+  else groups = raw.split(':')
+  if (groups.length !== 8) return null
+  return groups.map((group) => parseInt(group || '0', 16)).filter((part) => Number.isInteger(part))
+}
+
+export function isPrivateIpv6(ip) {
+  const raw = normalizeHost(ip)
+  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(raw)
+  if (mapped) return isPrivateIpv4(mapped[1])
+  const groups = ipv6Groups(raw)
+  if (!groups) return false
+  if (groups.every((group, index) => (index < 7 ? group === 0 : group === 1))) return true // ::1
+  if (groups.every((group) => group === 0)) return true // ::
+  if ((groups[0] & 0xFE00) === 0xFC00) return true // fc00::/7
+  if ((groups[0] & 0xFFC0) === 0xFE80) return true // fe80::/10
+  if ((groups[0] & 0xFF00) === 0xFF00) return true // multicast
+  // IPv4-mapped ::ffff:a.b.c.d
+  if (groups.slice(0, 5).every((group) => group === 0) && groups[5] === 0xFFFF) {
+    const v4 = `${groups[6] >> 8}.${groups[6] & 0xFF}.${groups[7] >> 8}.${groups[7] & 0xFF}`
+    return isPrivateIpv4(v4)
+  }
+  return false
+}
+
+export function isPrivateAddress(ip) {
+  const host = normalizeHost(ip)
+  const family = net.isIP(host)
+  if (family === 4) return isPrivateIpv4(host)
+  if (family === 6) return isPrivateIpv6(host)
+  return false
+}
+
+/** 同步分类：仅处理字面量 IP 与元数据主机名；DNS 主机名留给请求前预检。 */
+export function classifyEndpointHost(hostname, { allowHosts = [] } = {}) {
+  const host = normalizeHost(hostname)
+  const allowed = new Set((Array.isArray(allowHosts) ? allowHosts : []).map(normalizeHost))
+  if (isMetadataHost(host)) return { ok: false, reason: 'metadata-address-blocked', kind: 'metadata' }
+  const family = net.isIP(host)
+  if (family === 0) {
+    if (host === 'localhost') return { ok: true, kind: 'loopback' }
+    return { ok: true, kind: 'hostname' }
+  }
+  if (isMetadataAddress(host)) return { ok: false, reason: 'metadata-address-blocked', kind: 'metadata' }
+  if (family === 4 && inV4Range(ipv4Parts(host) ?? [], ipv4ToInt([127, 0, 0, 0]), 8)) return { ok: true, kind: 'loopback' }
+  if (family === 6) {
+    const groups = ipv6Groups(host)
+    if (groups && groups.every((group, index) => (index < 7 ? group === 0 : group === 1))) return { ok: true, kind: 'loopback' }
+  }
+  if ((family === 4 && isPrivateIpv4(host)) || (family === 6 && isPrivateIpv6(host))) {
+    if (allowed.has(host)) return { ok: true, kind: 'private-allowlisted' }
+    return { ok: false, reason: 'private-address-blocked', kind: 'private' }
+  }
+  return { ok: true, kind: family === 4 ? 'public-ipv4' : 'public-ipv6' }
+}
+
+/** 请求前 DNS 预检；解析失败视为 NXDOMAIN（交给 fetch 失败，不视为 SSRF）。 */
+export async function assertEndpointSafe(hostname, { allowHosts = [], resolve = dns.lookup, timeoutMs = 1500 } = {}) {
+  const sync = classifyEndpointHost(hostname, { allowHosts })
+  if (!sync.ok) return sync
+  if (sync.kind !== 'hostname') return sync
+  const host = normalizeHost(hostname)
+  const allowed = new Set((Array.isArray(allowHosts) ? allowHosts : []).map(normalizeHost))
+  // 明确的 metadata 主机名已在 sync 拦截；其余做一次解析。
+  let addresses = []
+  try {
+    const result = await Promise.race([
+      resolve(host, { all: true, verbatim: true }),
+      new Promise((_, reject) => setTimeout(() => reject(new Error('dns-timeout')), timeoutMs).unref?.()),
+    ])
+    addresses = Array.isArray(result) ? result : (result?.address ? [result] : [])
+  } catch (error) {
+    return { ok: true, kind: 'hostname-unresolved', detail: String(error?.message ?? error) }
+  }
+  for (const entry of addresses) {
+    const address = normalizeHost(entry?.address ?? entry)
+    if (isMetadataAddress(address)) return { ok: false, reason: 'metadata-address-blocked', kind: 'metadata', address }
+    if (isPrivateAddress(address) && !allowed.has(host)) {
+      return { ok: false, reason: 'private-address-blocked', kind: 'private', address }
+    }
+  }
+  return { ok: true, kind: 'hostname-public', addresses: addresses.map((entry) => normalizeHost(entry?.address ?? entry)) }
+}

package/src/lib/status-store.mjs

@@ -0,0 +1,257 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// dsh-Fang v3.1.0 — MirrorStatusStore（插件层外部 store，框架无关）。
+//
+// 供 DSH client-half（React）用 useSyncExternalStore 订阅：
+//   const snap = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot)
+//
+// 语义：
+//   * 订阅者 0 → 不轮询；首个订阅者立即 refresh；
+//   * 轮询间隔 = activeConsumers > 0 且未空闲降级 ? activeIntervalMs : idleIntervalMs；
+//   * acquireActive() 引用计数 + 每次调用重置 idleTimer（默认 30s 无交互 → 降回 idle）；
+//   * pokeActive() 只报告“用户还活着”，不改变引用计数（refcount=0 时 no-op）；
+//   * 降级后 pokeActive() 立即恢复高频档（不立即 refresh，节奏仍由 interval 决定）；
+//   * refresh 结果 304 时只更新 lastUpdatedAt，不替换 status 引用；
+//   * dispose() 清理所有定时器并 abort in-flight。
+//
+// 测试可注入 timers/now/fetcher，避免真实等待。
+
+export const INITIAL_MIRROR_SNAPSHOT = Object.freeze({
+  status: null, loading: false, error: null, lastUpdatedAt: null,
+})
+
+export class MirrorStatusStore {
+  /**
+   * @param {{fetcher: (options: {force?: boolean, signal?: AbortSignal}) => Promise<{status: object|null, notModified: boolean}>,
+   *   idleIntervalMs?: number, activeIntervalMs?: number, activeIdleTimeoutMs?: number,
+   *   logger?: {warn?: Function},
+   *   timers?: {setTimeout: Function, clearTimeout: Function, setInterval: Function, clearInterval: Function},
+   *   now?: () => number}} options
+   */
+  constructor(options) {
+    if (options === null || typeof options !== 'object' || typeof options.fetcher !== 'function') {
+      throw new Error('MirrorStatusStore: fetcher required')
+    }
+    this.fetcher = options.fetcher
+    this.idleIntervalMs = Math.max(1, Number(options.idleIntervalMs) || 60_000)
+    this.activeIntervalMs = Math.max(1, Number(options.activeIntervalMs) || 5_000)
+    this.activeIdleTimeoutMs = Math.max(1, Number(options.activeIdleTimeoutMs) || 30_000)
+    this.logger = options.logger ?? {}
+    this.timers = options.timers ?? { setTimeout, clearTimeout, setInterval, clearInterval }
+    this.now = typeof options.now === 'function' ? options.now : () => Date.now()
+    this.snapshot = INITIAL_MIRROR_SNAPSHOT
+    this.subscribers = new Set()
+    this.idleSinks = new Set()
+    this.activeConsumers = 0
+    this.activeAcquiredAt = null
+    this.lastPokeAt = null
+    this.idleTimedOut = false
+    this.idleTimer = null
+    this.timer = null
+    this.inFlight = false
+    this.stopped = false
+    this.controller = typeof AbortController === 'function' ? new AbortController() : null
+    this.getSnapshot = () => this.snapshot
+    this.subscribe = (callback) => this.addSubscriber(callback)
+  }
+
+  addSubscriber(callback) {
+    this.subscribers.add(callback)
+    if (this.subscribers.size === 1) this.startPolling()
+    return () => {
+      this.subscribers.delete(callback)
+      if (this.subscribers.size === 0) this.stopPolling()
+    }
+  }
+
+  startPolling() {
+    void this.refresh()
+    this.rescheduleTimer()
+  }
+
+  stopPolling() {
+    this.clearTimer()
+  }
+
+  /** 注册高频消费者；返回幂等 release。 */
+  acquireActive() {
+    this.activeConsumers += 1
+    if (this.activeConsumers === 1) {
+      this.activeAcquiredAt = this.now()
+      this.lastPokeAt = null
+    }
+    this.idleTimedOut = false
+    this.resetIdleTimer()
+    this.rescheduleTimer()
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      this.activeConsumers = Math.max(0, this.activeConsumers - 1)
+      if (this.activeConsumers === 0) {
+        this.idleTimedOut = false
+        this.activeAcquiredAt = null
+        this.lastPokeAt = null
+        this.clearIdleTimer()
+      }
+      this.rescheduleTimer()
+    }
+  }
+
+  /** 报告用户交互；refcount=0 或已 dispose 时 no-op。 */
+  pokeActive() {
+    if (this.stopped || this.activeConsumers === 0) return
+    this.lastPokeAt = this.now()
+    if (!this.idleTimedOut) { this.resetIdleTimer(); return }
+    this.idleTimedOut = false
+    this.resetIdleTimer()
+    this.rescheduleTimer()
+  }
+
+  /** 是否处于空闲降级态（供重算轮询等消费者降频）。 */
+  isIdle() {
+    return this.idleTimedOut
+  }
+
+  /**
+   * 订阅空闲降级事件（用于 Auditor 统计“打开后多久走开”）。
+   * @param {(event: {at:number, timeoutMs:number, acquiredAt:number, lastPokeAt:number|null,
+   *   idleAfterMs:number, totalActiveMs:number, activeConsumers:number}) => void} sink
+   * @returns {() => void} unsubscribe
+   */
+  onIdleDowngraded(sink) {
+    if (typeof sink !== 'function') throw new TypeError('onIdleDowngraded: sink must be a function')
+    this.idleSinks.add(sink)
+    return () => { this.idleSinks.delete(sink) }
+  }
+
+  /** 当前有效轮询间隔（诊断/测试用）。 */
+  currentIntervalMs() {
+    return this.activeConsumers > 0 && !this.idleTimedOut ? this.activeIntervalMs : this.idleIntervalMs
+  }
+
+  /** 当前交互超时（毫秒）。 */
+  getActiveIdleTimeout() {
+    return this.activeIdleTimeoutMs
+  }
+
+  /**
+   * 运行时调整“无交互降级”超时（设置面板 15/30/60s）。
+   * - 无活跃消费者：只记录，下次 acquireActive 生效；
+   * - 已降级：视为用户回来操作，恢复高频并重建 idleTimer；
+   * - 活跃未降级：只重建 idleTimer（不重建轮询 timer，避免推迟下一次轮询）。
+   * @param {number} ms
+   */
+  setActiveIdleTimeout(ms) {
+    const next = Number(ms)
+    if (!Number.isFinite(next) || next < 1) throw new RangeError('invalid activeIdleTimeoutMs')
+    if (next === this.activeIdleTimeoutMs) return
+    this.activeIdleTimeoutMs = next
+    if (this.stopped || this.activeConsumers === 0) return
+    if (this.idleTimedOut) {
+      this.idleTimedOut = false
+      this.rescheduleTimer()
+    }
+    this.resetIdleTimer()
+  }
+
+  async refresh(options = {}) {
+    if (this.stopped || this.inFlight) return
+    if (this.controller !== null && this.controller.signal.aborted) return
+    this.inFlight = true
+    this.update({ loading: true })
+    try {
+      const result = await this.fetcher({
+        force: options.force === true,
+        signal: this.controller === null ? undefined : this.controller.signal,
+      })
+      if (this.stopped || (this.controller !== null && this.controller.signal.aborted)) return
+      if (result.notModified === true) {
+        this.update({ loading: false, error: null, lastUpdatedAt: this.now() })
+      } else if (result.status !== null && result.status !== undefined) {
+        this.update({ status: result.status, loading: false, error: null, lastUpdatedAt: this.now() })
+      }
+    } catch (error) {
+      if (this.stopped || (this.controller !== null && this.controller.signal.aborted)) return
+      this.logger.warn?.('[mirror-status] refresh failed', {
+        error: String(error instanceof Error ? error.message : error),
+      })
+      this.update({ loading: false, error: String(error instanceof Error ? error.message : error) })
+    } finally {
+      this.inFlight = false
+    }
+  }
+
+  dispose() {
+    this.stopped = true
+    this.clearTimer()
+    this.clearIdleTimer()
+    if (this.controller !== null) this.controller.abort()
+    this.subscribers.clear()
+    this.idleSinks.clear()
+  }
+
+  // ── internals ────────────────────────────────────────────────────────────
+
+  resetIdleTimer() {
+    this.clearIdleTimer()
+    if (this.stopped || this.activeConsumers === 0) return
+    this.idleTimer = this.timers.setTimeout(() => { this.handleIdleTimeout() }, this.activeIdleTimeoutMs)
+    this.idleTimer?.unref?.()
+  }
+
+  /** 降级发生：记录事件（真实走开时长 = now - lastPokeAt/acquiredAt）并通知订阅者。 */
+  handleIdleTimeout() {
+    this.idleTimer = null
+    if (this.stopped || this.activeConsumers === 0) return
+    const at = this.now()
+    const acquiredAt = this.activeAcquiredAt ?? at
+    const reference = this.lastPokeAt ?? acquiredAt
+    const event = {
+      at,
+      timeoutMs: this.activeIdleTimeoutMs,
+      acquiredAt,
+      lastPokeAt: this.lastPokeAt,
+      idleAfterMs: at - reference,
+      totalActiveMs: at - acquiredAt,
+      activeConsumers: this.activeConsumers,
+    }
+    this.idleTimedOut = true
+    this.rescheduleTimer()
+    this.logger.warn?.('[mirror-status] active consumer idle, downgrading to idle interval', {
+      idleIntervalMs: this.idleIntervalMs, idleAfterMs: event.idleAfterMs,
+    })
+    for (const sink of [...this.idleSinks]) {
+      try { sink(event) } catch { /* 订阅者异常隔离 */ }
+    }
+  }
+
+  clearIdleTimer() {
+    if (this.idleTimer !== null) {
+      this.timers.clearTimeout(this.idleTimer)
+      this.idleTimer = null
+    }
+  }
+
+  rescheduleTimer() {
+    if (this.stopped || this.subscribers.size === 0) return
+    this.clearTimer()
+    this.timer = this.timers.setInterval(() => { void this.refresh() }, this.currentIntervalMs())
+    this.timer?.unref?.()
+  }
+
+  clearTimer() {
+    if (this.timer !== null) {
+      this.timers.clearInterval(this.timer)
+      this.timer = null
+    }
+  }
+
+  update(patch) {
+    this.snapshot = { ...this.snapshot, ...patch }
+    for (const callback of [...this.subscribers]) {
+      try { callback() } catch { /* 订阅者异常隔离 */ }
+    }
+  }
+}
+
+export const _internals = Object.freeze({ INITIAL_MIRROR_SNAPSHOT })