network-proxy-guard 0.0.0-stage → 0.1.0

package/skill/network-proxy-guard/references/mobile-qr.md

@@ -0,0 +1,13 @@
+# Offline mobile QR delivery
+
+Use the same `node.json` used for Clash setup. The CLI builds a VLESS Reality URI and renders it locally as `shadowrocket-qr.png`; it also writes `vless-link.txt`. No online QR service is used. Reality X25519 public keys must be exactly 43 base64url characters. `flow` is included only when explicitly present in the node config; do not blindly add Vision to every VLESS node.
+
+```bash
+network-proxy-guard qr --config /private/path/node.json --output /private/path/mobile-qr
+# Or as part of an approved setup:
+network-proxy-guard setup --config /private/path/node.json --yes --qr-dir /private/path/mobile-qr
+```
+
+The QR payload is the complete VLESS URI. Both files are sensitive credentials and are created with owner-only permissions. Report file paths, not the URI, and never commit or upload them.
+
+Shadowrocket versions with VLESS Reality support can scan the QR. Other mobile apps may require a different URI or import format; do not promise universal compatibility. After import, use rule mode where appropriate and verify the egress matches the computer. Regenerate both desktop and mobile artifacts after an IP, port, UUID or Reality parameter change.

package/skill/network-proxy-guard/references/xray-reality.md

@@ -0,0 +1,31 @@
+# Xray VLESS Reality server runbook
+
+Use this runbook only when the user explicitly asks to create or change a server. It is not part of client-side setup by default.
+
+## Before changing anything
+
+- Confirm the VPS provider, OS, SSH access, intended domain/port, and whether a snapshot/backup exists.
+- Show the planned packages, services, ports, firewall/security-group changes, and restart window. Get separate VPS approval.
+- Preserve password login until key login has been tested in a second independent session. Do not lock the user out.
+- Use official Xray releases or another user-approved source; prefer pinned versions and integrity checks over piping an unknown script to a root shell.
+
+## Port diagnosis
+
+Check in order: Xray process/listener, host firewall, provider security group and instance association, provider upstream restrictions, local-to-VPS reachability, and external probes. `timeout` differs from `connection refused`. One `nc`, ping, or proxy-contaminated curl is not enough.
+
+Reality does not require TCP 443. Do not claim that 443 is inherently unblockable. Choose a reachable port based on evidence and keep only required ports exposed.
+
+## Reality parameters
+
+- Generate UUID/key material on the server and never expose the Reality private key in client files, logs, tickets, GitHub, or QR output.
+- Keep server `dest`/`serverNames` consistent with client SNI and public key/short ID.
+- Test candidate `dest` sites from the VPS repeatedly. A result for Apple, Microsoft, or any other domain on one machine is not a universal recommendation.
+- For intermittent handshakes, check duplicate Xray processes/SO_REUSEPORT, old test listeners, mismatched client/server configuration, and both debug logs before reinstalling.
+
+## Performance and acceptance
+
+BBR, `fq`, and buffer changes are optional experiments, not guaranteed optimizations. Record the previous sysctl values and compare repeated measurements before keeping them.
+
+Validate with a server-side loopback client and then a real external client. Check repeated TLS/HTTP success, egress IP, domestic DIRECT behavior, and speed. Remove temporary listeners/configs only after identifying them; do not use broad process kills. Leave a sanitized backup and maintenance commands.
+
+A provider IP replacement may also change the host, SSH keys, security groups, and open ports. Revalidate all of them before updating client profiles or mobile QR codes.

package/src/claude-reset.js

