@h0tp/shucky 0.1.0 → 0.4.4

package/lib/report.js

@@ -1,53 +1,53 @@
-'use strict';
-
-function human(result) {
-  const out = [];
-  out.push('shucky verdict: ' + result.verdict.toUpperCase() + '    (policy: ' + result.policy + ')');
-  out.push('target: ' + result.target +
-    (result.source ? '  source: ' + result.source : '') +
-    (result.version ? '@' + result.version : '') +
-    (result.relaxed ? '  [trusted: relaxed]' : ''));
-  const c = result.counts;
-  out.push('files scanned: ' + result.files.length +
-    '   findings: ' + result.findings.length +
-    '  (critical ' + (c.critical || 0) + ', high ' + (c.high || 0) +
-    ', medium ' + (c.medium || 0) + ', low ' + (c.low || 0) + ')');
-  out.push('');
-
-  if (result.findings.length === 0) {
-    out.push('  no deterministic red flags found.');
-  } else {
-    for (const f of result.findings) {
-      out.push('  [' + f.severity.toUpperCase() + '] ' + f.ruleId + '  ' + f.file + ':' + f.line);
-      if (f.snippet) out.push('      ' + f.snippet);
-      out.push('      → ' + f.why);
-    }
-  }
-
-  out.push('');
-  if (result.overriddenByApproval) {
-    const a = result.overriddenByApproval;
-    out.push('APPROVED OVERRIDE on file: "' + (a.reason || '(no reason)') + '"' +
-      ' — by ' + (a.approvedBy || '?') + ' on ' + (a.date || '?'));
-    out.push('(deterministic verdict before override was: ' + result.rawVerdict.toUpperCase() + ')');
-  }
-  if (result.requireAgentReview) {
-    out.push('NOTE: this is the deterministic floor only. A human/agent semantic review is');
-    out.push('still required (intent vs. description, novel obfuscation, social engineering).');
-  }
-  if (result.verdict === 'block') {
-    out.push('DECISION: BLOCKED — do not install without an explicit, logged override.');
-  } else if (result.verdict === 'warn') {
-    out.push('DECISION: WARN — review the findings above before trusting this skill.');
-  } else {
-    out.push('DECISION: PASS' + (result.overriddenByApproval ? ' (by override)' : ' (deterministic)') +
-      ' — still do the semantic review before trusting.');
-  }
-  return out.join('\n');
-}
-
-function json(result) {
-  return JSON.stringify(result, null, 2);
-}
-
-module.exports = { human, json };
+'use strict';
+
+function human(result) {
+  const out = [];
+  out.push('shucky verdict: ' + result.verdict.toUpperCase() + '    (policy: ' + result.policy + ')');
+  out.push('target: ' + result.target +
+    (result.source ? '  source: ' + result.source : '') +
+    (result.version ? '@' + result.version : '') +
+    (result.relaxed ? '  [trusted: relaxed]' : ''));
+  const c = result.counts;
+  out.push('files scanned: ' + result.files.length +
+    '   findings: ' + result.findings.length +
+    '  (critical ' + (c.critical || 0) + ', high ' + (c.high || 0) +
+    ', medium ' + (c.medium || 0) + ', low ' + (c.low || 0) + ')');
+  out.push('');
+
+  if (result.findings.length === 0) {
+    out.push('  no deterministic red flags found.');
+  } else {
+    for (const f of result.findings) {
+      out.push('  [' + f.severity.toUpperCase() + '] ' + f.ruleId + '  ' + f.file + ':' + f.line);
+      if (f.snippet) out.push('      ' + f.snippet);
+      out.push('      → ' + f.why);
+    }
+  }
+
+  out.push('');
+  if (result.overriddenByApproval) {
+    const a = result.overriddenByApproval;
+    out.push('APPROVED OVERRIDE on file: "' + (a.reason || '(no reason)') + '"' +
+      ' — by ' + (a.approvedBy || '?') + ' on ' + (a.date || '?'));
+    out.push('(deterministic verdict before override was: ' + result.rawVerdict.toUpperCase() + ')');
+  }
+  if (result.requireAgentReview) {
+    out.push('NOTE: this is the deterministic floor only. A human/agent semantic review is');
+    out.push('still required (intent vs. description, novel obfuscation, social engineering).');
+  }
+  if (result.verdict === 'block') {
+    out.push('DECISION: BLOCKED — do not install without an explicit, logged override.');
+  } else if (result.verdict === 'warn') {
+    out.push('DECISION: WARN — review the findings above before trusting this skill.');
+  } else {
+    out.push('DECISION: PASS' + (result.overriddenByApproval ? ' (by override)' : ' (deterministic)') +
+      ' — still do the semantic review before trusting.');
+  }
+  return out.join('\n');
+}
+
+function json(result) {
+  return JSON.stringify(result, null, 2);
+}
+
+module.exports = { human, json };

