dsh-mesh-node 0.0.0-stage → 0.0.1

package/src/core/tls.js

@@ -0,0 +1,160 @@
+/**
+ * TLS：自签证书生成与校验信息读取。
+ *
+ * 为什么需要：樱花穿透的 TCP 隧道默认不加密（只有「访问认证」，没有传输加密），
+ * Bearer token 与所有 MCP 报文都会明文过公网。跨网阶段必须自带 TLS。
+ *
+ * 设计取舍：
+ * - 自签「CA-and-leaf」证书（basicConstraints CA:true + serverAuth EKU），这样对端
+ *   把 cert.pem 当作信任锚（NODE_EXTRA_CA_CERTS）就能通过校验，不需要额外 CA 基础设施。
+ * - SAN 里默认包含 localhost / 127.0.0.1 / 本机 hostname；樱花隧道建好后用
+ *   `--san <节点域名>` 重新生成（或首次生成时一次给全）。
+ * - 私钥 0600 落 `~/.dsh-mesh/tls/key.pem`，不进 git、不进任何快照。
+ */
+
+import { X509Certificate } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { hostname as osHostname } from 'node:os'
+import { join } from 'node:path'
+import selfsigned from 'selfsigned'
+
+/** TLS 文件目录。 */
+export function tlsDir(home) {
+  return join(home, 'tls')
+}
+
+/** 证书路径（可在 config.tls.cert 覆盖）。 */
+export function certPath(home) {
+  return join(tlsDir(home), 'cert.pem')
+}
+
+/** 私钥路径（可在 config.tls.key 覆盖）。 */
+export function keyPath(home) {
+  return join(tlsDir(home), 'key.pem')
+}
+
+/** 是否已生成证书。 */
+export function hasCert(home) {
+  return existsSync(certPath(home)) && existsSync(keyPath(home))
+}
+
+/** 判断字符串是不是 IPv4/IPv6 字面量。 */
+function isIp(value) {
+  return /^(\d{1,3}\.){3}\d{1,3}$/.test(value) || /^[0-9a-f:]+$/i.test(value) && value.includes(':')
+}
+
+/** 构造 SAN 列表：总是包含本机可用的默认项，再合并调用方给的。 */
+export function buildAltNames(extra = []) {
+  const names = new Set(['localhost', '127.0.0.1', osHostname()])
+  for (const item of extra) {
+    const value = String(item).trim()
+    if (value.length > 0) names.add(value)
+  }
+  return [...names].map(value => (isIp(value) ? { type: 7, ip: value } : { type: 2, value }))
+}
+
+/**
+ * 生成自签证书。
+ * @returns {{certPath: string, keyPath: string, info: object}}
+ */
+export async function generateCert({ home, sans = [], days = 825, keySize = 2048, commonName, force = false }) {
+  const dir = tlsDir(home)
+  mkdirSync(dir, { recursive: true })
+  if (!force && hasCert(home)) {
+    return { certPath: certPath(home), keyPath: keyPath(home), info: describeCert(home), reused: true }
+  }
+  const altNames = buildAltNames(sans)
+  const attrs = [{ name: 'commonName', value: commonName ?? `dsh-mesh-${osHostname()}` }]
+  const pems = await selfsigned.generate(attrs, {
+    days,
+    keySize,
+    algorithm: 'sha256',
+    extensions: [
+      { name: 'basicConstraints', cA: true },
+      { name: 'keyUsage', digitalSignature: true, keyEncipherment: true, keyCertSign: true },
+      { name: 'extKeyUsage', serverAuth: true, clientAuth: true },
+      { name: 'subjectAltName', altNames },
+    ],
+  })
+  writeFileSync(certPath(home), pems.cert, { mode: 0o644 })
+  writeFileSync(keyPath(home), pems.private, { mode: 0o600 })
+  return { certPath: certPath(home), keyPath: keyPath(home), info: describeCert(home), reused: false, sans: altNames }
+}
+
+/** 读取证书的人类可读信息（也用于 `tls info`）。 */
+export function describeCert(home) {
+  if (!hasCert(home)) return { present: false }
+  const cert = new X509Certificate(readFileSync(certPath(home)))
+  return {
+    present: true,
+    certPath: certPath(home),
+    keyPath: keyPath(home),
+    subject: cert.subject.replace(/\n/g, ', '),
+    issuer: cert.issuer.replace(/\n/g, ', '),
+    validFrom: cert.validFrom,
+    validTo: cert.validTo,
+    validToDate: new Date(cert.validTo).toISOString(),
+    fingerprint256: cert.fingerprint256,
+    serialNumber: cert.serialNumber,
+    subjectAltName: cert.subjectAltName,
+    selfSigned: cert.subject === cert.issuer,
+  }
+}
+
+/** 供 https.createServer 使用的证书对。路径缺失时抛结构化错误。 */
+export function loadTlsMaterial({ home, cert, key }) {
+  const certFile = cert || certPath(home)
+  const keyFile = key || keyPath(home)
+  if (!existsSync(certFile) || !existsSync(keyFile)) {
+    const error = new Error(`TLS 已启用但缺少证书：${certFile} / ${keyFile}，先跑 \`node src/cli.js tls init\``)
+    error.code = 'E_TLS_MISSING'
+    throw error
+  }
+  return { cert: readFileSync(certFile), key: readFileSync(keyFile), certFile, keyFile }
+}
+
+/**
+ * 证书指纹规范化：大小写无关、去掉冒号/空格，统一成 64 位大写 hex。
+ *
+ * 为什么需要它：`mesh_self` / `tls info` / `pair --code` 打印的是
+ * `AA:BB:...` 形式（X509Certificate.fingerprint256），而 socket 拿到的也是这种，
+ * 但人手工粘贴时常带上小写或漏冒号 —— 直接字符串比较会假失败。
+ */
+export function normalizeFingerprint(value) {
+  const compact = String(value || '')
+    .replace(/[^0-9a-fA-F]/g, '')
+    .toUpperCase()
+  if (compact.length !== 64) {
+    const error = new Error(`证书指纹应为 64 位 hex（SHA-256），收到 ${compact.length} 位`)
+    error.code = 'E_BAD_FINGERPRINT'
+    throw error
+  }
+  return compact
+}
+
+/** 从 TLS socket 上取对端证书指纹，返回规范化的 64 位 hex。 */
+export function fingerprintOfSocket(socket) {
+  const cert = socket?.getPeerCertificate?.()
+  if (!cert || !cert.fingerprint256) {
+    const error = new Error('对端没有提供证书，无法核对指纹')
+    error.code = 'E_NO_PEER_CERT'
+    throw error
+  }
+  return normalizeFingerprint(cert.fingerprint256)
+}
+
+/** 固定指纹校验：expected / actual 都规范化后比较，失败抛 E_PIN_MISMATCH。 */
+export function assertFingerprint(expected, actual) {
+  const want = normalizeFingerprint(expected)
+  const got = normalizeFingerprint(actual)
+  if (want !== got) {
+    const error = new Error(
+      `证书指纹不匹配（可能被中间人替换或证书已轮换）\n  期望 ${want}\n  实际 ${got}`
+    )
+    error.code = 'E_PIN_MISMATCH'
+    error.expected = want
+    error.actual = got
+    throw error
+  }
+  return got
+}

