@goodandready/dsh-github-ops 0.2.10 → 0.2.12

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.2.12
+
+### Security
+- **Release Preflight Test Confirmation & CWD Containment** (#80): Required `confirm: true` to execute `npm test` during `gh_release_preflight` audit, and routed audit directory through `validateCwd` to prevent arbitrary directory test execution.
+- **SCM Symlink Traversal Protection** (#96): Enhanced `validateCwd` with `realpathSync` resolution to prevent directory traversal and symlink escape into protected system directories (`/etc`, `/proc`, `/sys`, etc.).
+- **Socket Remote Address Verification & IPv6 Support** (#97): Enforced socket `remoteAddress` validation in `isTrustedRequest` and `isTrustedWriteRequest` to block untrusted external clients from spoofing matching `Host` and `Origin` headers. Fixed unbracketed IPv6 address parsing in `isTrustedHost`.
+
+### Refactored
+- **Mirror Git Index Directory Isolation** (#91): Created mirror temporary git-index inside an isolated `fs.mkdtemp` (0700) directory with guaranteed cleanup in `finally`.
+- **Dead Parameter Aliases Removed** (#92): Removed undeclared schema fallback aliases (`tagName`, `targetCommitish`, `previousTagName`, `configurationFilePath`, `pullNumber`) from tool registrations.
+- **Unused Parameters & Re-exports Cleanup** (#95): Removed unused `repoHint` in slash commands, dead `liveConfig()` call in `gh_auth_status`, and unused re-export of `runReleasePreflight`.
+
+## 0.2.11
+
+### Security
+- **Strict CSRF & Origin Verification on SCM Writes** (#98, #81, #99): Added `isTrustedWriteRequest` guarding `POST /scm`. Discarded client-supplied `X-Forwarded-Host` in favor of validated `Host` header. Enforced strict fail-closed policy on cross-site requests (`Sec-Fetch-Site: cross-site`) across loopback and local networks.
+- **Path Segment Encoding & Traversal Defense** (#87): Added `encodeRepoPath` to prevent directory traversal (`..`) and URI-encode path segments in GitHub Contents API endpoints (`getFile`, `deleteFile`, and blob viewer route).
+- **Mirror Publication Isolation & Option Injection Defense** (#83, #91): Added strict validation on mirror destination URLs and branch names (`validateRemote`, `validateBranchName`) to reject leading hyphen flags and CLI option injection into git arguments. Replaced predictable temp index paths with `crypto.randomUUID()`-backed paths in `tmpdir()`.
+- **Release Asset Upload Workspace Containment** (#82): Restricted release asset file uploads to files within the workspace root or allowlisted local files, rejecting system directories (`/etc`, `/proc`, `/sys`, etc.), traversal paths, and control characters.
+
 ## 0.2.10
 
 ### Fixed

package/lib/commands.js

@@ -72,7 +72,7 @@ export function buildGhInstruction({ topic, tool, args } = {}) {
  * Register the commands. Every handler returns an instruction for the model; none of them
  * touches GitHub.
  */
-export function registerCommands(commands, { readGitState, repoHint } = {}) {
+export function registerCommands(commands, { readGitState } = {}) {
   const disposers = []
   const context = async () => {
     try {
@@ -92,7 +92,7 @@ export function registerCommands(commands, { readGitState, repoHint } = {}) {
       const git = await context()
       return {
         kind: 'success',
-        text: buildPrInstruction({ title: rest.join(' '), branch: git.branch, base: git.base || 'main', repo: git.repo || (typeof repoHint === 'function' ? repoHint() : undefined), remoteUrl: git.remoteUrl }),
+        text: buildPrInstruction({ title: rest.join(' '), branch: git.branch, base: git.base || 'main', repo: git.repo, remoteUrl: git.remoteUrl }),
       }
     },
   }))
@@ -107,7 +107,7 @@ export function registerCommands(commands, { readGitState, repoHint } = {}) {
       const git = await context()
       return {
         kind: 'success',
-        text: buildReviewInstruction({ number, branch: git.branch, repo: git.repo || (typeof repoHint === 'function' ? repoHint() : undefined) }),
+        text: buildReviewInstruction({ number, branch: git.branch, repo: git.repo }),
       }
     },
   }))
@@ -119,7 +119,7 @@ export function registerCommands(commands, { readGitState, repoHint } = {}) {
     handler: async (invocation) => {
       const [sub, ...rest] = String(invocation.rawInput || '').trim().split(/\s+/)
       const git = await context()
-      const repo = git.repo || (typeof repoHint === 'function' ? repoHint() : undefined)
+      const repo = git.repo
       if (sub === 'new') return { kind: 'success', text: buildIssueInstruction({ sub, title: rest.join(' '), repo }) }
       if (sub === 'show' && /^\d+$/.test(rest[0] || '')) return { kind: 'success', text: buildIssueInstruction({ sub, number: Number(rest[0]), repo }) }
       if (!sub || sub === 'list') return { kind: 'success', text: buildIssueInstruction({ sub: 'list', repo }) }

package/lib/github.js

@@ -424,3 +424,17 @@ export function describeError(err) {
   }
   return String(err.message || err)
 }
+
+/**
+ * Safely encode a repository file path segment for the GitHub contents API.
+ * Rejects path traversal (..) and encodes each path component.
+ */
+export function encodeRepoPath(rawPath) {
+  const cleaned = String(rawPath == null ? '' : rawPath).trim().replace(/^\/+/, '')
+  if (!cleaned) throw new Error('path is required')
+  const segments = cleaned.split('/')
+  if (segments.some((s) => s === '..' || s === '.')) {
+    throw new Error('path must not contain traversal segments')
+  }
+  return segments.map(encodeURIComponent).join('/')
+}

package/lib/index.js

@@ -375,7 +375,7 @@ export function apply(ctx, rawConfig) {
     },
   }
 
-  const deps = { tool, asRepo, client, liveConfig, reviewRules, auth: authSeam }
+  const deps = { tool, asRepo, client, liveConfig, reviewRules, auth: authSeam, defaultCwd: () => (typeof ctx.cwd === 'string' && ctx.cwd) || process.cwd() }
   registerCoreTools(deps)
   registerCollabTools(deps)
   registerOpsTools(deps)

package/lib/routes.js

@@ -8,7 +8,7 @@
 import { existsSync, statSync } from 'node:fs'
 import { join as joinPath } from 'node:path'
 
-import { statusPayload, isTrustedRequest, sendJson } from './status.js'
+import { statusPayload, isTrustedRequest, isTrustedWriteRequest, sendJson } from './status.js'
 import { buildAction, validateCwd } from './scm-write.js'
 import { parseStatus, parseBranches, parseStashes, parseWorktrees, parseCount, scmPayload, mergeStateFrom } from './scm.js'
 import { listIssues } from './tools/issues.js'
@@ -94,7 +94,11 @@ export function registerRoutes(ctx, deps = {}) {
         path: SCM_PATH,
         handler: async (req, res) => {
           if (req.method !== 'GET' && req.method !== 'POST') return sendJson(res, 405, { error: 'method not allowed' })
-          if (!isTrustedRequest(req)) return sendJson(res, 403, { error: 'forbidden' })
+          if (req.method === 'POST') {
+            if (!isTrustedWriteRequest(req)) return sendJson(res, 403, { error: 'forbidden' })
+          } else {
+            if (!isTrustedRequest(req)) return sendJson(res, 403, { error: 'forbidden' })
+          }
           const git = makeGitRunner()
           const url = new URL(req.url || '/', 'http://localhost')
           const file = url.searchParams.get('file') || ''
@@ -254,7 +258,13 @@ export function registerRoutes(ctx, deps = {}) {
               return sendJson(res, 200, { configured: true, ...view })
             }
             if (what === 'blob') {
-              const { data } = await github.get(`/repos/${repoOwner}/${repoName}/contents/${path}`, { query: ref ? { ref } : undefined })
+              let encodedPath = ''
+              try {
+                encodedPath = encodeRepoPath(path)
+              } catch (err) {
+                return sendJson(res, 400, { configured: true, error: (err && err.message) || String(err) })
+              }
+              const { data } = await github.get(`/repos/${repoOwner}/${repoName}/contents/${encodedPath}`, { query: ref ? { ref } : undefined })
               if (Array.isArray(data)) return sendJson(res, 200, { configured: true, entries: data.map((e) => ({ name: e.name, type: e.type, size: e.size, path: e.path })) })
               const encoded = String((data && data.content) || '').replace(/\n/g, '')
               const text = encoded ? Buffer.from(encoded, 'base64').toString('utf8') : ''

package/lib/scm-write.js

@@ -1,3 +1,4 @@
+import { realpathSync } from 'node:fs'
 // Writing to a working copy, from the Source Control tab.
 //
 // Every action is a list of argv arrays — never a shell string. The route runs them one by one
@@ -172,5 +173,16 @@ export function validateCwd(path) {
       throw new Error(`access to system directory "${root}" is not allowed`)
     }
   }
+  let realPath = value
+  try {
+    realPath = realpathSync(value)
+  } catch {
+    realPath = value
+  }
+  for (const root of DISALLOWED_ROOTS) {
+    if (realPath === root || realPath.startsWith(root + '/')) {
+      throw new Error(`access to system directory "${root}" is not allowed`)
+    }
+  }
   return value
 }

package/lib/status.js

@@ -7,43 +7,106 @@
 // The payload never contains the access value. The route answers only a local or same-origin
 // caller, because the payload describes the machine's account.
 
+/** Whether a request may read the status payload. Fail-closed. */
+function isTrustedHost(host) {
+  if (!host || typeof host !== 'string') return false
+  let hostname = host.trim()
+  if (hostname.startsWith('[')) {
+    const end = hostname.indexOf(']')
+    if (end > 0) hostname = hostname.slice(1, end)
+  } else if (hostname.includes(':')) {
+    const colons = hostname.split(':').length - 1
+    if (colons === 1) {
+      hostname = hostname.split(':')[0]
+    }
+  }
+  hostname = hostname.toLowerCase()
+  if (!hostname) return false
+  if (hostname === 'localhost' || hostname.endsWith('.local') || hostname.endsWith('.lan')) return true
+  const clean = hostname.replace(/^::ffff:/, '')
+  if (clean === '127.0.0.1' || clean === '::1' || clean.startsWith('127.')) return true
+  if (clean.startsWith('10.') || clean.startsWith('192.168.')) return true
+  const match172 = clean.match(/^172\.(\d+)\./)
+  if (match172) {
+    const octet = parseInt(match172[1], 10)
+    if (octet >= 16 && octet <= 31) return true
+  }
+  return false
+}
+
 /** Whether a request may read the status payload. Fail-closed. */
 export function isTrustedRequest(req) {
   if (!req) return false
-  const address = (req.socket && (req.socket.remoteAddress || req.socket.address?.().address)) || ''
-  const loopback = address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1'
-  if (loopback) return true
 
-  // For non-loopback callers: fail-closed source verification
+  // Fail-closed against cross-site fetches regardless of source IP
   const secFetchSite = header(req, 'sec-fetch-site')
   if (secFetchSite === 'cross-site') return false
 
-  const host = header(req, 'x-forwarded-host') || header(req, 'host')
+  const address = (req.socket && (req.socket.remoteAddress || req.socket.address?.().address)) || ''
+  const cleanIp = address.replace(/^::ffff:/, '')
+  const loopback = cleanIp === '127.0.0.1' || cleanIp === '::1' || cleanIp.startsWith('127.')
+
+  // If socket remoteAddress is present, it MUST be a trusted local/private IP (never an untrusted remote IP)
+  if (cleanIp && !isTrustedHost(cleanIp)) return false
+
+  const host = header(req, 'host')
   const origin = header(req, 'origin') || header(req, 'referer')
-  if (!host || !origin) return false
 
-  try {
-    const originUrl = new URL(origin)
-    if (originUrl.host.toLowerCase() !== host.toLowerCase()) return false
+  // If host is provided, it MUST be a trusted local/private host (DNS rebinding guard)
+  if (host && !isTrustedHost(host)) return false
 
+  // If browser headers (origin/referer/sec-fetch-site) are absent and caller is loopback, allow local caller
+  if (!origin && !secFetchSite && loopback) return true
 
+  // If origin/referer is present, verify it matches host or is a trusted local host
+  if (origin) {
+    try {
+      const originUrl = new URL(origin)
+      if (!isTrustedHost(originUrl.hostname)) return false
+      if (host && originUrl.host.toLowerCase() !== host.toLowerCase()) return false
+      return true
+    } catch {
+      return false
+    }
+  }
 
-    // DNS rebinding guard: host must be a loopback, local or private LAN address
-    const hostname = host.split(':')[0].toLowerCase()
-    const isPrivate =
-      hostname === 'localhost' ||
-      hostname === '127.0.0.1' ||
-      hostname === '::1' ||
-      /^192\.168\.\d{1,3}\.\d{1,3}$/.test(hostname) ||
-      /^10\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname) ||
-      /^172\.(1[6-9]|2\d|3[0-1])\.\d{1,3}\.\d{1,3}$/.test(hostname) ||
-      hostname.endsWith('.local') ||
-      hostname.endsWith('.lan')
+  // Non-loopback caller without origin/referer is refused
+  if (!loopback) return false
 
-    return isPrivate
-  } catch {
+  return true
+}
+
+/** Whether a write/mutating request (e.g. POST /scm) is safe. Strict write guard against CSRF. */
+export function isTrustedWriteRequest(req) {
+  if (!req) return false
+  if (!isTrustedRequest(req)) return false
+
+  const secFetchSite = header(req, 'sec-fetch-site')
+  if (secFetchSite && secFetchSite !== 'same-origin' && secFetchSite !== 'none') {
     return false
   }
+
+  const address = (req.socket && (req.socket.remoteAddress || req.socket.address?.().address)) || ''
+  const cleanIp = address.replace(/^::ffff:/, '')
+  const loopback = cleanIp === '127.0.0.1' || cleanIp === '::1' || cleanIp.startsWith('127.')
+
+  if (cleanIp && !isTrustedHost(cleanIp)) return false
+
+  const host = header(req, 'host')
+  const origin = header(req, 'origin') || header(req, 'referer')
+  if (origin) {
+    try {
+      const originUrl = new URL(origin)
+      if (host && originUrl.host.toLowerCase() !== host.toLowerCase()) return false
+    } catch {
+      return false
+    }
+  } else {
+    // Write request without origin: only permit local loopback
+    if (!loopback) return false
+  }
+
+  return true
 }
 
 function header(req, name) {

package/lib/tools/mirror.js

@@ -1,3 +1,6 @@
+import { randomUUID } from 'node:crypto'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
 // Sanitized mirror publication.
 //
 // A GitHub mirror is a product channel, not a copy of the history: only the npm
@@ -76,7 +79,30 @@ async function readManifest(git, { cwd, ref }) {
  * Read-only plan: which files would be published, how many would be left behind, and
  * whether the publication must be refused (forbidden path present, required file missing).
  */
+
+const REMOTE_NAME_RE = /^(?!-)[a-zA-Z0-9._/-]+$/
+const BRANCH_NAME_RE = /^(?!-)[a-zA-Z0-9._/-]+$/
+
+export function validateRemote(remote) {
+  const val = String(remote || '').trim()
+  if (!val || val.startsWith('-') || !REMOTE_NAME_RE.test(val)) {
+    throw new Error(`invalid mirror remote name: "${remote}"`)
+  }
+  return val
+}
+
+export function validateBranchName(branch) {
+  const val = String(branch || '').trim()
+  if (!val || val.startsWith('-') || !BRANCH_NAME_RE.test(val)) {
+    throw new Error(`invalid branch name: "${branch}"`)
+  }
+  return val
+}
+
 export async function planMirror({ git, cwd, ref = 'origin/main', allow, forbidden, required = DEFAULT_REQUIRED }) {
+  if (String(ref || '').trim().startsWith('-')) {
+    throw new Error(`invalid source ref: "${ref}"`)
+  }
   const manifest = await readManifest(git, { cwd, ref })
   const allowlist = allow || allowlistFromManifest(manifest)
   const ls = await git(['ls-tree', '-r', '--name-only', ref], { cwd })
@@ -115,6 +141,11 @@ export async function publishMirror({
   git, cwd, ref = 'origin/main', mirror = 'github', branch = 'main',
   allow, forbidden, required = DEFAULT_REQUIRED, dryRun = false, message,
 }) {
+  validateRemote(mirror)
+  validateBranchName(branch)
+  if (String(ref || '').trim().startsWith('-')) {
+    throw new Error(`invalid source ref: "${ref}"`)
+  }
   const plan = await planMirror({ git, cwd, ref, allow, forbidden, required })
   if (plan.refused) {
     const err = new Error(plan.refused)
@@ -131,7 +162,9 @@ export async function publishMirror({
 
   if (dryRun) return { ...plan, mirror: mirrorRef, parent, commit: null, pushed: false }
 
-  const indexFile = `/tmp/dsh-github-ops-mirror-${process.pid}-${Date.now()}.index`
+  const fs = await import('node:fs/promises')
+  const tmpIndexDir = await fs.mkdtemp(path.join(tmpdir(), 'dsh-mirror-index-'))
+  const indexFile = path.join(tmpIndexDir, `mirror-${randomUUID()}.index`)
   const env = { GIT_INDEX_FILE: indexFile }
   try {
     await git(['read-tree', '--empty'], { cwd, env })
@@ -159,5 +192,6 @@ export async function publishMirror({
     }
   } finally {
     await git(['update-index', '--refresh'], { cwd, env }).catch(() => {})
+    await fs.rm(tmpIndexDir, { recursive: true, force: true }).catch(() => {})
   }
 }

package/lib/tools/register-collab.js

@@ -245,7 +245,7 @@ export function registerCollabTools({ tool, asRepo, client, liveConfig, reviewRu
       const { owner, repo } = await asRepo(args, liveConfig())
       return listReviewThreads(await client(), {
         owner, repo,
-        number: args.number || args.pullNumber,
+        number: args.number,
         unresolvedOnly: Boolean(args.unresolvedOnly),
       })
     },
@@ -266,7 +266,7 @@ export function registerCollabTools({ tool, asRepo, client, liveConfig, reviewRu
       const { owner, repo } = await asRepo(args, liveConfig())
       return replyReviewThread(await client(), {
         owner, repo,
-        number: args.number || args.pullNumber,
+        number: args.number,
         threadId: args.threadId,
         commentId: args.commentId,
         body: args.body,

package/lib/tools/register-core.js

@@ -1,3 +1,4 @@
+import { validateCwd } from '../scm-write.js'
 import { runReleasePreflight } from './release-preflight.js'
 // Core tool registrations: repository and file reads, releases, tags, the guarded
 // generic API pass-through, and repository creation/edits.
@@ -14,7 +15,7 @@ const REPOSITORY = {
   repository: { type: 'string', description: 'Repository as "owner/repo". Omit to use the default from settings.' },
 }
 
-export function registerCoreTools({ tool, asRepo, client, liveConfig }) {
+export function registerCoreTools({ tool, asRepo, client, liveConfig, defaultCwd }) {
   const repoParams = (extra = {}) => ({ ...REPOSITORY, ...extra })
 
   // ------------------------------------------------------------------ repository
@@ -223,6 +224,7 @@ export function registerCoreTools({ tool, asRepo, client, liveConfig }) {
         name: args.name,
         label: args.label,
         contentType: args.contentType,
+        cwd: typeof defaultCwd === 'function' ? defaultCwd() : undefined,
       })
     },
   )
@@ -254,10 +256,10 @@ export function registerCoreTools({ tool, asRepo, client, liveConfig }) {
       const { owner, repo } = await asRepo(args, liveConfig())
       return generateReleaseNotes(await client(), {
         owner, repo,
-        tag: args.tag || args.tagName,
-        target: args.target || args.targetCommitish,
-        previousTag: args.previousTag || args.previousTagName,
-        configFile: args.configFile || args.configurationFilePath,
+        tag: args.tag,
+        target: args.target,
+        previousTag: args.previousTag,
+        configFile: args.configFile,
       })
     },
   )
@@ -336,16 +338,23 @@ export function registerCoreTools({ tool, asRepo, client, liveConfig }) {
 
   tool(
     'gh_release_preflight',
-    'Run automated pre-release audit on the plugin package: checks package.json version, cordis.patch.yml, CHANGELOG.md release notes, three READMEs (EN/RU/ZH), npm pack file sizes (<256 KiB), and git index hygiene.',
+    'Run automated pre-release audit on the plugin package: checks package.json version, cordis.patch.yml, CHANGELOG.md release notes, three READMEs (EN/RU/ZH), npm pack file sizes (<256 KiB), and git index hygiene. Running test suite requires confirm: true.',
     {
       cwd: { type: 'string', description: 'Directory to audit (defaults to workspace or process.cwd()).' },
-      runTests: { type: 'boolean', description: 'Whether to run npm test as part of the audit (default false).' },
+      runTests: { type: 'boolean', description: 'Whether to run npm test as part of the audit (requires confirm: true).' },
       maxFileSize: { type: 'number', description: 'Max allowed size in bytes per packaged file (default 262144).' },
+      confirm: { type: 'boolean', description: 'Must be true to execute npm test when runTests is true.' },
     },
     async (args) => {
+      if (args.runTests === true && args.confirm !== true) {
+        throw new Error('running test suite during preflight audit requires confirm: true')
+      }
+      const rawCwd = args.cwd || (typeof defaultCwd === 'function' ? defaultCwd() : process.cwd())
+      const validatedCwd = validateCwd(rawCwd)
       return runReleasePreflight({
-        cwd: args.cwd,
+        cwd: validatedCwd,
         runTests: args.runTests,
+        confirm: args.confirm,
         maxFileSize: args.maxFileSize,
       })
     },

package/lib/tools/register-write.js

@@ -210,7 +210,6 @@ export function registerWriteTools({ tool, asRepo, client, liveConfig, auth }) {
     'Report where the current access comes from and whether it works: the source (credential, environment, this plugin\'s sign-in, gh CLI), the account, and the remaining API rate limit. The value itself is never shown. Read-only.',
     {},
     async () => {
-      const cfg = liveConfig()
       const access = await auth.resolve()
       if (!access.value) return { configured: false, guidance: access.guidance }
       const github = await client()
@@ -240,6 +239,4 @@ export function registerWriteTools({ tool, asRepo, client, liveConfig, auth }) {
     },
   )
 
-  // keep the imports honest for callers that compose their own flows
-  return { accessFilePath, readAccessFile }
 }

package/lib/tools/release-preflight.js

@@ -1,3 +1,4 @@
+import { validateCwd } from '../scm-write.js'
 // lib/tools/release-preflight.js
 // Automated release preflight audit for DSH plugins according to
 // dhs-plugin-release-workflow and dsh-documentation-standard.
@@ -23,8 +24,12 @@ const FORBIDDEN_PACK_EXACT = ['AGENTS.md', '.env', '.env.local', 'deploy.sh']
  * @param {object} [deps] Injectable dependencies for unit testing
  */
 export async function runReleasePreflight(options = {}, deps = {}) {
-  const cwd = options.cwd || process.cwd()
+  const rawCwd = options.cwd || process.cwd()
+  const cwd = validateCwd(rawCwd)
   const runTests = options.runTests === true
+  if (runTests && options.confirm !== true) {
+    throw new Error('running test suite during preflight audit requires confirm: true')
+  }
   const maxFileSize = typeof options.maxFileSize === 'number' ? options.maxFileSize : MAX_FILE_SIZE_DEFAULT
   const exec = deps.execFile || pExecFile
   const fsRead = deps.readFileSync || readFileSync

package/lib/tools/releases.js

@@ -139,23 +139,61 @@ export async function listReleaseAssets(client, { owner, repo, tag, releaseId, l
   return { assets, count: assets.length, releaseId: id, rateLimit }
 }
 
-export async function uploadReleaseAsset(client, { owner, repo, tag, releaseId, filePath, name, label, contentType }) {
+const DISALLOWED_ROOTS = ['/etc', '/proc', '/sys', '/dev', '/root', '/bin', '/sbin', '/usr', '/boot', '/var/run']
+
+function checkDisallowedRoots(resolvedPath, sep) {
+  for (const root of DISALLOWED_ROOTS) {
+    if (resolvedPath === root || resolvedPath.startsWith(root + sep) || resolvedPath.startsWith(root + '/')) {
+      throw new Error(`access to system directory "${root}" is not allowed`)
+    }
+  }
+}
+
+export async function uploadReleaseAsset(client, { owner, repo, tag, releaseId, filePath, name, label, contentType, cwd }) {
   ensureRepo({ owner, repo })
-  if (!filePath) throw new Error('filePath is required')
-  const id = await resolveReleaseId(client, { owner, repo, tag, releaseId })
+  if (!filePath || typeof filePath !== 'string') throw new Error('filePath is required')
+  if (/[\x00-\x1f]/.test(filePath)) throw new Error('filePath may not contain control characters')
 
   const fs = await import('node:fs/promises')
   const path = await import('node:path')
 
+  const baseDir = cwd ? path.resolve(cwd) : null
+  const resolvedPath = baseDir ? path.resolve(baseDir, filePath) : path.resolve(filePath)
+
+  if (baseDir) {
+    if (resolvedPath !== baseDir && !resolvedPath.startsWith(baseDir + path.sep)) {
+      throw new Error(`filePath must reside within the workspace directory: ${filePath}`)
+    }
+  }
+
+  checkDisallowedRoots(resolvedPath, path.sep)
+
+  let realTarget = resolvedPath
+  try {
+    realTarget = await fs.realpath(resolvedPath)
+  } catch (err) {
+    throw new Error(`cannot access file "${filePath}": ${err && err.message}`)
+  }
+
+  checkDisallowedRoots(realTarget, path.sep)
+
+  if (baseDir) {
+    const realBase = await fs.realpath(baseDir).catch(() => baseDir)
+    if (realTarget !== realBase && !realTarget.startsWith(realBase + path.sep)) {
+      throw new Error(`filePath must reside within the workspace directory: ${filePath}`)
+    }
+  }
+
   let stats
   try {
-    stats = await fs.stat(filePath)
+    stats = await fs.stat(realTarget)
   } catch (err) {
     throw new Error(`cannot access file "${filePath}": ${err && err.message}`)
   }
   if (!stats.isFile()) throw new Error(`"${filePath}" is not a file`)
 
-  const fileBuffer = await fs.readFile(filePath)
+  const id = await resolveReleaseId(client, { owner, repo, tag, releaseId })
+  const fileBuffer = await fs.readFile(realTarget)
   const assetName = name || path.basename(filePath)
   const mimeType = contentType || 'application/octet-stream'
 
@@ -198,4 +236,3 @@ export async function generateReleaseNotes(client, { owner, repo, tag, target, p
     previousTag: previousTag || '',
   }
 }
-export { runReleasePreflight } from './release-preflight.js'

package/lib/tools/repos.js

@@ -1,3 +1,4 @@
+import { encodeRepoPath } from '../github.js'
 // Repository and file operations: metadata, file content at a ref, repository
 // search (its own quota), plus repository creation and edits.
 
@@ -36,8 +37,8 @@ export async function getRepo(client, { owner, repo }) {
 
 export async function getFile(client, { owner, repo, path, ref }) {
   ensureRepo({ owner, repo })
-  if (!path) throw new Error('path is required')
-  const { data } = await client.get(`/repos/${owner}/${repo}/contents/${path}`, {
+  const encodedPath = encodeRepoPath(path)
+  const { data } = await client.get(`/repos/${owner}/${repo}/contents/${encodedPath}`, {
     query: ref ? { ref } : undefined,
   })
   if (Array.isArray(data)) {

package/lib/tools/write-files.js

@@ -1,3 +1,4 @@
+import { encodeRepoPath } from '../github.js'
 // Writing files without a local checkout.
 //
 // A commit is built the way git builds it: blobs, a tree on top of the branch's tree, a
@@ -185,14 +186,14 @@ export async function uploadProject(client, {
 /** Delete one file, resolving its blob sha first (the contents API requires it). */
 export async function deleteFile(client, { owner, repo, path, message, branch } = {}) {
   ensureRepo({ owner, repo })
-  if (!path) throw new Error('path is required')
   if (!message) throw new Error('message is required')
-  const { data: current } = await client.get(`/repos/${owner}/${repo}/contents/${String(path).replace(/^\/+/, '')}`, {
+  const encodedPath = encodeRepoPath(path)
+  const { data: current } = await client.get(`/repos/${owner}/${repo}/contents/${encodedPath}`, {
     query: branch ? { ref: branch } : undefined,
   })
   const sha = current && current.sha
   if (!sha) throw new Error(`cannot resolve ${path}`)
-  const { data } = await client.del(`/repos/${owner}/${repo}/contents/${String(path).replace(/^\/+/, '')}`, {
+  const { data } = await client.del(`/repos/${owner}/${repo}/contents/${encodedPath}`, {
     body: { message, sha, ...(branch ? { branch } : {}) },
   })
   return { deleted: true, path, commit: data && data.commit ? data.commit.sha : null }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-github-ops",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "GitHub operations for DeepSeek Harness: releases, tags, a guarded generic API pass-through, workflow runs, secrets and sanitized mirror publication.",
   "license": "MIT",
   "type": "module",