dsh-jace-remote 0.2.1

package/src/index.js

@@ -0,0 +1,263 @@
+// dsh-jace-remote — dsh 插件入口
+//
+// 职责：在 dsh web 进程内起一个局域网网关（默认 0.0.0.0:3081），
+//       用动态 4 位数字配对放行设备，再反向代理到本机 dsh web（127.0.0.1:<webServer.port>）。
+//
+// 注意：本文件 import 了 @deepseek-ai/*，因此**安装目录必须位于
+//       $DSH_HOME/profiles/<profile>/ 树内**（Node ESM 按 realpath 解析）；
+//       开发目录在工作区，安装由 scripts/install.mjs 负责拷贝。
+import { mkdirSync, writeFileSync, chmodSync } from 'node:fs'
+import { homedir, networkInterfaces } from 'node:os'
+import { dirname, join } from 'node:path'
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { PairingManager } from './pairing.js'
+import { DeviceStore } from './devices.js'
+import { UpstreamAuth } from './upstream.js'
+import { createGateway } from './gateway.js'
+
+export const name = 'dsh-jace-remote'
+
+// connection 用于拿带 launch token 的 loopback URL；tools 用于注册 agent 工具
+export const inject = ['webServer', 'connection', 'tools']
+
+export const Config = z.object({
+  enabled: z.boolean().default(true),
+  /** 网关自身监听地址（不是 dsh web 的 bind）；0.0.0.0 = 局域网可访问 */
+  bindHost: z.string().default('0.0.0.0'),
+  port: z.number().step(1).min(1).max(65535).default(3081),
+  codeTtlSeconds: z.number().step(1).min(30).default(300),
+  sessionTtlHours: z.number().step(1).min(1).default(168),
+  maxAttemptsPerWindow: z.number().step(1).min(1).default(5),
+  rateWindowMinutes: z.number().step(1).min(1).default(10),
+  /** 是否把配对码打到 dsh 日志（本机终端） */
+  logCodes: z.boolean().default(true),
+  /** 只接受私网来源 */
+  allowPrivateOnly: z.boolean().default(true),
+  /** 空 = $DSH_HOME/jace-remote/state.json */
+  stateFile: z.string().default(''),
+})
+
+export function apply(ctx, config) {
+  const log = ctx.logger('jace-remote')
+  if (!config.enabled) {
+    log.info('dsh-jace-remote disabled by config')
+    return
+  }
+
+  const upstreamPort = ctx.webServer.port
+  const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+  const stateDir = join(home, 'jace-remote')
+  const stateFile = config.stateFile || join(stateDir, 'state.json')
+  const pairingFile = join(dirname(stateFile), 'pairing.json')
+
+  const pairing = new PairingManager({
+    codeTtlSeconds: config.codeTtlSeconds,
+    maxAttemptsPerWindow: config.maxAttemptsPerWindow,
+    rateWindowMinutes: config.rateWindowMinutes,
+  })
+  const devices = new DeviceStore({ filePath: stateFile, sessionTtlHours: config.sessionTtlHours })
+  const upstreamAuth = new UpstreamAuth({
+    getAuthenticatedUrl: () => ctx.connection.authenticatedUrl(`http://127.0.0.1:${String(upstreamPort)}`),
+    log: (m) => log.debug(m),
+  })
+
+  const gateway = createGateway({
+    host: config.bindHost,
+    port: config.port,
+    upstreamPort,
+    pairing,
+    devices,
+    upstreamAuth,
+    allowPrivateOnly: config.allowPrivateOnly,
+    log: (m) => log.info(m),
+  })
+
+  let lastCode = null
+  let listening = null
+
+  function persistCode(cur) {
+    try {
+      mkdirSync(dirname(pairingFile), { recursive: true, mode: 0o700 })
+      writeFileSync(pairingFile, JSON.stringify({ code: cur.code, expiresAt: cur.expiresAt, updatedAt: Date.now() }), { mode: 0o600 })
+      chmodSync(pairingFile, 0o600)
+    } catch (err) {
+      log.warn(`cannot persist pairing code: ${err?.message || err}`)
+    }
+  }
+
+  function announce(force = false) {
+    const cur = pairing.current()
+    if (!force && cur.code === lastCode) return cur
+    lastCode = cur.code
+    persistCode(cur)
+    if (config.logCodes) log.info(`pairing code ${cur.code} (expires in ${Math.round(cur.remainingMs / 1000)}s)`)
+    return cur
+  }
+
+  /** 取一个私网 IPv4，拼出给手机用的 URL。 */
+  function lanUrl() {
+    for (const list of Object.values(networkInterfaces())) {
+      for (const iface of list ?? []) {
+        if (iface.family !== 'IPv4' || iface.internal) continue
+        if (/^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(iface.address)) {
+          return `http://${iface.address}:${typeof gateway.port === 'number' ? gateway.port : config.port}/`
+        }
+      }
+    }
+    return `http://<本机IP>:${config.port}/`
+  }
+
+  // 生命周期：起停网关 + 轮换/展示配对码（webServer.register 要包 effect，自建 server 同理）
+  ctx.effect(() => {
+    gateway.start().then((info) => { listening = info }).catch((err) => log.error(`gateway start failed: ${err?.message || err}`))
+    announce(true)
+    const timer = setInterval(() => announce(), 10_000)
+    return async () => {
+      clearInterval(timer)
+      await Promise.race([gateway.stop(), new Promise((r) => setTimeout(r, 2000))])
+      log.info('gateway stopped')
+    }
+  }, 'jace-remote: lan gateway')
+
+  /** 供设置页 / agent 工具共用的状态快照。 */
+  function statusPayload() {
+    const cur = pairing.current()
+    return {
+      code: cur.code,
+      expiresAt: cur.expiresAt,
+      expiresInSeconds: Math.round(cur.remainingMs / 1000),
+      lanUrl: lanUrl(),
+      listening: Boolean(listening),
+      gatewayPort: config.port,
+      devices: devices.list(),
+    }
+  }
+
+  // 设置页读取入口：挂在本机 dsh web（127.0.0.1:<webServer.port>）上，同源、受 dsh 自身访问控制保护。
+  // LAN 网关只对「已配对」设备转发此路径，未配对设备拿不到配对码。
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/__jace/remote/status',
+    handler: (_req, res) => {
+      res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+      res.end(JSON.stringify(statusPayload()))
+    },
+  }), 'jace-remote: settings status route')
+
+  // ── agent 工具 ───────────────────────────────────────────────
+  ctx.tools.register(defineTool({
+    name: 'jace_remote_code',
+    description: '获取 dsh-jace-remote 的当前 4 位配对码与局域网访问地址（用于在手机/其他设备上配对 dsh web）。',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          code: { type: 'string', required: true },
+          expiresInSeconds: { type: 'integer', required: true },
+          url: { type: 'string', required: true },
+          listening: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `配对码：${value.code}（${value.expiresInSeconds}s 后过期）\n局域网地址：${value.url}\n网关状态：${value.listening ? 'listening' : 'not listening'}`,
+      }],
+    },
+    async execute() {
+      const cur = announce(true)
+      return {
+        code: cur.code,
+        expiresInSeconds: Math.round(cur.remainingMs / 1000),
+        url: lanUrl(),
+        listening: Boolean(listening),
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'jace_remote_devices',
+    description: '列出已通过配对码授权的局域网设备（含 id / 名称 / IP / 最后活跃 / 过期时间）。',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          count: { type: 'integer', required: true },
+          devices: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                id: { type: 'string', required: true },
+                name: { type: 'string', required: true },
+                ip: { type: 'string', required: true },
+                lastSeenAt: { type: 'integer', required: true },
+                expiresAt: { type: 'integer', required: true },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: value.count === 0
+          ? '当前没有已配对设备。'
+          : value.devices.map((d) => `· ${d.id} ${d.name} ${d.ip} 最后活跃 ${new Date(d.lastSeenAt).toLocaleString()}`).join('\n'),
+      }],
+    },
+    async execute() {
+      const list = devices.list()
+      return { count: list.length, devices: list }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'jace_remote_revoke',
+    description: '撤销一个已配对的局域网设备（写入操作）。传入 jace_remote_devices 返回的设备 id。',
+    parameters: {
+      id: { type: 'string', required: true, description: '设备 id' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          revoked: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.revoked ? '已撤销该设备。' : '未找到该设备 id。' }],
+    },
+    async execute(args) {
+      return { revoked: devices.revoke(args.id) }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'jace_remote_panic',
+    description: '紧急关闭局域网网关（停止监听 3081，已配对设备立即断连）。需要重新启用时重启 dsh web 或改回配置。',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: { stopped: { type: 'boolean', required: true } },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.stopped ? '局域网网关已关闭。' : '网关未在运行。' }],
+    },
+    async execute() {
+      const wasListening = Boolean(listening)
+      await gateway.stop()
+      listening = null
+      log.warn('gateway stopped by jace_remote_panic')
+      return { stopped: wasListening }
+    },
+  }))
+
+  log.info(`dsh-jace-remote ready → upstream 127.0.0.1:${String(upstreamPort)}, lan ${config.bindHost}:${String(config.port)}`)
+}