package/src/core/util.js

@@ -0,0 +1,68 @@
+import { execFile } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+
+/** Run a command without a shell; resolves (never rejects) with stdout/stderr/error. */
+export function run(cmd, args, { timeout = 20000, cwd, signal, maxBuffer = 8 * 1024 * 1024 } = {}) {
+  return new Promise((resolvePromise) => {
+    execFile(
+      cmd,
+      args,
+      { cwd, timeout, signal, encoding: 'utf8', windowsHide: true, maxBuffer },
+      (error, stdout, stderr) => {
+        resolvePromise({
+          error,
+          stdout: stdout || '',
+          stderr: stderr || '',
+          code: typeof error?.code === 'number' ? error.code : 0,
+          killed: Boolean(error?.killed),
+          timedOut: Boolean(error?.killed && error?.signal === 'SIGTERM')
+        })
+      }
+    )
+  })
+}
+
+/** Trim a string to a byte budget without splitting a UTF-8 code point badly. */
+export function clip(text, maxBytes) {
+  const buf = Buffer.from(text, 'utf8')
+  if (buf.length <= maxBytes) return { text, truncated: false, bytes: buf.length }
+  return { text: buf.subarray(0, maxBytes).toString('utf8'), truncated: true, bytes: buf.length }
+}
+
+export function sha256(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex')
+}
+
+export function short(text, n = 500) {
+  const s = String(text ?? '')
+  return s.length <= n ? s : s.slice(0, n) + '…'
+}
+
+/** ISO timestamp helper. */
+export function nowIso() {
+  return new Date().toISOString()
+}
+
+/**
+ * Strip a UTF-8 BOM. Windows editors (and PowerShell's Set-Content) love adding one,
+ * and `JSON.parse` chokes on it — a BOM'd config.json used to kill the node at boot.
+ */
+export function stripBom(text) {
+  return String(text).replace(/^\uFEFF/, '')
+}
+
+/** Read a JSON file, tolerating a BOM. */
+export function readJsonFile(path) {
+  return JSON.parse(stripBom(readFileSync(path, 'utf8')))
+}
+
+/** Wrap a promise with a hard timeout so a stuck tool cannot hang a request forever. */
+export function withTimeout(promise, ms, onTimeout) {
+  let timer
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(onTimeout || new Error(`timed out after ${ms}ms`)), ms)
+    timer.unref?.()
+  })
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer))
+}

