dsh-github-router 0.1.0

package/lib/tunnel.js

@@ -0,0 +1,247 @@
+/**
+ * Zero-dependency proxy transport: HTTPS through an HTTP CONNECT tunnel
+ * (plus plain HTTP via absolute-URI proxying), built on node:http/tls.
+ *
+ * Why not global fetch + undici ProxyAgent: this plugin must install
+ * OFFLINE on machines whose package registry access is exactly what is
+ * broken. The tunnel client is small, carries its own cooperative timeout
+ * and caller abort, enforces the byte cap, and sends
+ * `accept-encoding: identity` so responses never need decompression.
+ * @module dsh-github-router/tunnel
+ */
+import http from 'node:http'
+import tls from 'node:tls'
+
+const MAX_REDIRECTS = 3
+
+/** Basic auth header value for a proxy URL carrying credentials, else null. */
+export function proxyAuthHeader(proxyUrl) {
+  if (proxyUrl.username === '' && proxyUrl.password === '') return null
+  const user = decodeURIComponent(proxyUrl.username)
+  const pass = decodeURIComponent(proxyUrl.password)
+  if (user === '' && pass === '') return null
+  return 'Basic ' + Buffer.from(`${user}:${pass}`, 'utf8').toString('base64')
+}
+
+/** The CONNECT authority line for a target URL. */
+export function connectTarget(target) {
+  return `${target.hostname}:${target.port !== '' && target.port !== null ? target.port : 443}`
+}
+
+/** Build the request-line + headers block written onto the tunnel socket. */
+export function buildRequestHead(target, method, headers) {
+  const path = target.pathname + target.search
+  const lines = [`${method} ${path} HTTP/1.1`, `host: ${target.host}`]
+  for (const [key, value] of Object.entries(headers)) {
+    if (value === undefined || value === null) continue
+    lines.push(`${key}: ${value}`)
+  }
+  lines.push('accept-encoding: identity', 'connection: close', '', '')
+  return lines.join('\r\n')
+}
+
+/** Parse an HTTP response head into { status, headers }. */
+export function parseResponseHead(headText) {
+  const lines = String(headText).split('\r\n')
+  const match = /^HTTP\/\d(?:\.\d)? (\d{3})/.exec(lines[0] ?? '')
+  if (match === null) throw new Error(`bad HTTP status line: ${(lines[0] ?? '').slice(0, 60)}`)
+  const headers = {}
+  for (const line of lines.slice(1)) {
+    const colon = line.indexOf(':')
+    if (colon > 0) headers[line.slice(0, colon).trim().toLowerCase()] = line.slice(colon + 1).trim()
+  }
+  return { status: Number(match[1]), headers }
+}
+
+function openTunnel(target, proxyUrl, timeoutMs, signal) {
+  return new Promise((resolve, reject) => {
+    const auth = proxyAuthHeader(proxyUrl)
+    const request = http.request({
+      host: proxyUrl.hostname,
+      port: proxyUrl.port !== '' ? Number(proxyUrl.port) : 80,
+      method: 'CONNECT',
+      path: connectTarget(target),
+      headers: {
+        host: connectTarget(target),
+        ...(auth !== null ? { 'proxy-authorization': auth } : {}),
+      },
+    })
+    const onAbort = () => request.destroy(new DOMException('aborted', 'AbortError'))
+    if (signal !== undefined && signal !== null) {
+      if (signal.aborted) onAbort()
+      else signal.addEventListener('abort', onAbort, { once: true })
+    }
+    const timer = setTimeout(() => request.destroy(new DOMException('timed out', 'TimeoutError')), timeoutMs)
+    if (typeof timer.unref === 'function') timer.unref()
+    request.on('connect', (response, socket) => {
+      clearTimeout(timer)
+      if (response.statusCode !== 200) {
+        socket.destroy()
+        reject(new Error(`proxy CONNECT failed: HTTP ${response.statusCode}`))
+        return
+      }
+      const tlsSocket = tls.connect({ socket, servername: target.hostname }, () => {
+        if (signal !== undefined && signal !== null) signal.removeEventListener('abort', onAbort)
+        resolve(tlsSocket)
+      })
+      tlsSocket.on('error', reject)
+    })
+    request.on('error', (error) => {
+      clearTimeout(timer)
+      if (signal !== undefined && signal !== null) signal.removeEventListener('abort', onAbort)
+      reject(error)
+    })
+    request.end()
+  })
+}
+
+function readResponse(socket, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    let total = 0
+    let headerBuf = Buffer.alloc(0)
+    let headerDone = false
+    let settled = false
+    let status = 0
+    let headers = {}
+    let truncated = false
+    const finish = (error) => {
+      if (settled) return
+      settled = true
+      socket.destroy()
+      if (error !== undefined) reject(error)
+      else resolve({ status, ok: status >= 200 && status < 300, body: Buffer.concat(chunks), truncated, headers })
+    }
+    const onBody = (buf) => {
+      total += buf.length
+      if (total > maxBytes) {
+        const keep = maxBytes - (total - buf.length)
+        if (keep > 0) chunks.push(buf.subarray(0, keep))
+        truncated = true
+        finish()
+        return
+      }
+      chunks.push(buf)
+    }
+    socket.on('data', (buf) => {
+      if (!headerDone) {
+        headerBuf = Buffer.concat([headerBuf, buf])
+        const idx = headerBuf.indexOf('\r\n\r\n')
+        if (idx === -1) {
+          if (headerBuf.length > 65536) finish(new Error('response headers too large'))
+          return
+        }
+        try {
+          const head = parseResponseHead(headerBuf.subarray(0, idx).toString('latin1'))
+          status = head.status
+          headers = head.headers
+        } catch (error) {
+          finish(error)
+          return
+        }
+        headerDone = true
+        const rest = headerBuf.subarray(idx + 4)
+        if (rest.length > 0) onBody(rest)
+        return
+      }
+      onBody(buf)
+    })
+    socket.on('end', () => {
+      if (headerDone) finish()
+      else finish(new Error('connection closed before response headers'))
+    })
+    socket.on('error', (error) => finish(error))
+  })
+}
+
+/**
+ * One proxied request: CONNECT tunnel for https targets, absolute-URI for
+ * http targets. Returns the same shape as the direct fetch path.
+ */
+export async function tunnelRequest(targetUrl, options) {
+  const { method = 'GET', headers = {}, timeoutMs = 15000, proxy, signal, maxBytes = 1048576 } = options
+  let target = new URL(targetUrl)
+  let proxyUrl
+  try {
+    proxyUrl = new URL(String(proxy))
+  } catch {
+    // Never echo credentials: display only scheme://host:port.
+    const display = String(proxy).replace(/\/\/([^/@]+)@/, '//')
+    throw new Error(`invalid proxy URL: ${display.slice(0, 120)}`)
+  }
+
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
+    if (signal !== undefined && signal !== null && signal.aborted) throw new DOMException('aborted', 'AbortError')
+
+    let socket
+    if (target.protocol === 'https:') {
+      socket = await openTunnel(target, proxyUrl, timeoutMs, signal)
+    } else if (target.protocol === 'http:') {
+      const auth = proxyAuthHeader(proxyUrl)
+      socket = await new Promise((resolve, reject) => {
+        const request = http.request({
+          host: proxyUrl.hostname,
+          port: proxyUrl.port !== '' ? Number(proxyUrl.port) : 80,
+          method,
+          path: target.toString(),
+          headers: {
+            host: target.host,
+            ...(auth !== null ? { 'proxy-authorization': auth } : {}),
+            ...headers,
+          },
+        })
+        const onAbort = () => request.destroy(new DOMException('aborted', 'AbortError'))
+        if (signal !== undefined && signal !== null) {
+          if (signal.aborted) onAbort()
+          else signal.addEventListener('abort', onAbort, { once: true })
+        }
+        const timer = setTimeout(() => request.destroy(new DOMException('timed out', 'TimeoutError')), timeoutMs)
+        if (typeof timer.unref === 'function') timer.unref()
+        request.on('response', (response) => {
+          clearTimeout(timer)
+          if (signal !== undefined && signal !== null) signal.removeEventListener('abort', onAbort)
+          resolve({ stream: response, status: response.statusCode ?? 0, headers: response.headers })
+        })
+        request.on('error', (error) => {
+          clearTimeout(timer)
+          if (signal !== undefined && signal !== null) signal.removeEventListener('abort', onAbort)
+          reject(error)
+        })
+        request.end()
+      }).then(({ stream, status, headers }) => {
+        // Collect the http-over-proxy body (rarely used by this plugin).
+        return new Promise((resolve, reject) => {
+          const chunks = []
+          let total = 0
+          let truncated = false
+          stream.on('data', (buf) => {
+            total += buf.length
+            if (total > maxBytes) {
+              const keep = maxBytes - (total - buf.length)
+              if (keep > 0) chunks.push(buf.subarray(0, keep))
+              truncated = true
+              stream.destroy()
+            } else chunks.push(buf)
+          })
+          stream.on('end', () => resolve({ status, ok: status >= 200 && status < 300, body: Buffer.concat(chunks), truncated, headers }))
+          stream.on('error', reject)
+        })
+      })
+      return socket
+    } else {
+      throw new Error(`unsupported target protocol: ${target.protocol}`)
+    }
+
+    if (target.protocol === 'https:') {
+      socket.write(buildRequestHead(target, method, headers))
+      const response = await readResponse(socket, maxBytes)
+      const location = response.headers.location
+      if (location !== undefined && [301, 302, 303, 307, 308].includes(response.status) && hop < MAX_REDIRECTS) {
+        target = new URL(location, target)
+        continue
+      }
+      return { status: response.status, ok: response.ok, body: response.body, truncated: response.truncated, headers: response.headers, url: target.toString() }
+    }
+  }
+  throw new Error(`too many redirects (${MAX_REDIRECTS})`)
+}