package/src/pairing.js

@@ -0,0 +1,98 @@
+// dsh-jace-remote — 动态 4 位配对码：生成 / 轮换 / 校验 / 限速（纯逻辑，无 IO，可单测）
+import { randomInt, timingSafeEqual } from 'node:crypto'
+
+const CODE_RE = /^\d{4}$/
+
+export class PairingManager {
+  /**
+   * @param {object} opts
+   * @param {number} [opts.codeTtlSeconds=300]   单个码有效期（秒），到期自动轮换
+   * @param {number} [opts.maxAttemptsPerWindow=5] 每 IP 每窗口允许的失败次数
+   * @param {number} [opts.maxGlobalAttemptsPerWindow=20] 全局失败上限
+   * @param {number} [opts.rateWindowMinutes=10] 限速窗口（分钟）
+   * @param {() => number} [opts.now] 注入时钟（测试用）
+   */
+  constructor(opts = {}) {
+    this.codeTtlMs = (opts.codeTtlSeconds ?? 300) * 1000
+    this.maxAttempts = opts.maxAttemptsPerWindow ?? 5
+    this.maxGlobalAttempts = opts.maxGlobalAttemptsPerWindow ?? 20
+    this.rateWindowMs = (opts.rateWindowMinutes ?? 10) * 60_000
+    this.now = opts.now ?? (() => Date.now())
+
+    /** @type {Map<string, number[]>} ip -> 失败时间戳 */
+    this.failuresByIp = new Map()
+    /** @type {number[]} 全局失败时间戳 */
+    this.failuresGlobal = []
+    /** @type {string|null} */
+    this.code = null
+    this.expiresAt = 0
+    this.rotate()
+  }
+
+  /** 生成新码（旧码立即失效）。返回 {code, expiresAt}。 */
+  rotate() {
+    this.code = String(randomInt(0, 10_000)).padStart(4, '0')
+    this.expiresAt = this.now() + this.codeTtlMs
+    return { code: this.code, expiresAt: this.expiresAt }
+  }
+
+  /** 当前码与剩余时间（过期则自动轮换）。 */
+  current() {
+    if (this.now() >= this.expiresAt) this.rotate()
+    return { code: this.code, expiresAt: this.expiresAt, remainingMs: Math.max(0, this.expiresAt - this.now()) }
+  }
+
+  _prune(list, cutoff) {
+    while (list.length > 0 && list[0] < cutoff) list.shift()
+  }
+
+  _rateState(ip) {
+    const cutoff = this.now() - this.rateWindowMs
+    this._prune(this.failuresGlobal, cutoff)
+    const list = this.failuresByIp.get(ip) ?? []
+    this._prune(list, cutoff)
+    this.failuresByIp.set(ip, list)
+    return list
+  }
+
+  /** 该 ip 当前是否已被限速。 */
+  isRateLimited(ip) {
+    const list = this._rateState(ip)
+    return list.length >= this.maxAttempts || this.failuresGlobal.length >= this.maxGlobalAttempts
+  }
+
+  _recordFailure(ip) {
+    const list = this._rateState(ip)
+    list.push(this.now())
+    this.failuresGlobal.push(this.now())
+  }
+
+  /**
+   * 校验配对码。
+   * @param {unknown} input 用户输入的 4 位码
+   * @param {string} ip 来源 IP（用于限速）
+   * @returns {{ok: true} | {ok: false, reason: 'rate-limited'|'malformed'|'invalid'|'expired'}}
+   */
+  verify(input, ip = 'unknown') {
+    if (this.isRateLimited(ip)) return { ok: false, reason: 'rate-limited' }
+    if (typeof input !== 'string' || !CODE_RE.test(input)) {
+      this._recordFailure(ip)
+      return { ok: false, reason: 'malformed' }
+    }
+    if (this.now() >= this.expiresAt) {
+      this.rotate()
+      this._recordFailure(ip)
+      return { ok: false, reason: 'expired' }
+    }
+    const a = Buffer.from(input, 'utf8')
+    const b = Buffer.from(this.code, 'utf8')
+    if (a.length !== b.length || !timingSafeEqual(a, b)) {
+      this._recordFailure(ip)
+      return { ok: false, reason: 'invalid' }
+    }
+    // 成功：单次有效 → 立即作废并换新码
+    this.rotate()
+    this.failuresByIp.delete(ip)
+    return { ok: true }
+  }
+}

