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

package/src/lib/fs-guard.mjs

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// v3.0.9 fail-closed path guard: canonicalize and keep every path inside its root.
+import fs from 'node:fs'
+import path from 'node:path'
+
+export function safeJoin(root, ...parts) {
+  const base = path.resolve(root)
+  const target = path.resolve(base, ...parts)
+  if (target !== base && !target.startsWith(base + path.sep)) throw new Error('path-escape')
+  if (String(target).includes('\0')) throw new Error('path-escape')
+  return target
+}
+
+export function assertInside(root, target, { followSymlink = true } = {}) {
+  const base = path.resolve(root)
+  const lexical = path.resolve(target)
+  let resolved = lexical
+  let boundary = base
+  if (followSymlink) {
+    try { boundary = fs.realpathSync.native(base) } catch { /* keep lexical */ }
+    try { resolved = fs.realpathSync.native(lexical) } catch {
+      try { resolved = path.join(fs.realpathSync.native(path.dirname(lexical)), path.basename(lexical)) } catch { /* keep lexical */ }
+    }
+  }
+  const rel = path.relative(boundary, resolved)
+  if (rel === '..' || rel.startsWith('..' + path.sep) || path.isAbsolute(rel)) throw new Error('path-escape')
+  return lexical
+}

package/src/lib/http-auth.mjs