package/lib/util.js

@@ -0,0 +1,235 @@
+/**
+ * Shared helpers: session cwd, subprocess execution (argv arrays only),
+ * input validation guards, and text shaping.
+ * @module dsh-github-router/util
+ */
+import { createHash } from 'node:crypto'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export const DSH_HOME = process.env.DSH_HOME || join(homedir(), '.dsh')
+export const STORAGE_DIR = join(DSH_HOME, 'storages', 'dsh-github-router')
+export const CACHE_DIR = join(STORAGE_DIR, 'cache')
+export const GIT_CACHE_DIR = join(STORAGE_DIR, 'git')
+
+/** Session workspace cwd, with a process-cwd fallback. */
+export function sessionCwd(exec) {
+  const header = exec && exec.agent && exec.agent.session && exec.agent.session.header
+  if (header && typeof header.cwd === 'string' && header.cwd.length > 0) return header.cwd
+  return process.cwd()
+}
+
+export function sha1(text) {
+  return createHash('sha1').update(String(text), 'utf8').digest('hex')
+}
+
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+export function isAbortError(error) {
+  return (
+    (error instanceof DOMException && error.name === 'AbortError') ||
+    (error !== null && typeof error === 'object' && error.name === 'AbortError')
+  )
+}
+
+// ------------------------------------------------------------------ guards
+
+/** GitHub owner/repo names: alphanumerics plus . _ -, not empty. */
+const OWNER_REPO_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+
+export function guardOwnerRepo(value, label) {
+  const text = String(value ?? '')
+  if (text.length === 0 || text.length > 100 || !OWNER_REPO_RE.test(text)) {
+    throw new Error(`${label} must be a valid GitHub owner or repository name (got "${text}")`)
+  }
+  return text
+}
+
+export function guardPrNumber(value, label = 'number') {
+  const n = Number(value)
+  if (!Number.isInteger(n) || n < 1 || n > 100_000_000) {
+    throw new Error(`${label} must be a positive integer (got "${String(value)}")`)
+  }
+  return n
+}
+
+/**
+ * api.github.com relative paths only: starts with '/', no query/fragment,
+ * no control characters or spaces, no '..' segments. GET only — enforced
+ * by the client, which has no other verbs.
+ */
+const API_PATH_RE = /^\/[A-Za-z0-9._~%/-]*$/
+
+export function guardApiPath(path) {
+  const text = String(path ?? '')
+  if (text.length === 0 || text.length > 2048 || !API_PATH_RE.test(text)) {
+    throw new Error(`path must be a plain api.github.com relative path starting with "/" (got "${text}")`)
+  }
+  if (text.split('/').includes('..') || text.includes('%2e%2e') || text.toLowerCase().includes('%2e%2e')) {
+    throw new Error(`path must not contain ".." segments (got "${text}")`)
+  }
+  return text
+}
+
+/**
+ * Repo file path: relative, no leading slash, no ".." segments, no control
+ * characters, bounded length. It is passed to subprocesses as a single argv
+ * element (never interpolated into a shell command).
+ */
+const FILE_PATH_RE = /^[^\u0000-\u001f\u007f\\:*?"<>|]+$/
+
+export function guardFilePath(path) {
+  const text = String(path ?? '')
+  if (text.length === 0 || text.length > 1024) {
+    throw new Error(`path must be a non-empty relative repository file path (got "${text}")`)
+  }
+  if (text.startsWith('/') || !FILE_PATH_RE.test(text)) {
+    throw new Error(`path must be a relative repository file path without control characters (got "${text}")`)
+  }
+  if (text.split('/').includes('..')) {
+    throw new Error(`path must not contain ".." segments (got "${text}")`)
+  }
+  return text
+}
+
+export function guardRef(value, label = 'ref') {
+  const text = String(value ?? '').trim()
+  if (text.length === 0 || text.length > 512 || text.startsWith('-') || /[\u0000-\u001f\u007f~^:?*[\\]/.test(text) || text.includes('..')) {
+    throw new Error(`${label} must be a plain git ref name (branch, tag, or full commit sha) (got "${text}")`)
+  }
+  return text
+}
+
+export function guardByteCount(value, label, fallback, min, max) {
+  if (value === undefined || value === null) return fallback
+  const n = Number(value)
+  if (!Number.isInteger(n) || n < min || n > max) {
+    throw new Error(`${label} must be an integer between ${min} and ${max} (got "${String(value)}")`)
+  }
+  return n
+}
+
+// -------------------------------------------------------------- subprocess
+
+const DEFAULT_STDOUT_CAP = 1_048_576
+const DEFAULT_STDERR_CAP = 262_144
+
+/**
+ * Run one subprocess to completion through the platform subprocess service
+ * (host token — the same channel the pyenv/graphlint plugins use), with
+ * argv arrays and no shell interpolation anywhere.
+ * @returns { exitCode, ok, timedOut, stdout: {text, truncated}, stderr: {...}, spawnError }
+ */
+export async function runCaptured(subprocess, spec) {
+  const {
+    argv,
+    cwd,
+    env,
+    graceMs = 15_000,
+    signal,
+    maxStdout = DEFAULT_STDOUT_CAP,
+    maxStderr = DEFAULT_STDERR_CAP,
+    onSpawn,
+  } = spec
+  let handle
+  try {
+    handle = subprocess.spawn({
+      argv,
+      ...(cwd !== undefined ? { cwd } : {}),
+      ...(env !== undefined ? { env } : {}),
+      stdio: { stdin: 'ignore', stdout: { maxBytes: maxStdout }, stderr: { maxBytes: maxStderr } },
+      graceMs,
+      ...(signal !== undefined ? { signal } : {}),
+    })
+  } catch (error) {
+    return { exitCode: null, ok: false, timedOut: false, spawnError: String(error && error.message ? error.message : error), stdout: { text: '', truncated: false }, stderr: { text: '', truncated: false } }
+  }
+  if (onSpawn !== undefined) onSpawn(handle)
+  let outcome
+  try {
+    outcome = await handle.done
+  } catch (error) {
+    return { exitCode: null, ok: false, timedOut: false, spawnError: String(error && error.message ? error.message : error), stdout: { text: '', truncated: false }, stderr: { text: '', truncated: false } }
+  }
+  const shape = (reader) => {
+    if (reader === undefined || reader === null) return { text: '', truncated: false }
+    const read = reader.readFrom(0)
+    return { text: typeof read.text === 'string' ? read.text : '', truncated: !!read.lossy }
+  }
+  const exitCode = outcome.exitCode === undefined || outcome.exitCode === null ? null : outcome.exitCode
+  return {
+    exitCode,
+    ok: exitCode === 0,
+    timedOut: outcome.exitCode === null || outcome.exitCode === undefined,
+    spawnError: null,
+    stdout: shape(handle.collected && handle.collected.stdout),
+    stderr: shape(handle.collected && handle.collected.stderr),
+  }
+}
+
+/** Env for read-only git/gh children: never prompts, no color, plus the ambient env. */
+export function childEnv(extra) {
+  return {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    GH_PROMPT_DISABLED: '1',
+    NO_COLOR: '1',
+    ...extra,
+  }
+}
+
+// ---------------------------------------------------------------- shaping
+
+/** Byte-bounded truncation with a marker; lossless for inputs under the cap. */
+export function truncateText(text, maxBytes) {
+  const s = String(text ?? '')
+  const buf = Buffer.from(s, 'utf8')
+  if (buf.length <= maxBytes) return { text: s, truncated: false }
+  return { text: buf.subarray(0, maxBytes).toString('utf8'), truncated: true }
+}
+
+const HTML_ENTITIES = {
+  '&amp;': '&',
+  '&lt;': '<',
+  '&gt;': '>',
+  '&quot;': '"',
+  '&#39;': "'",
+  '&apos;': "'",
+  '&nbsp;': ' ',
+  '&#x27;': "'",
+}
+
+/** Crude tag-strip for bodies extracted from page payloads (display only). */
+export function stripHtml(html) {
+  let text = String(html ?? '')
+  text = text.replace(/<script[\s\S]*?<\/script>/gi, ' ')
+  text = text.replace(/<style[\s\S]*?<\/style>/gi, ' ')
+  text = text.replace(/<br\s*\/?>/gi, '\n')
+  text = text.replace(/<\/p>/gi, '\n')
+  text = text.replace(/<li[^>]*>/gi, '\n- ')
+  text = text.replace(/<[^>]+>/g, '')
+  text = text.replace(/&(amp|lt|gt|quot|apos|nbsp|#39|#x27);/gi, (m) => HTML_ENTITIES[m.toLowerCase()] ?? m)
+  text = text.replace(/\u00a0/g, ' ')
+  text = text.replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n')
+  return text.trim()
+}
+
+// --------------------------------------------------------------- git urls
+
+/**
+ * Extract { owner, repo } from common GitHub remote URL shapes.
+ * Returns null when the URL does not look like a GitHub repo remote.
+ */
+export function ownerRepoFromUrl(url) {
+  const text = String(url ?? '').trim().replace(/\\/g, '/')
+  let match
+  match = /^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/.exec(text)
+  if (match) return { owner: match[1], repo: match[2] }
+  match = /^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/.exec(text)
+  if (match) return { owner: match[1], repo: match[2] }
+  match = /^ssh:\/\/git@github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/.exec(text)
+  if (match) return { owner: match[1], repo: match[2] }
+  return null
+}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "dsh-github-router",
+  "version": "0.1.0",
+  "description": "DeepSeek Harness plugin: read-only GitHub access for agents (github_probe / github_pr / github_issue / github_file / github_api). Routes every request inside the tool — api.github.com (direct or proxy), gh CLI, git protocol (plugin-owned fetch cache plus read-only local repo reads), PR/issue page HTML with strict JSON embeddedData extraction, and optional user-configured raw mirrors — so agents never burn turns fighting sandbox TLS/proxy failures in a shell. No write/push capability exists anywhere in the plugin.",
+  "keywords": [
+    "dsh-plugin",
+    "dsh",
+    "deepseek-harness",
+    "github",
+    "pull-request",
+    "issue",
+    "read-only",
+    "proxy",
+    "router"
+  ],
+  "license": "MIT",
+  "author": "Yutong Zou <yutong.zou.24@alumni.ucl.ac.uk> (https://github.com/AngelosZou)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AngelosZou/dsh-github-router.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AngelosZou/dsh-github-router/issues"
+  },
+  "homepage": "https://github.com/AngelosZou/dsh-github-router#readme",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "SECURITY.md",
+    "README.md",
+    "README.zh.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "docs"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">=20.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^2.0.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test --test-isolation=none \"test/*.test.js\""
+  }
+}