@@ -0,0 +1,227 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  assertInsideHome, atomicWrite, ensureDir, ensurePrivateDir, exists,
+  homeDir, relativeDisplay, run, timestamp,
+} from './utils.js';
+
+const SHELL_FILES = [
+  '.zshrc', '.zprofile', '.bashrc', '.bash_profile', '.profile',
+  '.config/fish/config.fish',
+];
+const LIBRARY_DIRS = [
+  'Application Support', 'Caches', 'Preferences', 'HTTPStorages',
+  'WebKit', 'Logs', 'Saved Application State', 'LaunchAgents',
+];
+const TRACE_NAME = /claude|cc[._ -]?switch|com\.anthropic\./i;
+const ENV_NAME = '(?:ANTHROPIC_[A-Z0-9_]+|CLAUDE_[A-Z0-9_]+|CC[._]?SWITCH[A-Z0-9_]*)';
+const SHELL_ENV = new RegExp(`^\\s*(?:export\\s+)?${ENV_NAME}\\s*=`);
+const FISH_ENV = new RegExp(`^\\s*set\\s+(?:-[A-Za-z]+\\s+)*${ENV_NAME}\\b`);
+const LAUNCH_ENV = [
+  'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_BASE_URL',
+  'ANTHROPIC_DEFAULT_HAIKU_MODEL', 'ANTHROPIC_DEFAULT_OPUS_MODEL',
+  'ANTHROPIC_DEFAULT_SONNET_MODEL', 'CLAUDE_CODE_USE_BEDROCK',
+  'CLAUDE_CODE_USE_VERTEX',
+];
+
+function sharedSkillDirs(home) {
+  const claudeDir = path.join(home, '.claude');
+  if (!exists(claudeDir) || fs.lstatSync(claudeDir).isSymbolicLink()) return [];
+  return fs.readdirSync(claudeDir)
+    .filter((entry) => entry.toLowerCase() === 'skills')
+    .map((entry) => path.join(claudeDir, entry));
+}
+
+function canonical(target) {
+  try {
+    return fs.realpathSync(target);
+  } catch {
+    return path.resolve(target);
+  }
+}
+
+function related(left, right) {
+  return left === right
+    || left.startsWith(`${right}${path.sep}`)
+    || right.startsWith(`${left}${path.sep}`);
+}
+
+function assertSafeTarget(target, protectedPaths) {
+  const resolved = path.resolve(target);
+  const real = canonical(resolved);
+  for (const protectedPath of protectedPaths) {
+    if (related(resolved, path.resolve(protectedPath)) || related(real, canonical(protectedPath))) {
+      throw new Error(`Refusing protected or shared path: ${resolved}`);
+    }
+  }
+}
+
+function addTarget(set, target, protectedPaths) {
+  if (!exists(target)) return;
+  const resolved = path.resolve(target);
+  assertSafeTarget(resolved, protectedPaths);
+  set.add(resolved);
+}
+
+function scanTargets(home, extraPaths = []) {
+  const targets = new Set();
+  const claudeDir = path.join(home, '.claude');
+  if (exists(claudeDir) && fs.lstatSync(claudeDir).isSymbolicLink()) {
+    throw new Error('Refusing to traverse a symlinked ~/.claude; review it manually');
+  }
+  const skillDirs = sharedSkillDirs(home);
+  const scanProtected = [
+    ...skillDirs, path.join(home, '.agents'), path.join(home, '.codex'),
+    path.join(home, '.network-proxy-guard'),
+  ];
+  if (exists(claudeDir)) {
+    for (const entry of fs.readdirSync(claudeDir)) {
+      if (entry.toLowerCase() !== 'skills') addTarget(targets, path.join(claudeDir, entry), scanProtected);
+    }
+  }
+  addTarget(targets, path.join(home, '.claude.json'), scanProtected);
+  addTarget(targets, path.join(home, '.cc-switch'), scanProtected);
+  for (const directory of LIBRARY_DIRS) {
+    const parent = path.join(home, 'Library', directory);
+    if (!exists(parent)) continue;
+    for (const entry of fs.readdirSync(parent)) {
+      if (TRACE_NAME.test(entry)) addTarget(targets, path.join(parent, entry), scanProtected);
+    }
+  }
+  const extraProtected = [claudeDir, ...scanProtected];
+  for (const extra of extraPaths) {
+    const resolved = path.resolve(extra);
+    assertInsideHome(resolved, home);
+    if (resolved === path.resolve(home)) throw new Error('Refusing to reset HOME itself');
+    if (!/claude|cc[._ -]?switch|anthropic/i.test(path.basename(resolved))) {
+      throw new Error(`Extra path must be a specifically named Claude/Anthropic/CC Switch item: ${resolved}`);
+    }
+    addTarget(targets, resolved, extraProtected);
+  }
+  const sorted = [...targets].sort();
+  return sorted.filter((target) => !sorted.some((parent) => parent !== target && target.startsWith(`${parent}${path.sep}`)));
+}
+
+function shellPlan(home) {
+  const edits = [];
+  const warnings = [];
+  for (const relative of SHELL_FILES) {
+    const file = path.join(home, relative);
+    if (!exists(file)) continue;
+    if (fs.lstatSync(file).isSymbolicLink()) {
+      warnings.push(`Symlinked shell file needs manual review: ${relative}`);
+      continue;
+    }
+    const original = fs.readFileSync(file, 'utf8');
+    const lines = original.split(/(?<=\n)/);
+    const content = lines.filter((line) => !SHELL_ENV.test(line) && !FISH_ENV.test(line)).join('');
+    const removed = lines.filter((line) => SHELL_ENV.test(line) || FISH_ENV.test(line)).length;
+    if (content !== original) edits.push({ file, relative, original, content, removed });
+  }
+  return { edits, warnings };
+}
+
+async function defaultLaunchEnv(home) {
+  if (process.platform !== 'darwin' || home !== homeDir()) return [];
+  const set = [];
+  for (const name of LAUNCH_ENV) {
+    const result = await run('launchctl', ['getenv', name], { timeout: 3000 });
+    if (result.ok && result.stdout.trim()) set.push(name);
+  }
+  return set;
+}
+
+async function defaultUnsetLaunchEnv(name) {
+  const result = await run('launchctl', ['unsetenv', name], { timeout: 3000 });
+  if (!result.ok) throw new Error(`Could not unset launchd variable ${name}`);
+}
+
+export async function resetClaude(options = {}) {
+  const home = path.resolve(options.home ?? homeDir());
+  const yes = Boolean(options.yes);
+  const extraPaths = options.extraPaths ?? [];
+  const targets = scanTargets(home, extraPaths);
+  const { edits, warnings } = shellPlan(home);
+  const launchEnv = await (options.runtime?.listLaunchEnv ?? defaultLaunchEnv)(home);
+  const unsetLaunchEnv = options.runtime?.unsetLaunchEnv ?? defaultUnsetLaunchEnv;
+  const preserved = [...sharedSkillDirs(home), path.join(home, '.agents'), path.join(home, '.codex')]
+    .filter(exists).map((target) => relativeDisplay(target, home));
+  const plan = {
+    mode: yes ? 'apply' : 'dry-run',
+    targets: targets.map((target) => relativeDisplay(target, home)),
+    shellEdits: edits.map((edit) => ({ file: edit.relative, removedLines: edit.removed })),
+    launchEnv,
+    preserved,
+    programs: 'preserved; reset does not uninstall Claude Code or desktop apps',
+    warnings: [
+      ...warnings,
+      'Local reset does not revoke service-side tokens',
+      'A local backup will retain the removed data until you delete it yourself',
+    ],
+  };
+  if (!yes) return { plan, backup: null };
+  if (!targets.length && !edits.length && !launchEnv.length) return { plan: { ...plan, mode: 'no-op' }, backup: null };
+
+  const backup = path.join(home, '.network-proxy-guard', 'backups', `claude-reset-${timestamp()}`);
+  const moved = [];
+  const edited = [];
+  const launchCleared = [];
+  try {
+    ensurePrivateDir(backup);
+    for (const target of targets) {
+      const relative = path.relative(home, target);
+      const destination = path.join(backup, 'files', relative);
+      ensureDir(path.dirname(destination));
+      fs.renameSync(target, destination);
+      moved.push({ target, destination });
+    }
+    for (const edit of edits) {
+      const destination = path.join(backup, 'shell', edit.relative);
+      ensureDir(path.dirname(destination));
+      fs.writeFileSync(destination, edit.original, { mode: 0o600 });
+      atomicWrite(edit.file, edit.content);
+      edited.push({ ...edit, destination });
+    }
+  } catch (error) {
+    for (const edit of edited.reverse()) atomicWrite(edit.file, edit.original);
+    for (const { target, destination } of moved.reverse()) {
+      ensureDir(path.dirname(target));
+      fs.renameSync(destination, target);
+    }
+    throw error;
+  }
+  const launchEnvFailed = [];
+  for (const name of launchEnv) {
+    try {
+      await unsetLaunchEnv(name);
+      launchCleared.push(name);
+    } catch {
+      launchEnvFailed.push(name);
+    }
+  }
+  const resultWarnings = [...warnings];
+  if (launchEnvFailed.length) resultWarnings.push(`Could not clear launchd variables: ${launchEnvFailed.join(', ')}`);
+  const manifest = {
+    createdAt: new Date().toISOString(),
+    moved: moved.map(({ target }) => relativeDisplay(target, home)),
+    shellEdited: edited.map(({ relative }) => relative),
+    launchEnvCleared: launchCleared,
+    launchEnvFailed,
+    preserved,
+  };
+  try {
+    atomicWrite(path.join(backup, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+  } catch (error) {
+    resultWarnings.push(`Could not write backup manifest: ${error.message}`);
+  }
+  return {
+    plan: {
+      ...plan,
+      mode: 'applied',
+      launchEnvCleared: launchCleared,
+      launchEnvFailed,
+      warnings: resultWarnings,
+    },
+    backup: relativeDisplay(backup, home),
+  };
+}

package/src/diagnostics.js

@@ -0,0 +1,157 @@
+import dns from 'node:dns';
+import net from 'node:net';
+import { URL } from 'node:url';
+import { displayUrl, publicEnv, run } from './utils.js';
+
+const GEO_SERVICES = [
+  { name: 'ipinfo', url: 'https://ipinfo.io/json' },
+  { name: 'ipwhois', url: 'https://ipwho.is/' },
+  { name: 'country.is', url: 'https://api.country.is/' },
+];
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'"'"'`)}'`;
+}
+
+function sshParts(options = {}) {
+  if (!options.sshTarget) return null;
+  if (options.sshTarget.startsWith('-')) throw new Error('Invalid SSH target');
+  const args = ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=8'];
+  if (options.sshPort) args.push('-p', String(options.sshPort));
+  if (options.identityFile) args.push('-i', options.identityFile);
+  args.push(options.sshTarget);
+  return args;
+}
+
+async function curl(url, options = {}) {
+  const args = ['--ipv4', '--noproxy', '*', '-sS', '--connect-timeout', '8', '--max-time', '25'];
+  if (options.headers) args.push('-D', '-', '-o', '/dev/null');
+  args.push(url);
+  const ssh = sshParts(options);
+  if (ssh) return run('ssh', [...ssh, `curl ${args.map(shellQuote).join(' ')}`], { timeout: 35_000 });
+  return run('curl', args, { timeout: 30_000 });
+}
+
+function headerValue(headers, name) {
+  const matches = [...headers.matchAll(new RegExp(`^${name}:\\s*(.+)$`, 'gim'))];
+  return matches.length ? matches.at(-1)[1].trim() : null;
+}
+
+function normalizeGeo(name, data) {
+  if (name === 'ipinfo') return { service: name, ip: data.ip, country: data.country, city: data.city, org: data.org };
+  if (name === 'ipwhois') return { service: name, ip: data.ip, country: data.country_code, city: data.city, org: data.connection?.asn_org };
+  return { service: name, ip: data.ip, country: data.country };
+}
+
+export function classifyGoogleRegion({ location, geo, serverDirect }) {
+  const evidenceIp = sharedUsIpv4(geo);
+  const hk = /google\.com\.hk(?:[/:]|$)/i.test(location ?? '');
+  if (hk && !serverDirect) return 'needs-vps-direct-test';
+  if (hk && evidenceIp) return 'google-region-mismatch';
+  if (hk) return 'provider-or-geo-data-mismatch';
+  if (location) return 'google-other-region-redirect';
+  return 'no-google-hk-redirect';
+}
+
+function sharedUsIpv4(geo) {
+  const counts = new Map();
+  for (const entry of geo) {
+    if (entry.country?.toUpperCase() === 'US' && net.isIP(entry.ip) === 4) {
+      counts.set(entry.ip, (counts.get(entry.ip) ?? 0) + 1);
+    }
+  }
+  return [...counts].find(([, count]) => count >= 2)?.[0] ?? null;
+}
+
+export async function detectGoogleRegion(options = {}) {
+  const serverDirect = Boolean(options.sshTarget || options.onVps);
+  const google = await curl('https://www.google.com/', { ...options, headers: true });
+  if (!google.ok) throw new Error(`Google test failed: ${google.stderr || 'network error'}`);
+  const location = headerValue(google.stdout, 'location');
+  const geo = await Promise.all(GEO_SERVICES.map(async ({ name, url }) => {
+    const result = await curl(url, options);
+    if (!result.ok) return { service: name, error: 'query failed' };
+    try {
+      return normalizeGeo(name, JSON.parse(result.stdout));
+    } catch {
+      return { service: name, error: 'invalid response' };
+    }
+  }));
+  const evidenceIp = sharedUsIpv4(geo);
+  return {
+    testedAt: new Date().toISOString(),
+    perspective: options.sshTarget ? 'VPS direct over SSH' : options.onVps ? 'VPS local direct' : 'local direct only',
+    serverDirect,
+    evidenceIp,
+    google: { url: 'https://www.google.com/', location },
+    geo,
+    classification: classifyGoogleRegion({ location, geo, serverDirect }),
+  };
+}
+
+function clean(value) {
+  return String(value ?? 'unknown').replace(/[|\r\n]/g, '/');
+}
+
+export function buildLisaTicket(report) {
+  if (report.classification !== 'google-region-mismatch') {
+    throw new Error(`Evidence does not justify this ticket yet: ${report.classification}`);
+  }
+  if (!report.serverDirect) throw new Error('A VPS-direct test is required before creating the ticket');
+  const ip = report.evidenceIp;
+  if (!ip || net.isIP(ip) !== 4) throw new Error('Two geolocation providers must agree on the same US IPv4');
+  const evidence = report.geo.filter((entry) => entry.ip === ip);
+  if (evidence.length < 2 || evidence.some((entry) => entry.country?.toUpperCase() !== 'US')) {
+    throw new Error('Ticket evidence is inconsistent');
+  }
+  const rows = evidence.map((entry) => `| ${clean(entry.service)} | ${clean(entry.country)} | ${clean(entry.city)} |`).join('\n');
+  return `主题：美国洛杉矶 VPS 的 IPv4 被 Google 判定为香港，申请核查并更换正确识别为美国的 IP\n\n你好，\n\n我购买的是美国洛杉矶地区的 VPS，当前实例公网 IPv4 为：${clean(ip)}。\n\n我在 VPS 本机直接访问 Google，未经过本地代理、VPN、浏览器 Cookie 或 Google 账号，访问 https://www.google.com/ 时跳转至：${clean(report.google.location)}。\n\n测试视角：${clean(report.perspective)}\n测试时间：${clean(report.testedAt)}\n\n第三方地理库结果：\n\n| 服务 | 国家/地区 | 城市 |\n|---|---|---|\n${rows}\n\n由于测试是在 VPS 本机直接完成，可以排除本地电脑代理规则、浏览器 Cookie 和本地 DNS 的影响。目前看起来是 Google 对该 IP 的地区识别与实例所在地区不一致，可能影响依赖 Google 地区判定的服务。\n\n请协助：\n1. 核查该 IP 是否存在历史地区标记或地区广播异常；\n2. 如无法修正，请更换一个能够被 Google 正确识别为美国的 IPv4；\n3. 操作前请说明是仅更换 IP，还是需要迁移实例/宿主机；\n4. 请勿直接重装、重置或迁移实例。如涉及这些操作，请先与我确认；\n5. 请确认更换后原实例数据、剩余使用时长及流量额度是否保留。\n\n我可以提供完整的响应头和地理库查询结果。谢谢。\n`;
+}
+
+async function curlMetrics(url, proxy) {
+  const args = ['-sS', '--connect-timeout', '8', '--max-time', '20', '-o', '/dev/null'];
+  if (proxy) args.push('-x', proxy);
+  else args.push('--noproxy', '*');
+  args.push('-w', '%{http_code}\\n%{remote_ip}\\n%{time_total}', url);
+  const result = await run('curl', args, { timeout: 25_000 });
+  const [httpCode, remoteIp, seconds] = result.stdout.trim().split('\n');
+  const connectionError = result.ok ? undefined : [url, proxy].filter(Boolean).reduce(
+    (message, sensitive) => message.split(sensitive).join(displayUrl(sensitive)),
+    result.stderr,
+  );
+  return { ok: result.ok, httpCode, remoteIp, seconds, error: connectionError };
+}
+
+async function systemProxy() {
+  if (process.platform !== 'darwin') return null;
+  const result = await run('scutil', ['--proxy'], { timeout: 3000 });
+  if (!result.ok) return null;
+  const output = {};
+  for (const name of ['HTTPEnable', 'HTTPProxy', 'HTTPPort', 'HTTPSEnable', 'HTTPSProxy', 'HTTPSPort', 'SOCKSEnable', 'SOCKSProxy', 'SOCKSPort', 'ProxyAutoConfigEnable']) {
+    const match = result.stdout.match(new RegExp(`${name}\\s*:\\s*([^\\n]+)`));
+    if (match) output[name] = match[1].trim();
+  }
+  return output;
+}
+
+export async function probeNetwork(options = {}) {
+  const target = new URL(options.url ?? 'https://www.google.com/generate_204');
+  if (!['http:', 'https:'].includes(target.protocol)) throw new Error('Only HTTP(S) probe URLs are supported');
+  const result = {
+    platform: process.platform,
+    arch: process.arch,
+    proxyEnv: publicEnv(),
+    systemProxy: await systemProxy(),
+    url: displayUrl(target.toString()),
+    proxy: displayUrl(options.proxy),
+  };
+  if (!options.offline) {
+    try {
+      result.dns = await dns.promises.lookup(target.hostname, { all: true });
+    } catch (error) {
+      result.dns = { error: error.message };
+    }
+    result.connection = await curlMetrics(target.toString(), options.proxy);
+  }
+  return result;
+}

package/src/install.js

@@ -0,0 +1,45 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TARGETS = {
+  agents: ['.agents', 'skills'],
+  claude: ['.claude', 'skills'],
+  codex: ['.codex', 'skills'],
+};
+
+export function installSkill(options = {}) {
+  const home = options.home ?? os.homedir();
+  const source = fileURLToPath(new URL('../skill/network-proxy-guard/', import.meta.url));
+  const root = options.target && !TARGETS[options.target]
+    ? path.resolve(options.target)
+    : path.join(home, ...(TARGETS[options.target ?? 'agents'] ?? TARGETS.agents));
+  const destination = path.join(root, 'network-proxy-guard');
+  if (fs.existsSync(destination) && !options.force) {
+    throw new Error(`Skill already exists: ${destination}. Use --force to back it up and replace it.`);
+  }
+  fs.mkdirSync(root, { recursive: true });
+  const temporary = `${destination}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    fs.cpSync(source, temporary, { recursive: true, errorOnExist: true, force: false });
+  } catch (error) {
+    fs.rmSync(temporary, { recursive: true, force: true });
+    throw error;
+  }
+  let backup = null;
+  try {
+    if (fs.existsSync(destination)) {
+      backup = `${destination}.backup-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+      fs.renameSync(destination, backup);
+    }
+    fs.renameSync(temporary, destination);
+  } catch (error) {
+    fs.rmSync(temporary, { recursive: true, force: true });
+    if (backup && fs.existsSync(backup) && !fs.existsSync(destination)) {
+      fs.renameSync(backup, destination);
+    }
+    throw error;
+  }
+  return { destination, backup };
+}