@@ -0,0 +1,162 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// v3.0.5/B1 — 安装级 HTTP 鉴权：token 文件（0600）、loopback Host 校验、CSRF/Origin 检查。
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { ensureDir, exists } from '../kernel/index.mjs'
+
+export const AUTH_TOKEN_FILE = 'fang-auth.json'
+export const AUTH_HEADER = 'x-fang-auth'
+export const MIN_TOKEN_LENGTH = 32
+
+/** 读取/生成安装级 token（env 覆盖 > 0600 文件 > 新建）。 */
+export function loadAuthToken(dataDir, envToken = process.env.DSH_FANG_AUTH_TOKEN) {
+  const fromEnv = String(envToken ?? '').trim()
+  if (fromEnv.length >= MIN_TOKEN_LENGTH) return fromEnv
+  const file = path.join(dataDir, AUTH_TOKEN_FILE)
+  if (exists(file)) {
+    try {
+      const doc = JSON.parse(fs.readFileSync(file, 'utf8'))
+      if (typeof doc?.token === 'string' && doc.token.length >= MIN_TOKEN_LENGTH) return doc.token
+    } catch { /* 损坏则重建 */ }
+  }
+  const token = crypto.randomBytes(32).toString('hex')
+  ensureDir(dataDir)
+  fs.writeFileSync(file, JSON.stringify({ token, createdAt: Date.now() }), { encoding: 'utf8', mode: 0o600 })
+  try { fs.chmodSync(file, 0o600) } catch { /* Windows 上 chmod 可能无效 */ }
+  return token
+}
+
+/**
+ * Host 是否 loopback（支持 localhost / 127.0.0.1 / [::1] / ::1，可带端口）。
+ *
+ * 严格解析：`[::1]evil.example`、`127.0.0.1:3080@evil.example` 这类带尾随垃圾的
+ * Host 必须判假——否则 DNS rebinding 防护会被一个字符串前缀绕过。
+ */
+export function isLoopbackHost(host) {
+  const raw = String(host ?? '').trim().toLowerCase()
+  if (raw.length === 0) return false
+  if (raw === '::1') return true
+  if (raw.startsWith('[')) {
+    const match = /^\[([0-9a-f:.]+)\](?::(\d{1,5}))?$/.exec(raw)
+    if (!match) return false
+    if (match[2] !== undefined && Number(match[2]) > 65535) return false
+    return match[1] === '::1'
+  }
+  const match = /^([a-z0-9.-]+)(?::(\d{1,5}))?$/.exec(raw)
+  if (!match) return false
+  if (match[2] !== undefined && Number(match[2]) > 65535) return false
+  return match[1] === 'localhost' || match[1] === '127.0.0.1'
+}
+
+/** Origin 是否允许（同源 loopback / dsh-app 壳 / 无 Origin）。 */
+export function isAllowedOrigin(origin) {
+  const raw = String(origin ?? '').trim()
+  if (raw.length === 0) return true
+  if (raw === 'dsh-app://app' || raw.startsWith('dsh-app://')) return true
+  try {
+    const url = new URL(raw)
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return false
+    return isLoopbackHost(url.host)
+  } catch {
+    return false
+  }
+}
+
+function header(req, name) {
+  const headers = req?.headers ?? {}
+  const lower = name.toLowerCase()
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() === lower) return String(headers[key] ?? '')
+  }
+  return ''
+}
+
+function timingSafeEqualText(expected, actual) {
+  const a = Buffer.from(String(expected), 'utf8')
+  const b = Buffer.from(String(actual), 'utf8')
+  if (a.length !== b.length || a.length === 0) return false
+  try { return crypto.timingSafeEqual(a, b) } catch { return false }
+}
+
+/**
+ * 请求鉴权决策（fail-closed）。
+ * @param {any} req
+ * @param {{token:string, publicRoute?:boolean}} options
+ * @returns {{ok:true} | {ok:false, status:number, code:string}}
+ */
+export function checkRequestAuth(req, options) {
+  const token = String(options?.token ?? '')
+  const method = String(req?.method ?? 'GET').toUpperCase()
+  const host = header(req, 'host')
+  if (host && !isLoopbackHost(host)) return { ok: false, status: 403, code: 'bad-host' }
+  const origin = header(req, 'origin')
+  if (!isAllowedOrigin(origin)) return { ok: false, status: 403, code: 'bad-origin' }
+  const site = header(req, 'sec-fetch-site')
+  if (site && site !== 'same-origin' && site !== 'same-site' && site !== 'none') {
+    return { ok: false, status: 403, code: 'cross-site' }
+  }
+  if (options?.publicRoute === true) return { ok: true }
+  const given = header(req, AUTH_HEADER) || (() => {
+    const auth = header(req, 'authorization')
+    const match = /^Bearer\s+(.+)$/i.exec(auth)
+    return match ? match[1].trim() : ''
+  })()
+  if (!timingSafeEqualText(token, given)) return { ok: false, status: 401, code: 'unauthorized' }
+  // 写操作要求 JSON content-type（阻止 text/plain 简单请求 CSRF；无 body 的 POST 也允许）
+  if (method !== 'GET' && method !== 'HEAD' && method !== 'OPTIONS') {
+    const contentType = header(req, 'content-type').toLowerCase()
+    if (contentType && !contentType.includes('application/json')) {
+      return { ok: false, status: 415, code: 'content-type-required' }
+    }
+  }
+  return { ok: true }
+}
+
+/** Stable error envelope for every auth/host/origin rejection (additive `code`). */
+export function authErrorBody(decision) {
+  const code = String(decision?.code ?? 'unauthorized')
+  return { ok: false, error: code, code }
+}
+
+/**
+ * Install-level guard shared by every plugin that owns `/fang/api/*` routes.
+ *
+ * Resolves the token exactly once at startup, with the same precedence as the
+ * orchestrator: explicit config > env > `<dataDir>/fang-auth.json` (0600).
+ * `enabled: false` is the explicit test/debug escape hatch and still enforces
+ * Host/Origin/CSRF — it only skips the token comparison.
+ *
+ * @param {{dataDir?:string, token?:string, envToken?:string, enabled?:boolean}} [options]
+ * @returns {{token:string, enabled:boolean, check:(req:any, routeOptions?:{public?:boolean})=>
+ *   ({ok:true}|{ok:false,status:number,code:string})}}
+ */
+export function createHttpGuard(options = {}) {
+  const enabled = options.enabled !== false
+  const dataDir = String(options.dataDir ?? '').trim()
+  const explicit = String(options.token ?? '').trim()
+  const envToken = options.envToken === undefined ? process.env.DSH_FANG_AUTH_TOKEN : options.envToken
+  let token = ''
+  if (enabled) {
+    if (dataDir) {
+      token = loadAuthToken(dataDir, explicit || envToken)
+    } else {
+      const candidate = explicit || String(envToken ?? '').trim()
+      if (candidate.length < MIN_TOKEN_LENGTH) {
+        throw new Error('http-auth: dataDir or a >=32-char auth token is required when auth is enabled')
+      }
+      token = candidate
+    }
+  }
+  return {
+    token,
+    enabled: token.length > 0,
+    check(req, routeOptions = {}) {
+      return checkRequestAuth(req, {
+        token,
+        publicRoute: token.length === 0 || routeOptions.public === true,
+      })
+    },
+  }
+}

package/src/lib/idle-audit.mjs