package/src/e2e-autostart.js

@@ -0,0 +1,58 @@
+// e2e: autostart helper (Windows only). Read-only: never registers/removes a task.
+// Proves (a) status is safe on a clean machine, (b) both mutating paths refuse without --yes,
+// (c) the generated logon command points at this checkout's cli.js.
+import assert from 'node:assert/strict'
+import {
+  TASK_NAME,
+  autostartCommand,
+  autostartInstall,
+  autostartRemove,
+  autostartStatus
+} from './core/autostart.js'
+
+const checks = []
+function check(name, fn) {
+  checks.push({ name, fn })
+}
+
+check('Windows guard / status shape', async () => {
+  if (process.platform !== 'win32') return 'skipped: not win32'
+  const st = await autostartStatus()
+  assert.equal(typeof st.installed, 'boolean')
+  assert.equal(st.name, TASK_NAME)
+  if (st.installed) {
+    assert.ok(st.taskToRun, 'installed task must report taskToRun')
+  } else {
+    assert.ok(typeof st.detail === 'string')
+  }
+  return `installed=${st.installed}`
+})
+
+check('command quotes node + cli.js + port', () => {
+  const cmd = autostartCommand(TASK_NAME, 8124)
+  assert.match(cmd, /^".*node(\.exe)?"/)
+  assert.ok(cmd.includes('cli.js'), 'command must point at the CLI')
+  assert.match(cmd, /serve --port 8124$/)
+  return cmd
+})
+
+check('install refuses without --yes', async () => {
+  await assert.rejects(() => autostartInstall({ yes: false }), /--yes/)
+})
+
+check('remove refuses without --yes', async () => {
+  await assert.rejects(() => autostartRemove({ yes: false }), /--yes/)
+})
+
+let failed = 0
+for (const c of checks) {
+  try {
+    const detail = await c.fn()
+    console.log(`PASS  ${c.name}${detail ? `  (${detail})` : ''}`)
+  } catch (err) {
+    failed += 1
+    console.error(`FAIL  ${c.name}\n      ${err.message}`)
+  }
+}
+console.log(`\n${checks.length - failed}/${checks.length} passed`)
+process.exit(failed === 0 ? 0 : 1)

package/src/e2e-channel.js

