@twinsearth/dsh-master 0.0.0-stage → 3.2.9

package/src/superagent/bridge-tokens.ts

@@ -0,0 +1,236 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+
+/**
+ * 桥 token 的自动轮换与审计（v3.2.5）。
+ *
+ * 覆盖母体↔原身派发桥（`POST /dsh-master/api/bridge/spawn`）使用的 `bridgeToken`：
+ *   * 自动轮换：按 `rotateMs` 周期性签发新 token；
+ *   * 宽限重叠：旧 token 在 `graceMs` 内仍可用，避免在途请求瞬间失败；
+ *   * 持久化：只落 **sha256 摘要**（不是明文），进程重启后仍可用；
+ *   * 审计：动作 + token 摘要前缀写入 `token-audit.jsonl`（append-only），不含明文；
+ *   * 常量时间比较，避免时序侧信道。
+ *
+ * 静态配置的 `bridgeToken` 仍然可用（作为“长期 token”参与校验），便于旧部署平滑升级。
+ */
+
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const DEFAULT_ROTATE_MS = 30 * 60_000
+const DEFAULT_GRACE_MS = 5 * 60_000
+const DEFAULT_AUDIT_LIMIT = 500
+
+function nowOf(clock) {
+  return typeof clock === 'function' ? clock() : Date.now()
+}
+
+function digestOf(token) {
+  return crypto.createHash('sha256').update(String(token ?? ''), 'utf8').digest('hex')
+}
+
+function safeEqualHex(a, b) {
+  const left = String(a ?? '')
+  const right = String(b ?? '')
+  if (!left || left.length !== right.length) return false
+  try {
+    return crypto.timingSafeEqual(Buffer.from(left, 'hex'), Buffer.from(right, 'hex'))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @param {object} [options]
+ * @param {string} [options.staticToken] 配置里的长期 token（可选）
+ * @param {number} [options.rotateMs] 自动轮换周期（0 = 关闭）
+ * @param {number} [options.graceMs] 旧 token 宽限
+ * @param {string} [options.dataDir] 持久化目录（空 = 仅内存）
+ * @param {boolean} [options.persist=true]
+ * @param {() => number} [options.clock]
+ */
+export function createBridgeTokenManager(options = {}) {
+  const staticToken = String(options.staticToken ?? '').trim()
+  const rotateMs = Math.max(0, Number(options.rotateMs ?? DEFAULT_ROTATE_MS) || 0)
+  const graceMs = Math.max(0, Number(options.graceMs ?? DEFAULT_GRACE_MS) || 0)
+  const dataDir = String(options.dataDir ?? '').trim()
+  const persist = dataDir !== '' && options.persist !== false
+  const auditLimit = Math.max(10, Number(options.auditLimit ?? DEFAULT_AUDIT_LIMIT))
+  const clock = typeof options.clock === 'function' ? options.clock : () => Date.now()
+
+  /** @type {{id:string,digest:string,issuedAt:number,retireAt:number|null}[]} */
+  let entries = []
+  const auditLog = []
+  const counters = { issued: 0, rotated: 0, verified: 0, rejected: 0, expired: 0 }
+  let timer = null
+  let lastRotatedAt = 0
+
+  const storageFile = persist ? path.join(dataDir, 'bridge-tokens.json') : ''
+  const auditFile = persist ? path.join(dataDir, 'token-audit.jsonl') : ''
+
+  const audit = (action, detail = {}) => {
+    const record = Object.freeze({ at: nowOf(clock), scope: 'bridge', action, ...detail })
+    auditLog.push(record)
+    if (auditLog.length > auditLimit) auditLog.splice(0, auditLog.length - auditLimit)
+    if (auditFile) {
+      try {
+        fs.mkdirSync(path.dirname(auditFile), { recursive: true })
+        fs.appendFileSync(auditFile, JSON.stringify(record) + '\n', { mode: 0o600 })
+      } catch { /* 审计落盘失败不影响鉴权 */ }
+    }
+    return record
+  }
+
+  const persistNow = () => {
+    if (!storageFile) return
+    try {
+      fs.mkdirSync(path.dirname(storageFile), { recursive: true })
+      const payload = { version: 1, savedAt: nowOf(clock), entries }
+      fs.writeFileSync(storageFile, JSON.stringify(payload, null, 2), { mode: 0o600 })
+    } catch { /* 落盘失败：退化为内存态 */ }
+  }
+
+  const loadPersisted = () => {
+    if (!storageFile) return
+    try {
+      const raw = fs.readFileSync(storageFile, 'utf8')
+      const parsed = JSON.parse(raw)
+      if (Array.isArray(parsed?.entries)) {
+        entries = parsed.entries
+          .filter((item) => typeof item?.digest === 'string' && /^[0-9a-f]{64}$/.test(item.digest))
+          .map((item) => ({
+            id: String(item.id ?? item.digest.slice(0, 8)),
+            digest: item.digest,
+            issuedAt: Number(item.issuedAt ?? 0),
+            retireAt: item.retireAt == null ? null : Number(item.retireAt),
+          }))
+        audit('load', { count: entries.length })
+      }
+    } catch { /* 首次运行或文件损坏：从空开始 */ }
+  }
+
+  const issue = (detail = {}) => {
+    const token = crypto.randomBytes(24).toString('hex')
+    const digest = digestOf(token)
+    const entry = { id: digest.slice(0, 8), digest, issuedAt: nowOf(clock), retireAt: null }
+    entries.push(entry)
+    counters.issued += 1
+    audit('issue', { tokenId: entry.id, ...detail })
+    persistNow()
+    return { token, tokenId: entry.id, issuedAt: entry.issuedAt }
+  }
+
+  const sweep = () => {
+    const now = nowOf(clock)
+    const kept = []
+    let removed = 0
+    for (const entry of entries) {
+      if (entry.retireAt !== null && now >= entry.retireAt) {
+        removed += 1
+        counters.expired += 1
+        audit('expire', { tokenId: entry.id })
+      } else {
+        kept.push(entry)
+      }
+    }
+    if (removed > 0) {
+      entries = kept
+      persistNow()
+    }
+    return removed
+  }
+
+  /**
+   * 轮换：签发新 token，旧的活动 token 进入宽限期。
+   * @param {{reason?:string}} [detail]
+   */
+  const rotate = (detail = {}) => {
+    const now = nowOf(clock)
+    for (const entry of entries) {
+      if (entry.retireAt === null) entry.retireAt = now + graceMs
+    }
+    const issued = issue({ reason: detail.reason ?? 'auto-rotate' })
+    counters.rotated += 1
+    lastRotatedAt = now
+    rotateCount += 1
+    persistNow()
+    return { ...issued, graceMs }
+  }
+  let rotateCount = 0
+
+  const verify = (token) => {
+    const presented = digestOf(token)
+    const now = nowOf(clock)
+    if (staticToken && safeEqualHex(presented, digestOf(staticToken))) {
+      counters.verified += 1
+      audit('verify-ok', { tokenId: 'static', source: 'static' })
+      return { ok: true, tokenId: 'static', source: 'static' }
+    }
+    let expiredMatch = null
+    for (const entry of entries) {
+      if (!safeEqualHex(entry.digest, presented)) continue
+      if (entry.retireAt !== null && now >= entry.retireAt) {
+        expiredMatch = entry
+        continue
+      }
+      counters.verified += 1
+      audit('verify-ok', { tokenId: entry.id, source: entry.retireAt === null ? 'active' : 'grace' })
+      return { ok: true, tokenId: entry.id, source: entry.retireAt === null ? 'active' : 'grace' }
+    }
+    counters.rejected += 1
+    const reason = expiredMatch ? 'token-expired' : presented === digestOf('') ? 'token-missing' : 'token-unknown'
+    audit('verify-fail', { reason, ...(expiredMatch ? { tokenId: expiredMatch.id } : {}) })
+    return { ok: false, reason }
+  }
+
+  const describe = () => {
+    const now = nowOf(clock)
+    return {
+      enabled: Boolean(staticToken) || entries.length > 0,
+      staticToken: Boolean(staticToken),
+      rotateMs,
+      graceMs,
+      autoRotate: rotateMs > 0,
+      persist,
+      tokens: entries.map((entry) => ({
+        tokenId: entry.id,
+        issuedAt: entry.issuedAt,
+        retiringAt: entry.retireAt,
+        state: entry.retireAt === null ? 'active' : (now >= entry.retireAt ? 'expired' : 'retiring'),
+      })),
+      nextRotationAt: rotateMs > 0 ? (lastRotatedAt || now) + rotateMs : null,
+      lastRotatedAt: lastRotatedAt || null,
+      rotations: rotateCount,
+      counts: { ...counters },
+    }
+  }
+
+  const start = () => {
+    if (timer || rotateMs <= 0) return false
+    timer = setInterval(() => {
+      try { sweep(); rotate({ reason: 'scheduled' }) } catch { /* 定时轮换失败不致命 */ }
+    }, rotateMs)
+    timer.unref?.()
+    audit('schedule', { rotateMs, graceMs })
+    return true
+  }
+
+  const stop = () => {
+    if (timer) { clearInterval(timer); timer = null; return true }
+    return false
+  }
+
+  loadPersisted()
+  // 有静态 token 或已有持久化 token 时，启动自动轮换才有意义。
+  if ((staticToken || entries.length > 0) && rotateMs > 0 && options.autoStart !== false) start()
+
+  return {
+    issue, verify, rotate, sweep, describe, start, stop,
+    audit: (limit = 50) => auditLog.slice(-Math.max(1, Number(limit) || 50)),
+    staticToken: () => staticToken,
+    /** 一次性接管：轮换后返回新 token（供运维/宿主下发）。 */
+    rotateAndGet: (detail = {}) => rotate(detail).token,
+  }
+}

package/src/superagent/dispatch.ts

@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+
+/**
+ * Router → 瓮城 DerivedManager 的派发适配（v3.2.4）。
+ *
+ * 优先走独立契约 SDK（`@twinsearth/dsh-fang-contract` 的内嵌副本）：
+ *   local（同 Host 的 fangContract 服务）→ http（/fang/api/contract/*）
+ *   → file（文件 outbox 兜底）→ legacy（3.1.x 旧服务键）。
+ * 若契约全部失败，再回退到本包自带的 local forker / 母体 bridge（兼容旧部署）。
+ * 所有路径只传 Ticket + 受限 DSH_MASTER_* env；缺能力时 fail-closed。
+ */
+
+import path from 'node:path'
+
+import { createContractClient } from '../contract/index.js'
+import { FANG_SERVICE, masterError, safeGet } from '../kernel.ts'
+
+const BRIDGE_PATH = '/dsh-master/api/bridge/spawn'
+const ENV_PREFIX = 'DSH_MASTER_'
+
+function asString(value) { return String(value ?? '').trim() }
+
+function filterEnv(env) {
+  const out = {}
+  if (!env || typeof env !== 'object') return out
+  for (const [key, value] of Object.entries(env)) {
+    if (!String(key).startsWith(ENV_PREFIX)) continue
+    if (typeof value !== 'string') continue
+    out[String(key)] = value.slice(0, 32_000)
+  }
+  return out
+}
+
+/**
+ * @param {object} ctx
+ * @param {{dispatch?:{
+ *   homeDir?:string, cliPath?:string, profile?:string,
+ *   motherUrl?:string, motherToken?:string,
+ *   contract?:boolean, contractFileDir?:string, contractOrder?:string[],
+ *   contractTimeoutMs?:number, contractFileTimeoutMs?:number,
+ * }}} [config]
+ * @param {{fetchImpl?:typeof fetch, getOrigin?:()=>string}} [options]
+ */
+export function createFangDispatcher(ctx, config = {}, options = {}) {
+  const raw = config.dispatch && typeof config.dispatch === 'object' ? config.dispatch : {}
+  const homeDir = asString(raw.homeDir)
+  const cliPath = asString(raw.cliPath)
+  const profile = asString(raw.profile) || 'default'
+  const motherUrl = asString(raw.motherUrl).replace(/\/+$/, '')
+  const motherToken = asString(raw.motherToken)
+  const motherAuthToken = asString(raw.motherAuthToken)
+  // v3.2.5：essence 运行态由瓮城注入 DSH_FANG_MOTHER（母体 dataDir）；
+  // 默认用共享 contract-outbox 作为跨进程 file bridge，无需手工配置 URL。
+  const motherDataDir = asString(process.env.DSH_FANG_MOTHER)
+  const contractFileDir = asString(raw.contractFileDir) || (motherDataDir ? path.join(motherDataDir, 'contract-outbox') : '')
+  // 派发超时必须覆盖母体 fork 预置（provision 常需 10–30s）；默认 180s，可由 dispatch 配置覆盖。
+  const contractTimeoutMs = Math.max(5_000, Number(raw.contractTimeoutMs ?? 180_000) || 180_000)
+  const contractFileTimeoutMs = Math.max(5_000, Number(raw.contractFileTimeoutMs ?? contractTimeoutMs) || contractTimeoutMs)
+  const workerEnv = raw.workerEnv && typeof raw.workerEnv === 'object' ? raw.workerEnv : {}
+  const fetchImpl = options.fetchImpl ?? fetch
+  const contractEnabled = raw.contract === true || Boolean(contractFileDir)
+  const contractClient = contractEnabled
+    ? createContractClient({
+        ctx,
+        config: {
+          httpBaseUrl: motherUrl,
+          httpToken: motherToken,
+          httpHeaders: motherAuthToken ? { 'x-fang-auth': motherAuthToken } : undefined,
+          fileDir: contractFileDir,
+          timeoutMs: contractTimeoutMs,
+          fileTimeoutMs: contractFileTimeoutMs,
+          order: Array.isArray(raw.contractOrder) ? raw.contractOrder : undefined,
+        },
+        fetchImpl,
+      })
+    : null
+
+  const resolveForker = () => {
+    const forker = safeGet(ctx, FANG_SERVICE.forker)
+    return forker && typeof forker.spawn === 'function' ? forker : null
+  }
+  const localReady = () => Boolean(resolveForker() && homeDir && cliPath)
+  const bridgeReady = () => Boolean(motherUrl && motherToken)
+  const contractReady = () => Boolean(contractClient && contractClient.transports().length > 0)
+  const available = () => contractReady() || localReady() || bridgeReady()
+  const mode = () => {
+    if (contractReady()) return 'contract'
+    if (localReady()) return 'local'
+    if (bridgeReady()) return 'bridge'
+    return 'none'
+  }
+  const describe = () => ({
+    mode: mode(),
+    forker: Boolean(resolveForker()),
+    homeDir: Boolean(homeDir),
+    cliPath: Boolean(cliPath),
+    profile,
+    bridgeUrl: motherUrl ? `${motherUrl}${BRIDGE_PATH}` : null,
+    bridgeConfigured: Boolean(motherUrl && motherToken),
+    contract: contractClient ? { ...contractClient.describe(), attempts: contractClient.attempts?.() ?? [] } : null,
+    contractFileDir: contractFileDir || null,
+    contractTimeoutMs,
+    contractFileTimeoutMs,
+    workerEnvKeys: Object.keys(workerEnv).filter((key) => String(key).startsWith('WORKER_') || String(key).startsWith('DSH_MASTER_')),
+    available: available(),
+    reason: available() ? null : (!resolveForker() && !bridgeReady() && !contractReady() ? 'fang-forker-unavailable' : 'dispatch-config-incomplete'),
+  })
+
+  const baseEnv = (ticket) => {
+    const env = {
+      DSH_MASTER_TICKET: JSON.stringify(ticket),
+      DSH_MASTER_TICKET_ID: String(ticket?.id ?? ''),
+      DSH_MASTER_TRUST_MODE: 'auto',
+      DSH_MASTER_MANDATE_SCOPE: String(ticket?.mandate?.scope ?? ''),
+    }
+    for (const [key, value] of Object.entries(workerEnv)) {
+      if (!String(key).startsWith('WORKER_') && !String(key).startsWith('DSH_MASTER_')) continue
+      if (typeof value === 'string') env[String(key)] = value
+    }
+    return env
+  }
+
+  return {
+    available,
+    describe,
+    /**
+     * @param {object} ticket
+     * @param {Record<string,string>} [extraEnv] 仅 DSH_MASTER_* 会被下发
+     */
+    async dispatch(ticket, extraEnv = {}) {
+      const env = { ...baseEnv(ticket), ...filterEnv(extraEnv) }
+      let contractFailure = null
+      if (contractReady()) {
+        const params = {
+          homeDir: homeDir || undefined,
+          cliPath: cliPath || undefined,
+          profile,
+          taskTitle: `SuperAgent ${String(ticket?.id ?? '')}`,
+          env,
+        }
+        const result = await contractClient.spawnFork(params, { idempotencyKey: String(ticket?.id ?? '') })
+        if (result.ok) {
+          return {
+            ok: true,
+            model: `contract:${result.transport}`,
+            fork: result.response?.result ?? result.response,
+            transport: result.transport,
+          }
+        }
+        contractFailure = result
+      }
+      if (localReady()) {
+        try {
+          const fork = await resolveForker().spawn({
+            homeDir, cliPath, profile,
+            taskTitle: `SuperAgent ${String(ticket?.id ?? '')}`,
+            env,
+          })
+          if (fork && fork.ok === false) return masterError('fang-spawn-failed', 'fangForker.spawn returned an error', fork)
+          return { ok: true, model: 'local', fork }
+        } catch (error) {
+          return masterError('fang-spawn-threw', String(error?.message ?? error))
+        }
+      }
+      if (bridgeReady()) {
+        try {
+          const response = await fetchImpl(`${motherUrl}${BRIDGE_PATH}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${motherToken}` },
+            body: JSON.stringify({ ticket, env }),
+          })
+          const text = await response.text()
+          let body = null
+          try { body = JSON.parse(text) } catch { body = null }
+          if (!response.ok || !body || body.ok !== true) {
+            return masterError('bridge-spawn-failed', `mother bridge rejected spawn (HTTP ${response.status})`, body ? { code: body.code ?? null, error: body.error ?? null } : null)
+          }
+          return { ok: true, model: 'bridge', fork: body.fork }
+        } catch (error) {
+          return masterError('bridge-spawn-threw', String(error?.message ?? error))
+        }
+      }
+      if (contractFailure) {
+        return masterError(
+          'contract-dispatch-failed',
+          'all fang-master contract transports failed and no local/bridge fallback is available',
+          { code: contractFailure.code ?? null, failures: contractFailure.failures ?? null, attempts: contractFailure.attempts ?? null },
+        )
+      }
+      return masterError('dispatch-unavailable', 'no fang contract transport, local fangForker or mother bridge configured')
+    },
+  }
+}
+
+export { BRIDGE_PATH, ENV_PREFIX, filterEnv }