@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// dsh-Fang v3.0.8 — 空闲降级审计聚合。
+//
+// MirrorStatusStore 在“活跃消费者 30s 无交互 → 降级”时发 ActiveIdleEvent；
+// 本模块把事件写入 Auditor（单条 + 周期 summary），并从统计里生成 UI 优化建议：
+//   * idleAfterMs = 降级时刻 - 最后一次交互（真实的“走开时长”）
+//   * totalActiveMs = 降级时刻 - 首次 acquireActive（用户停留总时长）
+// 样本不足（默认 <10）不给建议，避免小样本误导。
+
+export const IDLE_AUDIT_KIND = 'mirror-idle-downgrade'
+export const IDLE_AUDIT_SUMMARY_KIND = 'mirror-idle-downgrade-summary'
+
+export class IdleAuditAggregator {
+  /**
+   * @param {{record: (payload: Record<string, unknown>) => (void|Promise<void>),
+   *   minSamplesForRecommendation?: number, snapshotIntervalMs?: number,
+   *   timers?: {setInterval: Function, clearInterval: Function}, now?: () => number}} options
+   */
+  constructor(options) {
+    if (options === null || typeof options !== 'object' || typeof options.record !== 'function') {
+      throw new Error('IdleAuditAggregator: record required')
+    }
+    this.record = options.record
+    this.minSamples = Math.max(1, Math.floor(Number(options.minSamplesForRecommendation) || 10))
+    this.snapshotIntervalMs = Math.max(1, Math.floor(Number(options.snapshotIntervalMs) || 300_000))
+    this.timers = options.timers ?? { setInterval, clearInterval }
+    this.now = typeof options.now === 'function' ? options.now : () => Date.now()
+    this.events = []
+    this.rollingEvents = []
+    this.rollingCapacity = Math.max(1, Math.floor(Number(options.rollingCapacity) || 500))
+    this.snapshotTimer = null
+    this.sink = (event) => { this.handle(event) }
+  }
+
+  /** 传给 MirrorStatusStore.onIdleDowngraded(sink)。 */
+  asSink() {
+    return this.sink
+  }
+
+  start() {
+    this.stop()
+    this.snapshotTimer = this.timers.setInterval(() => { void this.publishSnapshot() }, this.snapshotIntervalMs)
+    this.snapshotTimer?.unref?.()
+  }
+
+  stop() {
+    if (this.snapshotTimer !== null) {
+      this.timers.clearInterval(this.snapshotTimer)
+      this.snapshotTimer = null
+    }
+  }
+
+  /** 基于滚动窗口（长期，最近 N 条）生成结构化建议；样本不足返回空数组。 */
+  getRecommendations() {
+    if (this.rollingEvents.length < this.minSamples) return []
+    return this.buildRecommendations(this.rollingEvents)
+  }
+
+  /** 由事件数组生成结构化建议（fieldKey/suggestedValue/text/sampleCount/confidence）。 */
+  buildRecommendations(events) {
+    const total = events.length
+    if (total === 0) return []
+    let rapid = 0
+    let full = 0
+    for (const event of events) {
+      if (event.idleAfterMs < event.timeoutMs * 0.3) rapid += 1
+      if (event.idleAfterMs >= event.timeoutMs * 0.9) full += 1
+    }
+    const rapidRatio = rapid / total
+    const fullRatio = full / total
+    const recommendations = []
+    if (rapidRatio > 0.5) {
+      recommendations.push({
+        fieldKey: 'activeIdleTimeoutMs',
+        suggestedValue: 15_000,
+        text: `超过一半（${(rapidRatio * 100).toFixed(0)}%）的对话框打开后很快走开，可考虑把交互超时降到 15 秒，减少无意义的高频轮询。`,
+        sampleCount: total,
+        confidence: rapidRatio,
+      })
+    }
+    if (fullRatio > 0.8) {
+      recommendations.push({
+        fieldKey: 'activeIdleTimeoutMs',
+        suggestedValue: 60_000,
+        text: `${(fullRatio * 100).toFixed(0)}% 的用户活跃到超时窗口末尾，建议把交互超时提高到 60 秒，让状态刷新更实时。`,
+        sampleCount: total,
+        confidence: fullRatio,
+      })
+    }
+    return recommendations
+  }
+
+  /** 发布聚合快照（无事件则不发）；发布后清空窗口。 */
+  async publishSnapshot() {
+    if (this.events.length === 0) return null
+    const windowStart = this.events[0].at
+    const windowEnd = this.events[this.events.length - 1].at
+    const summary = this.computeSummary()
+    this.events = []
+    const payload = {
+      kind: IDLE_AUDIT_SUMMARY_KIND,
+      at: this.now(),
+      windowStart,
+      windowEnd,
+      summary,
+    }
+    await this.record(payload)
+    return summary
+  }
+
+  computeSummary() {
+    const byTimeout = {}
+    let rapidAway = 0
+    let fullTimeout = 0
+    for (const event of this.events) {
+      const bucket = byTimeout[event.timeoutMs] ?? { count: 0, totalIdleAfterMs: 0, totalActiveMs: 0 }
+      bucket.count += 1
+      bucket.totalIdleAfterMs += event.idleAfterMs
+      bucket.totalActiveMs += event.totalActiveMs
+      byTimeout[event.timeoutMs] = bucket
+      if (event.idleAfterMs < event.timeoutMs * 0.3) rapidAway += 1
+      if (event.idleAfterMs >= event.timeoutMs * 0.9) fullTimeout += 1
+    }
+    for (const key of Object.keys(byTimeout)) {
+      const bucket = byTimeout[key]
+      bucket.avgIdleAfterMs = Math.round(bucket.totalIdleAfterMs / bucket.count)
+      bucket.avgTotalActiveMs = Math.round(bucket.totalActiveMs / bucket.count)
+      delete bucket.totalIdleAfterMs
+      delete bucket.totalActiveMs
+    }
+    const recommendations = this.events.length >= this.minSamples ? this.buildRecommendations(this.events) : []
+    return {
+      totalEvents: this.events.length,
+      byTimeout,
+      rapidAwayCount: rapidAway,
+      fullTimeoutCount: fullTimeout,
+      recommendation: recommendations[0]?.text ?? null,
+      recommendations,
+    }
+  }
+
+  buildRecommendation(rapidAway, fullTimeout) {
+    const total = this.events.length
+    if (total < this.minSamples) return null
+    const rapidRatio = rapidAway / total
+    const fullRatio = fullTimeout / total
+    if (rapidRatio > 0.5) {
+      return `超过一半（${(rapidRatio * 100).toFixed(0)}%）的对话框打开后很快走开，建议把默认交互超时降到 15s 以减少无意义轮询。`
+    }
+    if (fullRatio > 0.8) {
+      return `${(fullRatio * 100).toFixed(0)}% 的用户活跃到超时窗口末尾，建议把默认交互超时提高到 60s。`
+    }
+    return null
+  }
+
+  handle(event) {
+    this.events.push(event)
+    this.rollingEvents.push(event)
+    if (this.rollingEvents.length > this.rollingCapacity) {
+      this.rollingEvents.splice(0, this.rollingEvents.length - this.rollingCapacity)
+    }
+    const payload = {
+      kind: IDLE_AUDIT_KIND,
+      at: event.at,
+      timeoutMs: event.timeoutMs,
+      idleAfterMs: event.idleAfterMs,
+      totalActiveMs: event.totalActiveMs,
+      lastPokeAt: event.lastPokeAt,
+      activeConsumers: event.activeConsumers,
+    }
+    try {
+      const result = this.record(payload)
+      if (result !== null && typeof result === 'object' && typeof result.then === 'function') {
+        result.catch(() => { /* 审计失败不影响 UI */ })
+      }
+    } catch { /* 审计失败不影响 UI */ }
+  }
+}