package/src/node-config.js

@@ -0,0 +1,103 @@
+import fs from 'node:fs';
+import net from 'node:net';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SHORT_ID = /^[0-9a-f]{2,16}$/i;
+
+export const SENSITIVE_SUFFIXES = [
+  'anthropic.com', 'claude.ai', 'openai.com', 'chatgpt.com', 'openrouter.ai',
+  'stripe.com', 'stripe.network', 'stripe.global',
+];
+
+export function readNodeConfig(file) {
+  const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+  return validateNodeConfig(parsed);
+}
+
+export function validateNodeConfig(input) {
+  const required = ['name', 'address', 'port', 'uuid', 'publicKey', 'shortId', 'serverName'];
+  for (const key of required) {
+    if (input[key] === undefined || input[key] === null || input[key] === '') {
+      throw new Error(`Missing node field: ${key}`);
+    }
+  }
+  const node = {
+    name: String(input.name).trim(),
+    address: String(input.address).trim(),
+    port: Number(input.port),
+    uuid: String(input.uuid).trim(),
+    publicKey: String(input.publicKey).trim(),
+    shortId: String(input.shortId).trim(),
+    serverName: String(input.serverName).trim(),
+    flow: input.flow === undefined ? '' : String(input.flow ?? '').trim(),
+    fingerprint: String(input.fingerprint ?? 'chrome').trim(),
+    spiderX: String(input.spiderX ?? '/').trim(),
+  };
+  if (!node.name || /[\r\n]/.test(node.name)) throw new Error('Invalid node name');
+  if (!Number.isInteger(node.port) || node.port < 1 || node.port > 65535) throw new Error('Invalid node port');
+  if (!UUID.test(node.uuid)) throw new Error('Invalid UUID');
+  if (!SHORT_ID.test(node.shortId) || node.shortId.length % 2 !== 0) throw new Error('Short ID must be even-length hex');
+  if (!/^[A-Za-z0-9_-]{43}$/.test(node.publicKey) || /REPLACE|EXAMPLE/i.test(node.publicKey)) {
+    throw new Error('Public key is missing or still a placeholder');
+  }
+  if (!/^[A-Za-z0-9.-]+$/.test(node.serverName)) throw new Error('Invalid serverName');
+  if (!/^[A-Za-z0-9:.-]+$/.test(node.address)) throw new Error('Invalid node address');
+  return node;
+}
+
+export function buildVlessUri(nodeInput) {
+  const node = validateNodeConfig(nodeInput);
+  const host = net.isIP(node.address) === 6 ? `[${node.address}]` : node.address;
+  const params = new URLSearchParams({
+    type: 'tcp',
+    security: 'reality',
+    encryption: 'none',
+    sni: node.serverName,
+    fp: node.fingerprint,
+    pbk: node.publicKey,
+    sid: node.shortId,
+    spx: node.spiderX,
+  });
+  if (node.flow) params.set('flow', node.flow);
+  return `vless://${node.uuid}@${host}:${node.port}?${params.toString()}#${encodeURIComponent(node.name)}`;
+}
+
+export function buildMihomoProfile(nodeInput) {
+  const node = validateNodeConfig(nodeInput);
+  const group = '节点选择';
+  const addressVersion = net.isIP(node.address);
+  const serverRule = addressVersion === 4
+    ? `IP-CIDR,${node.address}/32,DIRECT,no-resolve`
+    : addressVersion === 6
+      ? `IP-CIDR6,${node.address}/128,DIRECT,no-resolve`
+      : `DOMAIN,${node.address},DIRECT`;
+  const rules = [
+    serverRule,
+    ...SENSITIVE_SUFFIXES.map((suffix) => `DOMAIN-SUFFIX,${suffix},${group}`),
+    `GEOSITE,google,${group}`,
+    'GEOSITE,CN,DIRECT',
+    'GEOIP,CN,DIRECT,no-resolve',
+    `MATCH,${group}`,
+  ];
+  return {
+    proxies: [{
+      name: node.name,
+      type: 'vless',
+      server: node.address,
+      port: node.port,
+      uuid: node.uuid,
+      network: 'tcp',
+      udp: true,
+      tls: true,
+      servername: node.serverName,
+      ...(node.flow ? { flow: node.flow } : {}),
+      'client-fingerprint': node.fingerprint,
+      'reality-opts': {
+        'public-key': node.publicKey,
+        'short-id': node.shortId,
+      },
+    }],
+    'proxy-groups': [{ name: group, type: 'select', proxies: [node.name] }],
+    rules,
+  };
+}

package/src/qr.js

@@ -0,0 +1,21 @@
+import path from 'node:path';
+import QRCode from 'qrcode';
+import { buildVlessUri } from './node-config.js';
+import { atomicWrite, ensurePrivateDir, exists } from './utils.js';
+
+export async function generateMobileQr(node, outputDir) {
+  const uri = buildVlessUri(node);
+  const directory = path.resolve(outputDir);
+  if (!exists(directory)) ensurePrivateDir(directory);
+  const linkFile = path.join(directory, 'vless-link.txt');
+  const qrFile = path.join(directory, 'shadowrocket-qr.png');
+  const png = await QRCode.toBuffer(uri, {
+    errorCorrectionLevel: 'M',
+    margin: 3,
+    width: 512,
+    color: { dark: '#000000', light: '#FFFFFF' },
+  });
+  atomicWrite(linkFile, `${uri}\n`);
+  atomicWrite(qrFile, png);
+  return { linkFile, qrFile };
+}