package/src/upstream.js

@@ -0,0 +1,62 @@
+// dsh-jace-remote — dsh 上游认证：用 launch token 换 dsh 会话 cookie，供代理注入
+//
+// 为什么需要：dsh web 的会话 cookie 绑定 authority(host:port)，LAN 浏览器拿不到、也不该拿。
+// 网关在进程内用 connection.authenticatedUrl() 拿带 token 的 loopback URL，换出 cookie 自用。
+
+export class UpstreamAuth {
+  /**
+   * @param {object} opts
+   * @param {() => (string|Promise<string>)} opts.getAuthenticatedUrl 返回带 token 的 loopback URL
+   * @param {(msg: string) => void} [opts.log]
+   */
+  constructor({ getAuthenticatedUrl, log = () => {} }) {
+    this.getAuthenticatedUrl = getAuthenticatedUrl
+    this.log = log
+    this.cookie = null
+    this.refreshing = null
+  }
+
+  /** 确保有可用 cookie（并发去重）。 */
+  async ensure() {
+    if (this.cookie) return this.cookie
+    if (!this.refreshing) {
+      this.refreshing = this._exchange().finally(() => { this.refreshing = null })
+    }
+    return this.refreshing
+  }
+
+  /** 上游返回 401 时调用：丢弃旧 cookie，重新换一次。 */
+  async refresh() {
+    this.cookie = null
+    return this.ensure()
+  }
+
+  invalidate() {
+    this.cookie = null
+  }
+
+  async _exchange() {
+    const url = await this.getAuthenticatedUrl()
+    const res = await fetch(url, { redirect: 'manual' })
+    const cookies = typeof res.headers.getSetCookie === 'function' ? res.headers.getSetCookie() : []
+    const first = cookies.find((c) => typeof c === 'string' && c.includes('='))
+    if (!first) {
+      this.log(`upstream auth: no Set-Cookie from ${redact(url)} (status ${res.status})`)
+      return null
+    }
+    this.cookie = first.split(';')[0]
+    this.log(`upstream auth: session cookie acquired (${this.cookie.split('=')[0]}=…)`)
+    return this.cookie
+  }
+}
+
+/** 去掉 query 里的 token，避免日志泄露。 */
+function redact(url) {
+  try {
+    const u = new URL(url)
+    if (u.searchParams.has('token')) u.searchParams.set('token', '***')
+    return u.href
+  } catch {
+    return '<invalid-url>'
+  }
+}