package/src/lib/interaction-poke.mjs

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// dsh-Fang v3.1.0 — 用户交互 poke（框架无关）。
+//
+// 消费者（如打开的镜像设置对话框）在挂载时调用 installInteractionPoke(store, {target})，
+// 鼠标/键盘/滚动/触摸等轻量交互会节流触发 store.pokeActive()，让 store 保持高频档；
+// 30s 无交互后 store 自动降回 idle 间隔。
+// 不监听 click：点击路径本身会调用 refresh/acquireActive，无需额外 poke。
+
+export const INTERACTION_EVENTS = Object.freeze([
+  'mousemove', 'mousedown', 'wheel', 'scroll', 'keydown', 'touchstart',
+])
+
+/**
+ * @param {{pokeActive: Function}} store
+ * @param {{target?: EventTarget|null, throttleMs?: number, now?: () => number,
+ *   timers?: {setTimeout: Function, clearTimeout: Function}}} [options]
+ * @returns {() => void} dispose
+ */
+export function installInteractionPoke(store, options = {}) {
+  const target = options.target ?? (typeof window !== 'undefined' ? window : null)
+  if (target === null || target === undefined || typeof target.addEventListener !== 'function') {
+    return () => {}
+  }
+  const throttleMs = Math.max(0, Number(options.throttleMs) || 1_000)
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  const timers = options.timers ?? { setTimeout, clearTimeout }
+  let lastPokeAt = 0
+  let trailing = null
+  let disposed = false
+
+  const fire = () => {
+    if (disposed) return
+    lastPokeAt = now()
+    store.pokeActive()
+  }
+
+  const onEvent = () => {
+    if (disposed) return
+    const elapsed = now() - lastPokeAt
+    if (elapsed >= throttleMs) { fire(); return }
+    if (trailing !== null) return
+    trailing = timers.setTimeout(() => {
+      trailing = null
+      fire()
+    }, throttleMs - elapsed)
+    trailing?.unref?.()
+  }
+
+  for (const eventName of INTERACTION_EVENTS) target.addEventListener(eventName, onEvent, { passive: true })
+
+  return () => {
+    disposed = true
+    for (const eventName of INTERACTION_EVENTS) {
+      try { target.removeEventListener(eventName, onEvent) } catch { /* 已移除 */ }
+    }
+    if (trailing !== null) {
+      timers.clearTimeout(trailing)
+      trailing = null
+    }
+  }
+}