@@ -0,0 +1,384 @@
+import { createServer } from 'node:http'
+import { mkdtempSync, rmSync, writeFileSync, utimesSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { WebSocketServer } from 'ws'
+import { Client } from '@modelcontextprotocol/client'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/client'
+import { DshWebClient, DshError } from './core/ds-web.js'
+import { defaultConfig, loadSecrets, configPath } from './core/config.js'
+import { startMeshServer } from './server.js'
+
+/**
+ * Protocol-level end-to-end test for the M3 channel (route A).
+ *
+ * A mock stand-in for `dsh web` speaks the exact wire shapes from
+ * apps/web/tests/smoke-real.e2e.ts (launch URL -> 303 + cookie, POST /api/<method>,
+ * session/list|create|prompt|page|cancel) so the client and the channel tools can be
+ * exercised without booting a real model instance.
+ *
+ * Usage: node src/e2e-channel.js
+ */
+
+const quiet = { debug() {}, info() {}, warn() {}, error() {} }
+const results = []
+function assert(cond, message) {
+  if (!cond) throw new Error(message)
+}
+async function check(name, fn) {
+  try {
+    await fn()
+    results.push({ name, ok: true })
+    console.log(`PASS ${name}`)
+  } catch (error) {
+    results.push({ name, ok: false, error: error?.message || String(error) })
+    console.log(`FAIL ${name} — ${error?.message || error}`)
+  }
+}
+
+const LAUNCH_TOKEN = 'A'.repeat(43)
+const COOKIE = 'dsh-auth-mock=v1.mock-signature'
+
+/** Minimal DSH web host: one session, scripted turn emitted in three delayed steps. */
+function startMockDsh() {
+  const events = []
+  let seq = 0
+  let sessions = []
+  const followers = new Set()
+  const push = (type, data = {}) => {
+    seq += 1
+    const event = { type, seq, data }
+    events.push(event)
+    for (const follower of followers) {
+      try {
+        follower.send(
+          JSON.stringify({ type: 'item', streamId: follower.streamId, value: { type: 'event', event } })
+        )
+      } catch {
+        /* follower already gone */
+      }
+    }
+  }
+  const server = createServer((req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1')
+    const send = (status, body, headers = {}) => {
+      res.writeHead(status, { 'content-type': 'application/json', ...headers })
+      res.end(JSON.stringify(body))
+    }
+    if (req.method === 'GET') {
+      if (url.pathname === '/') {
+        if (url.searchParams.get('token') === LAUNCH_TOKEN) {
+          res.writeHead(303, { location: '/', 'set-cookie': `${COOKIE}; HttpOnly; SameSite=Strict; Path=/` })
+          res.end()
+          return
+        }
+        res.writeHead(200, { 'content-type': 'text/plain' })
+        res.end('dsh web (mock)')
+        return
+      }
+      return send(404, { code: 'E_NOT_FOUND' })
+    }
+    if (req.method !== 'POST' || !url.pathname.startsWith('/api/')) return send(404, { code: 'E_NOT_FOUND' })
+    if (!String(req.headers.cookie || '').includes(COOKIE)) {
+      return send(401, { code: 'gateway/unauthorized', message: 'no session cookie' })
+    }
+    const chunks = []
+    req.on('data', (chunk) => chunks.push(chunk))
+    req.on('end', () => {
+      const envelope = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+      const args = envelope?.payload?.args || {}
+      const value = (v) => send(200, { result: { ok: true, value: v } })
+      switch (envelope.method) {
+        case 'session/list':
+          return value({ items: sessions.map((s) => ({ sessionId: s, title: `title ${s}`, status: 'idle' })) })
+        case 'session/create': {
+          const sessionId = `mock-${sessions.length + 1}`
+          sessions = [...sessions, sessionId]
+          return value({ sessionId })
+        }
+        case 'session/prompt': {
+          const { sessionId, requestId, content } = args?.request || {}
+          if (!sessions.includes(sessionId)) return send(200, { result: { ok: false, error: { code: 'gateway/not-found', message: 'no such session' } } })
+          const text = content?.[0]?.text ?? ''
+          push('user/message', { message: { content: [{ type: 'text', text }] }, requestId })
+          setTimeout(() => push('turn/start', { turn: 1 }), 200)
+          setTimeout(() => push('assistant/message', { message: { content: [{ type: 'text', text: `echo: ${text}` }, { type: 'text', text: 'MESH-CHANNEL-OK' }] } }), 600)
+          setTimeout(() => push('turn/end', { reason: { kind: 'completed' } }), 900)
+          return value({ accepted: true })
+        }
+        case 'session/page': {
+          const request = args?.request || {}
+          const through = Number.isInteger(request.throughSeq) ? request.throughSeq : -1
+          const max = request.maxMessages ?? 40
+          const visible = events.filter((event) => through === -1 || event.seq <= through)
+          const records = visible.slice(-max).map((event) => ({ type: 'event', event }))
+          return value({ records, hasMore: visible.length > records.length })
+        }
+        case 'session/cancel':
+          return value({ cancelled: true })
+        default:
+          return send(200, { result: { ok: false, error: { code: 'gateway/bad-request', message: `unknown method ${envelope.method}` } } })
+      }
+    })
+  })
+  // ---- session/follow carrier (`/api/remote.mux`) ---------------------------
+  // Wire shapes mirror packages/api/gateway/src/stream-protocol.ts: {type:'open',
+  // streamId, endpoint, payload} in, `{type:'item', streamId, value}` out.
+  const wss = new WebSocketServer({ noServer: true })
+  server.on('upgrade', (req, socket, head) => {
+    const url = new URL(req.url, 'http://127.0.0.1')
+    if (url.pathname !== '/api/remote.mux' || !String(req.headers.cookie || '').includes(COOKIE)) {
+      socket.destroy()
+      return
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      ws.on('message', (raw) => {
+        let frame
+        try {
+          frame = JSON.parse(raw.toString('utf8'))
+        } catch {
+          return
+        }
+        if (frame?.type === 'open' && frame.endpoint === 'session/follow') {
+          const maxMessages = frame.payload?.args?.request?.maxMessages ?? 40
+          ws.streamId = frame.streamId
+          followers.add(ws)
+          const records = events.slice(-maxMessages).map((event) => ({ type: 'event', event }))
+          ws.send(
+            JSON.stringify({
+              type: 'item',
+              streamId: frame.streamId,
+              value: { type: 'snapshot', cursor: seq, records, hasMore: false, header: {}, projections: {} }
+            })
+          )
+          return
+        }
+        if (frame?.type === 'cancel' || frame?.type === 'end') {
+          followers.delete(ws)
+          ws.close()
+        }
+      })
+      ws.on('close', () => followers.delete(ws))
+    })
+  })
+
+  return {
+    server,
+    dial() {
+      return new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', () => resolve(`http://127.0.0.1:${server.address().port}`))
+      })
+    },
+    close() {
+      for (const ws of followers) {
+        try {
+          ws.close()
+        } catch {
+          /* already closed */
+        }
+      }
+      return new Promise((resolve) => {
+        wss.close(() => server.close(() => resolve()))
+      })
+    },
+    reset() {
+      events.length = 0
+      seq = 0
+      sessions = []
+    },
+    launchUrl(base) {
+      return `${base}/?token=${LAUNCH_TOKEN}`
+    }
+  }
+}
+
+async function connectMesh(url, token) {
+  const transport = new StreamableHTTPClientTransport(new URL(url), {
+    requestInit: { headers: { Authorization: `Bearer ${token}` } }
+  })
+  const client = new Client({ name: 'dsh-mesh-channel-e2e', version: '0.0.1' })
+  await client.connect(transport)
+  return client
+}
+
+function parsed(result) {
+  const text = result?.content?.find?.((c) => c.type === 'text')?.text
+  return JSON.parse(text)
+}
+
+export async function runE2eChannel() {
+  const home = mkdtempSync(join(tmpdir(), 'dsh-mesh-channel-'))
+  const mock = startMockDsh()
+  const mockBase = await mock.dial()
+  const launchUrl = mock.launchUrl(mockBase)
+  let meshClient
+  let srv
+
+  try {
+    // ---- client level -------------------------------------------------------
+    await check('client.login exchanges the launch URL for a cookie', async () => {
+      const client = new DshWebClient({ log: quiet })
+      const { baseUrl } = await client.login(launchUrl)
+      assert(baseUrl === mockBase, `unexpected origin ${baseUrl}`)
+      assert(client.cookie === COOKIE, `unexpected cookie ${client.cookie}`)
+    })
+
+    await check('bad launch token is rejected (bad sample)', async () => {
+      const client = new DshWebClient({ log: quiet })
+      let failed = false
+      try {
+        await client.login(`${mockBase}/?token=${'B'.repeat(43)}`)
+      } catch (error) {
+        failed = error instanceof DshError && error.code === 'E_DSH_AUTH'
+      }
+      assert(failed, 'invalid launch token was accepted')
+    })
+
+    await check('rpc without a cookie fails fast (bad sample)', async () => {
+      const client = new DshWebClient({ baseUrl: mockBase, log: quiet })
+      let code = ''
+      try {
+        await client.listSessions()
+      } catch (error) {
+        code = error.code
+      }
+      assert(code === 'E_DSH_NO_COOKIE', `expected E_DSH_NO_COOKIE, got ${code}`)
+    })
+
+    await check('session/create -> prompt -> page returns the assistant reply', async () => {
+      const client = new DshWebClient({ log: quiet })
+      await client.login(launchUrl)
+      const sessionId = await client.createSession()
+      const result = await client.sendAndWait({ sessionId, text: 'ping', waitMs: 20000, pollMs: 200 })
+      assert(result.turnEnd.kind === 'completed', `unexpected turn end ${JSON.stringify(result.turnEnd)}`)
+      assert(result.reply.includes('echo: ping'), `reply missing echo: ${result.reply}`)
+      assert(result.reply.includes('MESH-CHANNEL-OK'), `reply missing marker: ${result.reply}`)
+    })
+
+    await check('HTTP 401 from the host surfaces as E_DSH_HTTP (bad sample)', async () => {
+      const client = new DshWebClient({ baseUrl: mockBase, cookie: 'stale=1', log: quiet })
+      let code = ''
+      try {
+        await client.listSessions()
+      } catch (error) {
+        code = error.code
+      }
+      assert(code === 'E_DSH_HTTP', `expected E_DSH_HTTP, got ${code}`)
+    })
+
+    // ---- mesh tools level ---------------------------------------------------
+    mock.reset()
+    const config = defaultConfig()
+    config.node = { ...config.node, name: 'channel-e2e', bind: '127.0.0.1', port: 0, path: '/mcp' }
+    config.acl.allow = [...config.acl.allow, 'channel_login', 'channel_send', 'channel_cancel']
+    config.dsh.targets = [{ id: 'mock-dsh', baseUrl: mockBase }]
+    writeFileSync(configPath(home), JSON.stringify(config, null, 2) + '\n', 'utf8')
+    const stamp = new Date(Date.now() + 5000)
+    utimesSync(configPath(home), stamp, stamp)
+    const secrets = loadSecrets(home)
+    srv = await startMeshServer({ home, log: quiet })
+    meshClient = await connectMesh(srv.url, secrets.inbound[0].token)
+
+    await check('channel_targets lists the configured target without a cookie', async () => {
+      const data = parsed(await meshClient.callTool({ name: 'channel_targets', arguments: {} }))
+      const target = data.targets.find((t) => t.id === 'mock-dsh')
+      assert(target, 'configured target not listed')
+      assert(target.hasCookie === false, 'cookie should not exist yet')
+    })
+
+    await check('channel_send before login returns E_DSH_NO_COOKIE', async () => {
+      const data = parsed(
+        await meshClient.callTool({ name: 'channel_send', arguments: { target: 'mock-dsh', text: 'hi' } })
+      )
+      assert(data.code === 'E_DSH_NO_COOKIE', `expected E_DSH_NO_COOKIE, got ${data.code}`)
+    })
+
+    await check('channel_login stores the cookie in secrets.json (0600, gitignored)', async () => {
+      const data = parsed(
+        await meshClient.callTool({ name: 'channel_login', arguments: { launchUrl, target: 'mock-dsh' } })
+      )
+      assert(data.target === 'mock-dsh', `unexpected target ${data.target}`)
+      assert(data.baseUrl === mockBase, `unexpected baseUrl ${data.baseUrl}`)
+      const raw = JSON.parse(await import('node:fs').then((fs) => fs.readFileSync(join(home, 'secrets.json'), 'utf8')))
+      assert(raw.dshWeb?.['mock-dsh']?.cookie === COOKIE, 'cookie was not persisted')
+    })
+
+    await check('channel_login without a target derives dsh-<port>', async () => {
+      const data = parsed(await meshClient.callTool({ name: 'channel_login', arguments: { launchUrl } }))
+      const port = new URL(mockBase).port
+      assert(data.target === `dsh-${port}`, `unexpected derived target ${data.target}`)
+    })
+
+    await check('channel_sessions lists the mock session after create', async () => {
+      const created = parsed(
+        await meshClient.callTool({ name: 'channel_send', arguments: { target: 'mock-dsh', text: 'wake up' } })
+      )
+      assert(created.reply.includes('MESH-CHANNEL-OK'), `unexpected reply ${created.reply}`)
+      const data = parsed(await meshClient.callTool({ name: 'channel_sessions', arguments: { target: 'mock-dsh' } }))
+      assert(data.count >= 1, 'no sessions listed')
+      assert(data.sessions[0].sessionId.length > 0, 'session id missing')
+    })
+
+    await check('channel_page returns a compact event list', async () => {
+      const sessions = parsed(await meshClient.callTool({ name: 'channel_sessions', arguments: { target: 'mock-dsh' } }))
+      const sessionId = sessions.sessions[0].sessionId
+      const data = parsed(await meshClient.callTool({ name: 'channel_page', arguments: { target: 'mock-dsh', sessionId } }))
+      const types = data.events.map((e) => e.type)
+      assert(types.includes('user/message'), 'missing user/message')
+      assert(types.includes('assistant/message'), 'missing assistant/message')
+      assert(types.includes('turn/end'), 'missing turn/end')
+    })
+
+    await check('channel_send to an unknown target returns E_NOT_FOUND (bad sample)', async () => {
+      const data = parsed(
+        await meshClient.callTool({ name: 'channel_send', arguments: { target: 'nope', text: 'x' } })
+      )
+      assert(data.code === 'E_NOT_FOUND', `expected E_NOT_FOUND, got ${data.code}`)
+    })
+
+    await check('channel_send is denied by ACL until a human allows it (bad sample)', async () => {
+      const before = JSON.parse(await import('node:fs').then((fs) => fs.readFileSync(configPath(home), 'utf8')))
+      const next = {
+        ...before,
+        acl: { ...before.acl, allow: before.acl.allow.filter((n) => n !== 'channel_send') }
+      }
+      writeFileSync(configPath(home), JSON.stringify(next, null, 2) + '\n', 'utf8')
+      const bump = new Date(Date.now() + 8000)
+      utimesSync(configPath(home), bump, bump)
+      // wait for the mtime-based reload
+      await new Promise((r) => setTimeout(r, 300))
+      const data = parsed(
+        await meshClient.callTool({ name: 'channel_send', arguments: { target: 'mock-dsh', text: 'blocked' } })
+      )
+      assert(data.code === 'E_DENIED', `expected E_DENIED, got ${data.code}`)
+    })
+
+    await check('channel calls land in the audit log', async () => {
+      const data = parsed(
+        await meshClient.callTool({ name: 'mesh_audit_tail', arguments: { limit: 200, tool: 'channel_send' } })
+      )
+      assert(data.entries.some((e) => e.tool === 'channel_send' && e.code === 'E_DENIED'), 'denied channel call not audited')
+    })
+  } finally {
+    try {
+      await meshClient?.close?.()
+    } catch {
+      /* ignore */
+    }
+    if (srv) await srv.close()
+    await mock.close()
+    rmSync(home, { recursive: true, force: true })
+  }
+
+  const failed = results.filter((r) => !r.ok)
+  console.log(`\ne2e-channel: ${results.length - failed.length}/${results.length} passed`)
+  if (failed.length > 0) {
+    for (const f of failed) console.log(`  FAILED: ${f.name} — ${f.error}`)
+    return 1
+  }
+  return 0
+}
+
+if (process.argv[1]?.endsWith('e2e-channel.js')) {
+  runE2eChannel().then((code) => process.exit(code))
+}