package/src/superagent/feishu.ts

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+
+/**
+ * 飞书事件源适配（v3.2.1）：challenge / verification token + 归一化为 SourceEvent。
+ *
+ * 当前只处理明文 `im.message.receive_v1` 文本消息；加密事件（Encrypt Key）在
+ * 3.2.2 接入。token 未配置时 fail-closed。
+ */
+
+import crypto from 'node:crypto'
+import { truncateText } from './types.ts'
+
+/** 飞书 Encrypt Key：SHA-256(key) 作为 AES-256-CBC 密钥，密文前 16 字节为 IV。 */
+export function decryptFeishuPayload(encrypted, encryptKey) {
+  const key = String(encryptKey ?? '')
+  const value = String(encrypted ?? '')
+  if (!key) throw new Error('feishu-encrypt-key-missing')
+  if (!value) throw new Error('feishu-encrypt-payload-missing')
+  const packed = Buffer.from(value, 'base64')
+  if (packed.length <= 16 || packed.length % 16 !== 0) throw new Error('feishu-encrypt-payload-invalid')
+  const keyBytes = crypto.createHash('sha256').update(key, 'utf8').digest()
+  const decipher = crypto.createDecipheriv('aes-256-cbc', keyBytes, packed.subarray(0, 16))
+  decipher.setAutoPadding(true)
+  const text = Buffer.concat([decipher.update(packed.subarray(16)), decipher.final()]).toString('utf8')
+  const parsed = JSON.parse(text)
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('feishu-decrypted-payload-invalid')
+  return parsed
+}
+
+/**
+ * 飞书 verification token 校验（大小写/空白严格比较）。
+ * @returns {{ok:boolean, code?:string}}
+ */
+export function verifyFeishuToken(payload, verificationToken) {
+  if (!verificationToken) return { ok: false, code: 'feishu-token-missing' }
+  const token = String(payload?.header?.token ?? payload?.token ?? '')
+  if (!token) return { ok: false, code: 'feishu-token-missing' }
+  return token === String(verificationToken) ? { ok: true } : { ok: false, code: 'feishu-token-mismatch' }
+}
+
+/**
+ * 飞书事件归一化。challenge 由 handleFeishuWebhook 处理；本函数只处理消息事件。
+ * @param {object} payload
+ * @param {{mentionHandles?:string[]}} [options]
+ */
+export function normalizeFeishuEvent(payload, options = {}) {
+  const body = payload && typeof payload === 'object' ? payload : {}
+  const eventType = String(body.header?.event_type ?? '')
+  if (eventType !== 'im.message.receive_v1') return null
+  const event = body.event && typeof body.event === 'object' ? body.event : {}
+  const message = event.message && typeof event.message === 'object' ? event.message : {}
+  if (String(message.message_type ?? '') !== 'text') return null
+  let text = ''
+  try {
+    const parsed = JSON.parse(String(message.content ?? '{}'))
+    text = String(parsed?.text ?? '')
+  } catch {
+    return null
+  }
+  const content = truncateText(text).trim()
+  const actor = String(event.sender?.sender_id?.open_id ?? event.sender?.sender_id?.user_id ?? '').trim()
+  const chatId = String(message.chat_id ?? '').trim()
+  const messageId = String(message.message_id ?? '').trim()
+  if (!content || !actor || !chatId) return null
+  const mentionHandles = Array.isArray(options.mentionHandles) && options.mentionHandles.length > 0
+    ? options.mentionHandles
+    : ['@dsh', '@superagent']
+  const mentions = Array.isArray(message.mentions) ? message.mentions : []
+  return {
+    eventId: String(body.header?.event_id ?? messageId),
+    sourceId: `feishu:${chatId}`,
+    eventType: 'feishu_message',
+    actor,
+    actorIsBot: String(event.sender?.sender_type ?? '') === 'bot',
+    isMention: mentions.length > 0 || mentionHandles.some((handle) => content.includes(handle)),
+    content,
+    threadId: `feishu:${chatId}:${String(message.thread_id ?? message.root_id ?? messageId)}`,
+    repo: '',
+  }
+}
+
+/**
+ * 处理一次飞书 Webhook：token 校验 → challenge 应答 / SourceEvent。
+ * @returns {{status:number, body:object}}
+ */
+export function handleFeishuWebhook({ payload, verificationToken, mentionHandles, encryptKey } = {}) {
+  let body = payload && typeof payload === 'object' ? payload : {}
+  if (typeof body.encrypt === 'string' && body.encrypt) {
+    try { body = decryptFeishuPayload(body.encrypt, encryptKey) }
+    catch (error) { return { status: 400, body: { ok: false, code: 'feishu-decrypt-failed', error: String(error?.message ?? error) } } }
+  }
+  if (String(body.type ?? '') === 'url_verification') {
+    const verify = verifyFeishuToken(body, verificationToken)
+    if (!verify.ok) return { status: 401, body: { ok: false, code: verify.code } }
+    return { status: 200, body: { challenge: String(body.challenge ?? '') } }
+  }
+  const verify = verifyFeishuToken(body, verificationToken)
+  if (!verify.ok) return { status: 401, body: { ok: false, code: verify.code } }
+  const event = normalizeFeishuEvent(body, { mentionHandles })
+  if (!event) return { status: 204, body: { ok: true, ignored: true } }
+  return { status: 200, body: { ok: true, event } }
+}