package/lib/rules.js

@@ -1,162 +1,162 @@
-'use strict';
-
-// Deterministic red-flag rules — the "floor" a malicious skill cannot talk the
-// reviewing agent out of. Patterns are intentionally conservative; the agent's
-// semantic review (see SKILL.md) covers intent and novel obfuscation on top.
-//
-// Some checks (browser_session, agent_state_access, IP-literal URLs) are adapted from
-// the community skill-vetter skill (spclaudehome, MIT-0).
-//
-// Each rule: { id, severity, patterns: [RegExp], why }
-
-const RULES = [
-  {
-    id: 'secret_access',
-    severity: 'critical',
-    patterns: [
-      /\.ssh\/(id_[a-z0-9]+|authorized_keys|config)/i,
-      /\bid_(rsa|ed25519|ecdsa|dsa)\b/i,
-      /\.aws\/credentials/i,
-      /\.config\/gcloud/i,
-      /\.git-credentials\b/i,
-      /(^|\s)\.netrc\b/i,
-      /(^|[^a-z0-9_.])\.npmrc\b/i,
-      /(^|\s)env\s*\|/,                 // `env | ...`  (dumping environment)
-      /\bprintenv\b/,
-      /169\.254\.169\.254/,             // cloud instance metadata
-      /metadata\.google\.internal/i,
-      /\/\.env(['"\s)]|$)/              // reading a .env file
-    ],
-    why: 'Accesses credentials/secrets (keys, env dump, cloud metadata, .env, .netrc).'
-  },
-  {
-    id: 'agent_state_access',
-    severity: 'medium',
-    patterns: [
-      /\b(SOUL|IDENTITY|MEMORY|USER)\.md\b/,
-      /\.config\/openclaw/i,
-      /\.claude\/(memory|projects)/i
-    ],
-    why: "Reads the agent's own memory/identity/state files (exfil or tampering risk)."
-  },
-  {
-    id: 'browser_session',
-    severity: 'high',
-    patterns: [
-      /cookies\.sqlite/i,
-      /(key4\.db|logins\.json|signons\.sqlite)/i,
-      /Login Data\b/,
-      /(Chrome|Chromium|Firefox|Edge|Safari|Brave)[^\n]*(Cookies|Profile|User Data)/i
-    ],
-    why: 'Accesses browser cookies / saved sessions / stored credentials.'
-  },
-  {
-    id: 'obfuscation',
-    severity: 'high',
-    patterns: [
-      /base64\s+(-d|--decode)[^\n]*\|\s*(sh|bash|zsh)/i,
-      /\|\s*base64\s+(-d|--decode)/i,
-      /\beval\s*[("`$]/,
-      /(curl|wget)\b[^\n|]*\|\s*(sh|bash|zsh)/i,   // curl ... | sh
-      /\b(gzip|gunzip|xxd|openssl)\b[^\n]*\|\s*(sh|bash)/i,
-      /\b(iex|invoke-expression)\b/i,              // PowerShell exec
-      /\b(python[0-9.]*|perl|ruby|node)\s+-(e|c)\b[^\n]*(base64|eval|exec\(|atob|fromCharCode|http)/i
-    ],
-    why: 'Decodes/obfuscates then executes code (classic dropper pattern).'
-  },
-  {
-    id: 'network_exfil',
-    severity: 'high',
-    patterns: [
-      /(curl|wget|nc|ncat)\b[^\n]*(--data|--data-binary|-d\s|@\$|@\/|@~|@-)/i,
-      /(curl|wget)\b[^\n]*\$\(/,                   // url/args built from command substitution
-      /\|\s*(curl|wget|nc|ncat)\b/i,               // piping data out
-      /(curl|wget)\b[^\n]*(webhook|requestbin|interactsh|burpcollab|pipedream|\.ngrok\.)/i,
-      /(Invoke-WebRequest|Invoke-RestMethod|iwr|Net\.WebClient|DownloadString|DownloadFile)/i,
-      /\b(scp|rsync|sftp)\b[^\n]*@[^\n]*:/i,       // copying data to a remote host
-      /https?:\/\/(?!127\.0\.0\.1|0\.0\.0\.0|localhost)\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}/i  // raw-IP URL
-    ],
-    why: 'Sends data to a remote host (possible exfiltration), incl. raw-IP endpoints.'
-  },
-  {
-    id: 'destructive',
-    severity: 'high',
-    patterns: [
-      /\brm\s+-[rf]{1,2}\b/i,
-      /\bmkfs\b/i,
-      /\bdd\b[^\n]*\bof=/i,
-      /\bchmod\s+-?R?\s*777\b/,
-      /:\(\)\s*\{\s*:\|:&\s*\}\s*;:/,              // fork bomb
-      /git\s+push\b[^\n]*--force/i,
-      /(^|\s)sudo\s/
-    ],
-    why: 'Destructive or privilege-escalating command.'
-  },
-  {
-    id: 'persistence',
-    severity: 'high',
-    patterns: [
-      /\bcrontab\b/i,
-      /\/etc\/(cron|init\.d)|\/Library\/Launch(Agents|Daemons)/i,
-      /\blaunchctl\s+(load|bootstrap|enable)/i,
-      /\bsystemctl\s+(--user\s+)?enable/i,
-      /HK(CU|LM)\\[^\n]*\\Run/i,
-      />>\s*~?\/?(\.bashrc|\.zshrc|\.profile|\.bash_profile|\.zprofile)\b/i,
-      /\bschtasks\b[^\n]*\/create/i
-    ],
-    why: 'Establishes persistence (autostart, cron, service, shell-rc, registry Run key).'
-  },
-  {
-    id: 'prompt_injection',
-    severity: 'high',
-    patterns: [
-      /ignore\b[^.\n]{0,40}(prior|previous|earlier|above)\b[^.\n]{0,30}(instruction|rule|prompt)/i,
-      /disregard\b[^.\n]{0,40}(prior|previous|earlier|above|instruction|rule)/i,
-      /do\s+not\s+(tell|inform|mention|report|alert|warn|reveal|disclose)\b/i,
-      /this\s+(skill|file|tool|package)\s+(is|has been|was)\s+[^.\n]{0,20}(safe|approved|trusted|pre-?approved|verified|vetted|legit)/i,
-      /\byou\s+are\s+now\b/i,
-      /\balways\s+run\b/i,
-      /do\s+not\s+(run|use|invoke)\s+(any\s+)?(scanner|security|review|shucky|check)/i
-    ],
-    why: 'Text aimed at the reviewing agent (instruction override / hiding actions).'
-  },
-  {
-    id: 'supply_chain',
-    severity: 'medium',
-    patterns: [
-      /(curl|wget)\b[^\n|]*\|\s*(sh|bash)/i,       // installer one-liner (also flagged as obfuscation)
-      /\bnpm\s+(i|install)\b[^\n]*(http|git\+|github:)/i,
-      /\bpip\s+install\b[^\n]*(http|git\+)/i,
-      /\bnpx\s+(--yes\s+|-y\s+)?[@a-z][^\n]*@latest/i
-    ],
-    why: 'Fetches/installs remote code at run time (unpinned supply chain).'
-  },
-  {
-    id: 'excessive_scope',
-    severity: 'low',
-    patterns: [
-      /\bnc\s+-l/i,                                // listener
-      /(^|\s)0\.0\.0\.0/,
-      /\bfind\s+\/\s/,                            // find / ...
-      /\bchmod\s+-R\b/i
-    ],
-    why: 'Broad/unscoped access beyond a typical skill task.'
-  }
-];
-
-// `undeclared_capability` is intentionally NOT a deterministic rule — it requires
-// comparing behavior against the SKILL.md description, which is the agent's job.
-
-const SUSPICIOUS_BINARY_EXT = new Set([
-  '.pyc', '.wasm', '.so', '.dylib', '.exe', '.dll', '.node', '.class', '.o', '.a', '.bin'
-]);
-
-function isProbablyBinary(buf) {
-  const n = Math.min(buf.length, 8000);
-  for (let i = 0; i < n; i++) {
-    if (buf[i] === 0) return true;
-  }
-  return false;
-}
-
-module.exports = { RULES, SUSPICIOUS_BINARY_EXT, isProbablyBinary };
+'use strict';
+
+// Deterministic red-flag rules — the "floor" a malicious skill cannot talk the
+// reviewing agent out of. Patterns are intentionally conservative; the agent's
+// semantic review (see SKILL.md) covers intent and novel obfuscation on top.
+//
+// Some checks (browser_session, agent_state_access, IP-literal URLs) are adapted from
+// the community skill-vetter skill (spclaudehome, MIT-0).
+//
+// Each rule: { id, severity, patterns: [RegExp], why }
+
+const RULES = [
+  {
+    id: 'secret_access',
+    severity: 'critical',
+    patterns: [
+      /\.ssh\/(id_[a-z0-9]+|authorized_keys|config)/i,
+      /\bid_(rsa|ed25519|ecdsa|dsa)\b/i,
+      /\.aws\/credentials/i,
+      /\.config\/gcloud/i,
+      /\.git-credentials\b/i,
+      /(^|\s)\.netrc\b/i,
+      /(^|[^a-z0-9_.])\.npmrc\b/i,
+      /(^|\s)env\s*\|/,                 // `env | ...`  (dumping environment)
+      /\bprintenv\b/,
+      /169\.254\.169\.254/,             // cloud instance metadata
+      /metadata\.google\.internal/i,
+      /\/\.env(['"\s)]|$)/              // reading a .env file
+    ],
+    why: 'Accesses credentials/secrets (keys, env dump, cloud metadata, .env, .netrc).'
+  },
+  {
+    id: 'agent_state_access',
+    severity: 'medium',
+    patterns: [
+      /\b(SOUL|IDENTITY|MEMORY|USER)\.md\b/,
+      /\.config\/openclaw/i,
+      /\.claude\/(memory|projects)/i
+    ],
+    why: "Reads the agent's own memory/identity/state files (exfil or tampering risk)."
+  },
+  {
+    id: 'browser_session',
+    severity: 'high',
+    patterns: [
+      /cookies\.sqlite/i,
+      /(key4\.db|logins\.json|signons\.sqlite)/i,
+      /Login Data\b/,
+      /(Chrome|Chromium|Firefox|Edge|Safari|Brave)[^\n]*(Cookies|Profile|User Data)/i
+    ],
+    why: 'Accesses browser cookies / saved sessions / stored credentials.'
+  },
+  {
+    id: 'obfuscation',
+    severity: 'high',
+    patterns: [
+      /base64\s+(-d|--decode)[^\n]*\|\s*(sh|bash|zsh)/i,
+      /\|\s*base64\s+(-d|--decode)/i,
+      /\beval\s*[("`$]/,
+      /(curl|wget)\b[^\n|]*\|\s*(sh|bash|zsh)/i,   // curl ... | sh
+      /\b(gzip|gunzip|xxd|openssl)\b[^\n]*\|\s*(sh|bash)/i,
+      /\b(iex|invoke-expression)\b/i,              // PowerShell exec
+      /\b(python[0-9.]*|perl|ruby|node)\s+-(e|c)\b[^\n]*(base64|eval|exec\(|atob|fromCharCode|http)/i
+    ],
+    why: 'Decodes/obfuscates then executes code (classic dropper pattern).'
+  },
+  {
+    id: 'network_exfil',
+    severity: 'high',
+    patterns: [
+      /(curl|wget|nc|ncat)\b[^\n]*(--data|--data-binary|-d\s|@\$|@\/|@~|@-)/i,
+      /(curl|wget)\b[^\n]*\$\(/,                   // url/args built from command substitution
+      /\|\s*(curl|wget|nc|ncat)\b/i,               // piping data out
+      /(curl|wget)\b[^\n]*(webhook|requestbin|interactsh|burpcollab|pipedream|\.ngrok\.)/i,
+      /(Invoke-WebRequest|Invoke-RestMethod|iwr|Net\.WebClient|DownloadString|DownloadFile)/i,
+      /\b(scp|rsync|sftp)\b[^\n]*@[^\n]*:/i,       // copying data to a remote host
+      /https?:\/\/(?!127\.0\.0\.1|0\.0\.0\.0|localhost)\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}/i  // raw-IP URL
+    ],
+    why: 'Sends data to a remote host (possible exfiltration), incl. raw-IP endpoints.'
+  },
+  {
+    id: 'destructive',
+    severity: 'high',
+    patterns: [
+      /\brm\s+-[rf]{1,2}\b/i,
+      /\bmkfs\b/i,
+      /\bdd\b[^\n]*\bof=/i,
+      /\bchmod\s+-?R?\s*777\b/,
+      /:\(\)\s*\{\s*:\|:&\s*\}\s*;:/,              // fork bomb
+      /git\s+push\b[^\n]*--force/i,
+      /(^|\s)sudo\s/
+    ],
+    why: 'Destructive or privilege-escalating command.'
+  },
+  {
+    id: 'persistence',
+    severity: 'high',
+    patterns: [
+      /\bcrontab\b/i,
+      /\/etc\/(cron|init\.d)|\/Library\/Launch(Agents|Daemons)/i,
+      /\blaunchctl\s+(load|bootstrap|enable)/i,
+      /\bsystemctl\s+(--user\s+)?enable/i,
+      /HK(CU|LM)\\[^\n]*\\Run/i,
+      />>\s*~?\/?(\.bashrc|\.zshrc|\.profile|\.bash_profile|\.zprofile)\b/i,
+      /\bschtasks\b[^\n]*\/create/i
+    ],
+    why: 'Establishes persistence (autostart, cron, service, shell-rc, registry Run key).'
+  },
+  {
+    id: 'prompt_injection',
+    severity: 'high',
+    patterns: [
+      /ignore\b[^.\n]{0,40}(prior|previous|earlier|above)\b[^.\n]{0,30}(instruction|rule|prompt)/i,
+      /disregard\b[^.\n]{0,40}(prior|previous|earlier|above|instruction|rule)/i,
+      /do\s+not\s+(tell|inform|mention|report|alert|warn|reveal|disclose)\b/i,
+      /this\s+(skill|file|tool|package)\s+(is|has been|was)\s+[^.\n]{0,20}(safe|approved|trusted|pre-?approved|verified|vetted|legit)/i,
+      /\byou\s+are\s+now\b/i,
+      /\balways\s+run\b/i,
+      /do\s+not\s+(run|use|invoke)\s+(any\s+)?(scanner|security|review|shucky|check)/i
+    ],
+    why: 'Text aimed at the reviewing agent (instruction override / hiding actions).'
+  },
+  {
+    id: 'supply_chain',
+    severity: 'medium',
+    patterns: [
+      /(curl|wget)\b[^\n|]*\|\s*(sh|bash)/i,       // installer one-liner (also flagged as obfuscation)
+      /\bnpm\s+(i|install)\b[^\n]*(http|git\+|github:)/i,
+      /\bpip\s+install\b[^\n]*(http|git\+)/i,
+      /\bnpx\s+(--yes\s+|-y\s+)?[@a-z][^\n]*@latest/i
+    ],
+    why: 'Fetches/installs remote code at run time (unpinned supply chain).'
+  },
+  {
+    id: 'excessive_scope',
+    severity: 'low',
+    patterns: [
+      /\bnc\s+-l/i,                                // listener
+      /(^|\s)0\.0\.0\.0/,
+      /\bfind\s+\/\s/,                            // find / ...
+      /\bchmod\s+-R\b/i
+    ],
+    why: 'Broad/unscoped access beyond a typical skill task.'
+  }
+];
+
+// `undeclared_capability` is intentionally NOT a deterministic rule — it requires
+// comparing behavior against the SKILL.md description, which is the agent's job.
+
+const SUSPICIOUS_BINARY_EXT = new Set([
+  '.pyc', '.wasm', '.so', '.dylib', '.exe', '.dll', '.node', '.class', '.o', '.a', '.bin'
+]);
+
+function isProbablyBinary(buf) {
+  const n = Math.min(buf.length, 8000);
+  for (let i = 0; i < n; i++) {
+    if (buf[i] === 0) return true;
+  }
+  return false;
+}
+
+module.exports = { RULES, SUSPICIOUS_BINARY_EXT, isProbablyBinary };

package/lib/safeurl.js

@@ -0,0 +1,139 @@
+'use strict';
+
+// shucky SSRF guard — validate a remote URL before any fetch.
+// shucky is a security tool that now reaches out to the network; this is the gate that
+// keeps an attacker-controlled "source" from pointing the fetcher at internal services
+// or the cloud-metadata endpoint. NO sockets here — pure validation + DNS lookup, so it
+// is unit-testable with an injected resolver. The redirect re-guard lives in fetch.js,
+// which calls assertSafeHttpsUrl() again on every hop.
+
+const dns = require('dns');
+const net = require('net');
+
+// ---- IPv4 ----------------------------------------------------------------
+
+function ipv4ToInt(ip) {
+  const parts = ip.split('.');
+  if (parts.length !== 4) return null;
+  let n = 0;
+  for (let i = 0; i < 4; i++) {
+    const p = Number(parts[i]);
+    if (!Number.isInteger(p) || p < 0 || p > 255) return null;
+    n = (n << 8) + p;
+  }
+  return n >>> 0;
+}
+
+function inCidr4(intIp, cidr) {
+  const slash = cidr.split('/');
+  const baseInt = ipv4ToInt(slash[0]);
+  const bits = Number(slash[1]);
+  if (baseInt === null) return false;
+  const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+  return (intIp & mask) === (baseInt & mask);
+}
+
+// Private, loopback, link-local (incl. 169.254.169.254 metadata), CGNAT, reserved, multicast.
+const BLOCKED_V4 = [
+  '0.0.0.0/8', '10.0.0.0/8', '100.64.0.0/10', '127.0.0.0/8',
+  '169.254.0.0/16', '172.16.0.0/12', '192.0.0.0/24', '192.168.0.0/16',
+  '198.18.0.0/15', '224.0.0.0/4', '240.0.0.0/4'
+];
+
+function isBlockedIPv4(ip) {
+  const n = ipv4ToInt(ip);
+  if (n === null) return true; // unparseable → block (fail closed)
+  for (const c of BLOCKED_V4) if (inCidr4(n, c)) return true;
+  return false;
+}
+
+// ---- IPv6 ----------------------------------------------------------------
+
+function isBlockedIPv6(ip) {
+  let s = ip.toLowerCase().replace(/^\[/, '').replace(/\]$/, '');
+  // IPv4-mapped / -embedded (::ffff:1.2.3.4, ::1.2.3.4) → validate the v4 part.
+  const v4 = s.match(/(\d+\.\d+\.\d+\.\d+)$/);
+  if (v4 && (s.indexOf('::ffff:') === 0 || s.indexOf('::') === 0)) return isBlockedIPv4(v4[1]);
+  if (s === '::1' || s === '::') return true;            // loopback / unspecified
+  if (/^fe[89ab]/.test(s)) return true;                  // fe80::/10 link-local
+  if (s[0] === 'f' && (s[1] === 'c' || s[1] === 'd')) return true; // fc00::/7 unique-local
+  if (s[0] === 'f' && s[1] === 'f') return true;         // ff00::/8 multicast
+  return false;
+}
+
+function isBlockedIp(ip) {
+  return ip.indexOf(':') !== -1 ? isBlockedIPv6(ip) : isBlockedIPv4(ip);
+}
+
+// ---- hostnames -----------------------------------------------------------
+
+const BLOCKED_HOSTNAMES = [
+  'localhost',
+  'metadata.google.internal',
+  'metadata.goog',
+  'instance-data',
+  'metadata' // common k8s/cloud alias
+];
+
+function isBlockedHostname(host) {
+  host = host.toLowerCase();
+  if (BLOCKED_HOSTNAMES.indexOf(host) !== -1) return true;
+  if (/\.(internal|local|localhost|home\.arpa)$/.test(host)) return true;
+  return false;
+}
+
+// ---- public API ----------------------------------------------------------
+
+function resolveAll(host, resolver) {
+  const lookup = resolver || dns.lookup;
+  return new Promise(function (res, rej) {
+    lookup(host, { all: true }, function (err, addrs) {
+      if (err) return rej(err);
+      if (!Array.isArray(addrs)) addrs = addrs ? [{ address: addrs }] : [];
+      res(addrs.map(function (a) { return typeof a === 'string' ? a : a.address; }));
+    });
+  });
+}
+
+// Throws if `input` is unsafe to fetch; resolves to the parsed URL otherwise.
+// opts: { allowHttp?:bool, resolver?:fn } — resolver is injectable for tests.
+async function assertSafeHttpsUrl(input, opts) {
+  opts = opts || {};
+  let u;
+  try { u = new URL(input); }
+  catch (e) { throw new Error('invalid URL: ' + input); }
+
+  if (u.protocol !== 'https:' && !(opts.allowHttp && u.protocol === 'http:')) {
+    throw new Error('refusing non-https URL: ' + input);
+  }
+
+  const bareHost = u.hostname.replace(/^\[/, '').replace(/\]$/, '');
+  if (!bareHost) throw new Error('URL has no host: ' + input);
+  if (isBlockedHostname(bareHost)) throw new Error('refusing internal host: ' + u.hostname);
+
+  // Literal IP → check directly (no DNS).
+  if (net.isIP(bareHost)) {
+    if (isBlockedIp(bareHost)) throw new Error('refusing internal/reserved IP: ' + u.hostname);
+    return u;
+  }
+
+  // Hostname → resolve and reject if ANY address is internal (DNS-rebind defense).
+  let addrs;
+  try { addrs = await resolveAll(bareHost, opts.resolver); }
+  catch (e) { throw new Error('DNS resolution failed for ' + u.hostname + ': ' + e.message); }
+  if (!addrs.length) throw new Error('no DNS records for ' + u.hostname);
+  for (const ip of addrs) {
+    if (isBlockedIp(ip)) {
+      throw new Error('host ' + u.hostname + ' resolves to internal IP ' + ip + ' — SSRF blocked');
+    }
+  }
+  return u;
+}
+
+module.exports = {
+  assertSafeHttpsUrl,
+  isBlockedIp,
+  isBlockedIPv4,
+  isBlockedIPv6,
+  isBlockedHostname
+};