{"record":{"id":"e02500b3b5c87946","repo":"docmirror/dev-sidecar","slug":"ip-ip","errorCode":null,"errorMessage":"无效的代理 IP 地址: ${ip}","messagePattern":"无效的代理 IP 地址: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/shell/scripts/set-system-proxy/index.js","lineNumber":301,"sourceCode":"/**\n * POSIX single-quote escaping: wraps `arg` in single quotes, escaping any\n * embedded single quotes with the '\\''-idiom.  This prevents shell\n * metacharacter expansion regardless of the character set of the value.\n * @param {string|number} arg\n * @returns {string}\n */\nfunction shellEscapeArg (arg) {\n  return \"'\" + String(arg).replace(/'/g, \"'\\\\''\") + \"'\"\n}\n\n/**\n * Strict-validate a proxy host (IPv4 / IPv6 / hostname) and throw if the\n * value looks suspicious.  This is a defence-in-depth guard for the sudo\n * execution path; the primary protection is `shellEscapeArg`.\n */\nfunction validateProxyIp (ip) {\n  if (typeof ip !== 'string' || !/^[\\w.\\-:[\\]]+$/.test(ip)) {\n    throw new Error(`无效的代理 IP 地址: ${ip}`)\n  }\n}\n\n/**\n * Strict-validate a TCP port number.\n */\nfunction validateProxyPort (port) {\n  const n = Number(port)\n  if (!Number.isInteger(n) || n < 1 || n > 65535) {\n    throw new Error(`无效的代理端口号: ${port}`)\n  }\n}\n\nfunction sudoExecMac (cmd) {\n  return new Promise((resolve, reject) => {\n    log.info('以管理员权限执行命令:', cmd)\n    sudoPrompt.exec(cmd, { name: 'dev-sidecar' }, (error, stdout, stderr) => {\n      if (stderr) {","sourceCodeStart":283,"sourceCodeEnd":319,"githubUrl":"https://github.com/docmirror/dev-sidecar/blob/7710cd56cce760c708f30b01d2d4056eb8c402d5/packages/core/src/shell/scripts/set-system-proxy/index.js#L283-L319","documentation":"validateProxyIp is a defence-in-depth guard on the macOS sudo execution path in set-system-proxy: the proxy host must be a string matching /^[\\w.\\-:[\\]]+$/ (letters, digits, underscore, dot, hyphen, colon, brackets) before it is embedded in networksetup commands. Any other value — or one containing shell metacharacters, spaces, slashes, or an empty string — throws this error to prevent command injection and malformed config.","triggerScenarios":"Calling the macOS set-system-proxy script with proxy ip set to: undefined/null/non-string; an empty string from config; a value containing spaces, 'http://' scheme prefix, or shell metacharacters ($;|&); a URL like 'http://127.0.0.1' passed where only the bare host '127.0.0.1' is expected.","commonSituations":"User config (~/.dev-sidecar/config.json) holding 'proxyHost': 'http://127.0.0.1' or an empty value; typos in the settings UI; config merged from remote shared/personal layers containing a full URL instead of a host.","solutions":["Set the proxy host to a bare hostname or IP without scheme: use `127.0.0.1`, not `http://127.0.0.1`.","Check ~/.dev-sidecar/config.json and the remote shared/personal config layers for a malformed ip/proxyHost value and fix it.","Remove any whitespace or special characters from the value (only [A-Za-z0-9_.-:[]) are accepted).","If you control the code, validate/normalize the host before invoking the script."],"exampleFix":"// before\nawait api.shell.setSystemProxy({ ip: 'http://127.0.0.1', port: 31181 })\n// after\nawait api.shell.setSystemProxy({ ip: '127.0.0.1', port: 31181 })","handlingStrategy":"validation","validationCode":"function isValidProxyIp(ip) {\n  return typeof ip === 'string' && /^[\\w.\\-:[\\]]+$/.test(ip)\n}\nconst ip = '127.0.0.1'\nif (!isValidProxyIp(ip)) throw new Error(`fix config: bad proxy ip ${JSON.stringify(ip)}`)","typeGuard":"function isProxyIp(v) {\n  return typeof v === 'string' && v.length > 0 && /^[\\w.\\-:[\\]]+$/.test(v)\n}","tryCatchPattern":"try {\n  await setSystemProxy({ ip, port })\n} catch (e) {\n  if (e.message.includes('无效的代理 IP 地址')) {\n    // strip scheme / trim and retry with a bare host\n    const bare = String(ip).replace(/^https?:\\/\\//, '').split('/')[0].trim()\n    if (isProxyIp(bare)) return setSystemProxy({ ip: bare, port })\n  }\n  throw e\n}","preventionTips":["Always pass a bare host/IP (127.0.0.1, localhost, ::1) — never a URL with scheme or path.","Validate the value in your settings UI before saving to ~/.dev-sidecar/config.json.","Audit remote shared/personal config layers for scheme-prefixed or empty host values.","Keep the value free of spaces and shell metacharacters; the regex allows only [\\w.\\-:[\\]]."],"tags":["mac","validation","system-proxy","input-validation"],"backgroundTag":"invalid-proxy-address","analyzedSha":"7710cd56cce760c708f30b01d2d4056eb8c402d5","analyzedAt":"2026-08-31T22:07:07.234Z","schemaVersion":2},"datasetVersion":"2026-08-31T22:30:34.772Z"}