package/src/superagent/github.ts

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+
+/**
+ * GitHub 事件源适配（v3.2.1）：Webhook 签名校验 + 归一化为 SourceEvent。
+ *
+ * 外部输入不可信：只有 HMAC-SHA256 签名通过、事件类型受支持、正文非空才进入 Router。
+ * 本模块不做网络请求（Webhook 由 Router 的 HTTP 路由接收）。
+ */
+
+import crypto from 'node:crypto'
+
+import { truncateText } from './types.ts'
+
+export const SUPPORTED_GITHUB_EVENTS = Object.freeze(['issue_comment', 'pull_request_review'])
+
+/** 大小写不敏感地取 header（Node 原生 headers 通常已小写）。 */
+function headerOf(headers, name) {
+  if (!headers || typeof headers !== 'object') return ''
+  const target = String(name).toLowerCase()
+  for (const [key, value] of Object.entries(headers)) {
+    if (String(key).toLowerCase() === target) {
+      if (Array.isArray(value)) return String(value[0] ?? '')
+      return String(value ?? '')
+    }
+  }
+  return ''
+}
+
+/**
+ * 校验 GitHub Webhook 的 `X-Hub-Signature-256`。
+ * secret 为空时 fail-closed（未配置密钥不允许接收事件）。
+ */
+export function verifyGithubSignature(rawBody, signatureHeader, secret) {
+  if (!secret) return { ok: false, code: 'github-secret-missing' }
+  const received = String(signatureHeader ?? '').trim()
+  if (!received.startsWith('sha256=')) return { ok: false, code: 'signature-missing' }
+  const expected = 'sha256=' + crypto.createHmac('sha256', String(secret)).update(rawBody).digest('hex')
+  const a = Buffer.from(expected, 'utf8')
+  const b = Buffer.from(received, 'utf8')
+  if (a.length !== b.length) return { ok: false, code: 'signature-mismatch' }
+  return crypto.timingSafeEqual(a, b) ? { ok: true } : { ok: false, code: 'signature-mismatch' }
+}
+
+/**
+ * 把 GitHub Webhook payload 归一化为 SourceEvent；不支持的事件返回 null。
+ * @param {object} payload JSON body
+ * @param {object} headers HTTP headers
+ * @param {{mentionHandles?:string[]}} [options]
+ */
+export function normalizeGithubWebhook(payload, headers, options = {}) {
+  const eventName = headerOf(headers, 'x-github-event').toLowerCase()
+  if (!SUPPORTED_GITHUB_EVENTS.includes(eventName)) return null
+  const body = payload && typeof payload === 'object' ? payload : {}
+  const repo = String(body.repository?.full_name ?? '').trim()
+  const actor = String(body.sender?.login ?? '').trim()
+  if (!repo || !actor) return null
+  const mentionHandles = Array.isArray(options.mentionHandles) && options.mentionHandles.length > 0
+    ? options.mentionHandles.map((item) => String(item))
+    : ['@dsh', '@superagent']
+  const delivery = headerOf(headers, 'x-github-delivery')
+  let content = ''
+  let threadId = ''
+  let eventType = ''
+  if (eventName === 'issue_comment') {
+    if (String(body.action ?? '') !== 'created') return null
+    content = truncateText(body.comment?.body)
+    const number = body.issue?.number
+    if (number === undefined || number === null) return null
+    threadId = `${repo}#${number}`
+    eventType = 'issue_comment'
+  } else if (eventName === 'pull_request_review') {
+    if (String(body.action ?? '') !== 'submitted') return null
+    content = truncateText(body.review?.body)
+    const number = body.pull_request?.number
+    if (number === undefined || number === null) return null
+    threadId = `${repo}#${number}`
+    eventType = 'pull_request_review'
+  }
+  if (!content.trim()) return null
+  return {
+    eventId: delivery || `gh:${threadId}:${String(body.comment?.id ?? body.review?.id ?? '')}`,
+    sourceId: `github:${repo}`,
+    eventType,
+    actor,
+    actorIsBot: String(body.sender?.type ?? '') === 'Bot',
+    isMention: mentionHandles.some((handle) => content.includes(handle)),
+    content,
+    threadId,
+    repo,
+  }
+}
+
+/**
+ * 处理一次 GitHub Webhook：签名 → 归一化 → SourceEvent（或明确错误）。
+ * @returns {{status:number, body:object}}
+ */
+export function handleGithubWebhook({ rawBody, headers, secret, mentionHandles } = {}) {
+  const verify = verifyGithubSignature(rawBody ?? '', headerOf(headers, 'x-hub-signature-256'), secret)
+  if (!verify.ok) return { status: 401, body: { ok: false, code: verify.code } }
+  let payload = null
+  try {
+    payload = JSON.parse(String(rawBody ?? '{}'))
+  } catch {
+    return { status: 400, body: { ok: false, code: 'invalid-json' } }
+  }
+  const event = normalizeGithubWebhook(payload, headers, { mentionHandles })
+  if (!event) return { status: 204, body: { ok: true, ignored: true } }
+  return { status: 200, body: { ok: true, event } }
+}