@h0tp/shucky 0.1.0 → 0.4.5

package/lib/scan.js

@@ -1,148 +1,148 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { RULES, SUSPICIOUS_BINARY_EXT, isProbablyBinary } = require('./rules');
-const { loadApprovals, isApproved } = require('./approvals');
-
-const MAX_READ_BYTES = 512 * 1024;
-const SEVERITY_RANK = { low: 1, medium: 2, high: 3, critical: 4 };
-
-function severityRank(s) { return SEVERITY_RANK[s] || 0; }
-
-function walk(dir, out) {
-  let entries;
-  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
-  catch (e) { return out; }
-  for (const e of entries) {
-    if (e.name === '.git' || e.name === 'node_modules') continue;
-    const full = path.join(dir, e.name);
-    if (e.isDirectory()) walk(full, out);
-    else if (e.isFile()) out.push(full);
-  }
-  return out;
-}
-
-function isTrusted(source, trustedSources) {
-  if (!source || !Array.isArray(trustedSources)) return false;
-  const owner = String(source).toLowerCase().split('/')[0];
-  return trustedSources.some(function (t) {
-    t = String(t).toLowerCase();
-    return owner === t || String(source).toLowerCase() === t;
-  });
-}
-
-// Apply rules to one file's lines.
-// In Markdown, code-execution rules run only INSIDE fenced code blocks; prose is checked for
-// prompt_injection only — so a doc that merely *mentions* "curl | sh" in a sentence isn't
-// flagged, but a real command in a ``` block is. Non-Markdown files (scripts, etc.) get every
-// rule on every line.
-function scanLines(rel, lines, isMarkdown, config, findings) {
-  let inFence = false;
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (isMarkdown && /^\s*(```|~~~)/.test(line)) { inFence = !inFence; continue; }
-    for (const rule of RULES) {
-      if (config.rules && config.rules[rule.id] === false) continue;
-      if (isMarkdown && !inFence && rule.id !== 'prompt_injection') continue;
-      for (const re of rule.patterns) {
-        if (re.test(line)) {
-          findings.push({
-            ruleId: rule.id, severity: rule.severity, file: rel, line: i + 1,
-            snippet: line.trim().slice(0, 160), why: rule.why
-          });
-          break;
-        }
-      }
-    }
-  }
-}
-
-// Read files as text and apply rules. NEVER executes anything.
-function scanTarget(targetPath, config) {
-  const stat = fs.statSync(targetPath);
-  const baseDir = stat.isDirectory() ? targetPath : path.dirname(targetPath);
-  const files = stat.isDirectory() ? walk(targetPath, []) : [targetPath];
-
-  const findings = [];
-  const fileInfos = [];
-
-  for (const f of files) {
-    const rel = path.relative(baseDir, f) || path.basename(f);
-    const ext = path.extname(f).toLowerCase();
-    let size = 0;
-    try { size = fs.statSync(f).size; } catch (e) { /* ignore */ }
-
-    let buf;
-    try { buf = fs.readFileSync(f); }
-    catch (e) { fileInfos.push({ path: rel, size: size, note: 'unreadable' }); continue; }
-
-    if (isProbablyBinary(buf)) {
-      fileInfos.push({ path: rel, size: size, binary: true });
-      if (SUSPICIOUS_BINARY_EXT.has(ext)) {
-        findings.push({
-          ruleId: 'obfuscation', severity: 'high', file: rel, line: 0,
-          snippet: '<binary ' + ext + '>',
-          why: 'Ships compiled/opaque executable code inside a skill.'
-        });
-      }
-      continue;
-    }
-
-    if (size > MAX_READ_BYTES) {
-      fileInfos.push({ path: rel, size: size, note: 'skipped (>512KB)' });
-      continue;
-    }
-
-    fileInfos.push({ path: rel, size: size });
-    const isMarkdown = ext === '.md' || ext === '.markdown';
-    scanLines(rel, buf.toString('utf8').split(/\r?\n/), isMarkdown, config, findings);
-  }
-
-  const trusted = isTrusted(config.source, config.trustedSources);
-  const relaxed = trusted && config.trustedSourcePolicy === 'relax';
-
-  const counts = { low: 0, medium: 0, high: 0, critical: 0 };
-  for (const f of findings) counts[f.severity] = (counts[f.severity] || 0) + 1;
-
-  // Severities that count toward the verdict (relax drops low/medium for trusted sources).
-  const counting = findings.filter(function (f) {
-    if (relaxed && (f.severity === 'low' || f.severity === 'medium')) return false;
-    return true;
-  }).map(function (f) { return f.severity; });
-
-  const failOn = config.failOn || ['high', 'critical'];
-  const warnOn = config.warnOn || ['medium'];
-  const hits = function (set) { return set.some(function (s) { return counting.indexOf(s) !== -1; }); };
-
-  let rawVerdict = 'pass';
-  if (hits(failOn)) rawVerdict = 'block';
-  else if (hits(warnOn)) rawVerdict = 'warn';
-
-  // Persistent override: an exact source@version approved earlier forces pass (a logged override).
-  let overriddenByApproval = null;
-  if (config.source && config.version) {
-    overriddenByApproval = isApproved(loadApprovals(config), config.source, config.version);
-  }
-  const verdict = overriddenByApproval ? 'pass' : rawVerdict;
-
-  findings.sort(function (a, b) { return severityRank(b.severity) - severityRank(a.severity); });
-
-  return {
-    target: targetPath,
-    source: config.source || null,
-    version: config.version || null,
-    trusted: trusted,
-    relaxed: relaxed,
-    policy: config.policy,
-    files: fileInfos,
-    findings: findings,
-    counts: counts,
-    verdict: verdict,
-    rawVerdict: rawVerdict,
-    overriddenByApproval: overriddenByApproval,
-    requireAgentReview: config.requireAgentReview !== false
-  };
-}
-
-module.exports = { scanTarget, severityRank, isTrusted };
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { RULES, SUSPICIOUS_BINARY_EXT, isProbablyBinary } = require('./rules');
+const { loadApprovals, isApproved } = require('./approvals');
+
+const MAX_READ_BYTES = 512 * 1024;
+const SEVERITY_RANK = { low: 1, medium: 2, high: 3, critical: 4 };
+
+function severityRank(s) { return SEVERITY_RANK[s] || 0; }
+
+function walk(dir, out) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch (e) { return out; }
+  for (const e of entries) {
+    if (e.name === '.git' || e.name === 'node_modules') continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) walk(full, out);
+    else if (e.isFile()) out.push(full);
+  }
+  return out;
+}
+
+function isTrusted(source, trustedSources) {
+  if (!source || !Array.isArray(trustedSources)) return false;
+  const owner = String(source).toLowerCase().split('/')[0];
+  return trustedSources.some(function (t) {
+    t = String(t).toLowerCase();
+    return owner === t || String(source).toLowerCase() === t;
+  });
+}
+
+// Apply rules to one file's lines.
+// In Markdown, code-execution rules run only INSIDE fenced code blocks; prose is checked for
+// prompt_injection only — so a doc that merely *mentions* "curl | sh" in a sentence isn't
+// flagged, but a real command in a ``` block is. Non-Markdown files (scripts, etc.) get every
+// rule on every line.
+function scanLines(rel, lines, isMarkdown, config, findings) {
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (isMarkdown && /^\s*(```|~~~)/.test(line)) { inFence = !inFence; continue; }
+    for (const rule of RULES) {
+      if (config.rules && config.rules[rule.id] === false) continue;
+      if (isMarkdown && !inFence && rule.id !== 'prompt_injection') continue;
+      for (const re of rule.patterns) {
+        if (re.test(line)) {
+          findings.push({
+            ruleId: rule.id, severity: rule.severity, file: rel, line: i + 1,
+            snippet: line.trim().slice(0, 160), why: rule.why
+          });
+          break;
+        }
+      }
+    }
+  }
+}
+
+// Read files as text and apply rules. NEVER executes anything.
+function scanTarget(targetPath, config) {
+  const stat = fs.statSync(targetPath);
+  const baseDir = stat.isDirectory() ? targetPath : path.dirname(targetPath);
+  const files = stat.isDirectory() ? walk(targetPath, []) : [targetPath];
+
+  const findings = [];
+  const fileInfos = [];
+
+  for (const f of files) {
+    const rel = path.relative(baseDir, f) || path.basename(f);
+    const ext = path.extname(f).toLowerCase();
+    let size = 0;
+    try { size = fs.statSync(f).size; } catch (e) { /* ignore */ }
+
+    let buf;
+    try { buf = fs.readFileSync(f); }
+    catch (e) { fileInfos.push({ path: rel, size: size, note: 'unreadable' }); continue; }
+
+    if (isProbablyBinary(buf)) {
+      fileInfos.push({ path: rel, size: size, binary: true });
+      if (SUSPICIOUS_BINARY_EXT.has(ext)) {
+        findings.push({
+          ruleId: 'obfuscation', severity: 'high', file: rel, line: 0,
+          snippet: '<binary ' + ext + '>',
+          why: 'Ships compiled/opaque executable code inside a skill.'
+        });
+      }
+      continue;
+    }
+
+    if (size > MAX_READ_BYTES) {
+      fileInfos.push({ path: rel, size: size, note: 'skipped (>512KB)' });
+      continue;
+    }
+
+    fileInfos.push({ path: rel, size: size });
+    const isMarkdown = ext === '.md' || ext === '.markdown';
+    scanLines(rel, buf.toString('utf8').split(/\r?\n/), isMarkdown, config, findings);
+  }
+
+  const trusted = isTrusted(config.source, config.trustedSources);
+  const relaxed = trusted && config.trustedSourcePolicy === 'relax';
+
+  const counts = { low: 0, medium: 0, high: 0, critical: 0 };
+  for (const f of findings) counts[f.severity] = (counts[f.severity] || 0) + 1;
+
+  // Severities that count toward the verdict (relax drops low/medium for trusted sources).
+  const counting = findings.filter(function (f) {
+    if (relaxed && (f.severity === 'low' || f.severity === 'medium')) return false;
+    return true;
+  }).map(function (f) { return f.severity; });
+
+  const failOn = config.failOn || ['high', 'critical'];
+  const warnOn = config.warnOn || ['medium'];
+  const hits = function (set) { return set.some(function (s) { return counting.indexOf(s) !== -1; }); };
+
+  let rawVerdict = 'pass';
+  if (hits(failOn)) rawVerdict = 'block';
+  else if (hits(warnOn)) rawVerdict = 'warn';
+
+  // Persistent override: an exact source@version approved earlier forces pass (a logged override).
+  let overriddenByApproval = null;
+  if (config.source && config.version) {
+    overriddenByApproval = isApproved(loadApprovals(config), config.source, config.version);
+  }
+  const verdict = overriddenByApproval ? 'pass' : rawVerdict;
+
+  findings.sort(function (a, b) { return severityRank(b.severity) - severityRank(a.severity); });
+
+  return {
+    target: targetPath,
+    source: config.source || null,
+    version: config.version || null,
+    trusted: trusted,
+    relaxed: relaxed,
+    policy: config.policy,
+    files: fileInfos,
+    findings: findings,
+    counts: counts,
+    verdict: verdict,
+    rawVerdict: rawVerdict,
+    overriddenByApproval: overriddenByApproval,
+    requireAgentReview: config.requireAgentReview !== false
+  };
+}
+
+module.exports = { scanTarget, severityRank, isTrusted };

package/lib/sources.js

@@ -0,0 +1,311 @@
+'use strict';
+
+// shucky source resolver — parse a source string into a structured target.
+// Portions ported from vercel-labs/skills `src/source-parser.ts` (MIT). See NOTICE.
+// Pure string → struct: NO I/O, NO network. Trivially unit-testable.
+//
+// ParsedSource = { type, url, subpath?, ref?, skillFilter?, localPath? }
+//   type ∈ local | github | gitlab | git | well-known | rawfile | gist
+// shucky widens the reference set with `rawfile` (a direct SKILL.md / .md URL,
+// incl. github /blob/ and gitlab /-/raw/) and `gist`, so "from anywhere" is literally true.
+
+const { isAbsolute, resolve } = require('path');
+
+// Common shorthand → canonical source.
+const SOURCE_ALIASES = {
+  'coinbase/agentWallet': 'coinbase/agentic-wallet-skills'
+};
+
+function parseOwnerRepo(ownerRepo) {
+  const m = String(ownerRepo).match(/^([^/]+)\/([^/]+)$/);
+  return m ? { owner: m[1], repo: m[2] } : null;
+}
+
+// Reject any subpath with a ".." segment (path-traversal guard, parse-time).
+function sanitizeSubpath(subpath) {
+  const normalized = String(subpath).replace(/\\/g, '/');
+  for (const seg of normalized.split('/')) {
+    if (seg === '..') {
+      throw new Error('Unsafe subpath: "' + subpath + '" contains path-traversal ".." segments.');
+    }
+  }
+  return subpath;
+}
+
+function isLocalPath(input) {
+  return (
+    isAbsolute(input) ||
+    input.startsWith('./') ||
+    input.startsWith('../') ||
+    input === '.' ||
+    input === '..' ||
+    /^[a-zA-Z]:[/\\]/.test(input) // Windows C:\ , D:/ , …
+  );
+}
+
+// .tar.gz / .tgz / .zip → archive (tested on the path portion, ignoring #frag / ?query).
+function archiveFormat(spec) {
+  const p = String(spec).split('#')[0].split('?')[0];
+  if (/\.zip$/i.test(p)) return 'zip';
+  if (/\.(tar\.gz|tgz)$/i.test(p)) return 'tar.gz';
+  return null;
+}
+
+function decodeFragmentValue(value) {
+  try { return decodeURIComponent(value); }
+  catch (e) { return value; }
+}
+
+// Only treat a trailing #fragment as a git ref for git-shaped sources (so a
+// generic well-known URL keeps its fragment).
+function looksLikeGitSource(input) {
+  if (input.startsWith('github:') || input.startsWith('gitlab:') || input.startsWith('git@')) return true;
+  if (/^ssh:\/\/.+\.git(?:$|[/?])/i.test(input)) return true;
+  if (input.startsWith('http://') || input.startsWith('https://')) {
+    try {
+      const u = new URL(input);
+      const p = u.pathname;
+      if (u.hostname === 'github.com') return /^\/[^/]+\/[^/]+(?:\.git)?(?:\/tree\/[^/]+(?:\/.*)?)?\/?$/.test(p);
+      if (u.hostname === 'gitlab.com') return /^\/.+?\/[^/]+(?:\.git)?(?:\/-\/tree\/[^/]+(?:\/.*)?)?\/?$/.test(p);
+    } catch (e) { /* fall through */ }
+  }
+  if (/^https?:\/\/.+\.git(?:$|[/?])/i.test(input)) return true;
+  return (
+    !input.includes(':') &&
+    !input.startsWith('.') &&
+    !input.startsWith('/') &&
+    /^([^/]+)\/([^/]+)(?:\/(.+)|@(.+))?$/.test(input)
+  );
+}
+
+function parseFragmentRef(input) {
+  const hashIndex = input.indexOf('#');
+  if (hashIndex < 0) return { inputWithoutFragment: input };
+  const inputWithoutFragment = input.slice(0, hashIndex);
+  const fragment = input.slice(hashIndex + 1);
+  if (!fragment || !looksLikeGitSource(inputWithoutFragment)) return { inputWithoutFragment: input };
+  const atIndex = fragment.indexOf('@');
+  if (atIndex === -1) return { inputWithoutFragment: inputWithoutFragment, ref: decodeFragmentValue(fragment) };
+  const ref = fragment.slice(0, atIndex);
+  const skillFilter = fragment.slice(atIndex + 1);
+  return {
+    inputWithoutFragment: inputWithoutFragment,
+    ref: ref ? decodeFragmentValue(ref) : undefined,
+    skillFilter: skillFilter ? decodeFragmentValue(skillFilter) : undefined
+  };
+}
+
+function appendFragmentRef(input, ref, skillFilter) {
+  if (!ref) return input;
+  return input + '#' + ref + (skillFilter ? '@' + skillFilter : '');
+}
+
+// Any HTTP(S) URL that is not a known git host and not a .git repo → well-known discovery.
+function isWellKnownUrl(input) {
+  if (!input.startsWith('http://') && !input.startsWith('https://')) return false;
+  try {
+    const u = new URL(input);
+    const excluded = [
+      'github.com', 'gitlab.com',
+      'raw.githubusercontent.com', 'gist.github.com', 'gist.githubusercontent.com'
+    ];
+    if (excluded.indexOf(u.hostname.toLowerCase()) !== -1) return false;
+    if (input.endsWith('.git')) return false;
+    return true;
+  } catch (e) { return false; }
+}
+
+// shucky extension: classify direct-file and gist http(s) sources BEFORE the loose
+// github/gitlab regexes (which would otherwise mis-match e.g. gist.github.com).
+function classifyHttpUrl(input, fragmentRef) {
+  let u;
+  try { u = new URL(input); } catch (e) { return null; }
+  const host = u.hostname.toLowerCase();
+  const path = u.pathname;
+
+  if (host === 'gist.github.com') {
+    const parts = path.split('/').filter(Boolean);
+    const id = (parts.length >= 2 ? parts[1] : parts[0]) || '';
+    const cleanId = id.replace(/\.git$/, '');
+    if (cleanId) {
+      const out = { type: 'gist', url: 'https://gist.github.com/' + cleanId + '.git' };
+      if (fragmentRef) out.ref = fragmentRef;
+      return out;
+    }
+  }
+
+  if (host === 'raw.githubusercontent.com' || host === 'gist.githubusercontent.com') {
+    return { type: 'rawfile', url: input };
+  }
+
+  if (host === 'github.com') {
+    // /blob/<ref>/<path> or /raw/<ref>/<path> → fetch the raw file directly.
+    const m = path.match(/^\/([^/]+)\/([^/]+)\/(?:blob|raw)\/([^/]+)\/(.+)$/);
+    if (m) {
+      const owner = m[1], repo = m[2].replace(/\.git$/, ''), ref = m[3], p = m[4];
+      return { type: 'rawfile', url: 'https://raw.githubusercontent.com/' + owner + '/' + repo + '/' + ref + '/' + p };
+    }
+    return null; // repo / tree URLs handled by the git logic below
+  }
+
+  if (host === 'gitlab.com') {
+    if (path.indexOf('/-/raw/') !== -1) return { type: 'rawfile', url: input }; // gitlab raw is directly fetchable
+    return null;
+  }
+
+  // Any other host whose path points straight at a markdown / SKILL file → rawfile.
+  if (/\/SKILL\.md$/i.test(path) || /\.md$/i.test(path)) {
+    return { type: 'rawfile', url: input };
+  }
+  return null;
+}
+
+function parseSource(input) {
+  input = String(input == null ? '' : input).trim();
+  if (!input) throw new Error('empty source');
+
+  // Local path: absolute, relative, or current dir.
+  if (isLocalPath(input)) {
+    const resolved = resolve(input);
+    const lfmt = archiveFormat(input);
+    if (lfmt) return { type: 'archive', url: resolved, localPath: resolved, archiveFormat: lfmt };
+    return { type: 'local', url: resolved, localPath: resolved };
+  }
+
+  const fr = parseFragmentRef(input);
+  let body = fr.inputWithoutFragment;
+  const fragmentRef = fr.ref;
+  const fragmentSkillFilter = fr.skillFilter;
+
+  if (SOURCE_ALIASES[body]) body = SOURCE_ALIASES[body];
+
+  // Prefix shorthands.
+  const ghPrefix = body.match(/^github:(.+)$/);
+  if (ghPrefix) return parseSource(appendFragmentRef(ghPrefix[1], fragmentRef, fragmentSkillFilter));
+  const glPrefix = body.match(/^gitlab:(.+)$/);
+  if (glPrefix) return parseSource(appendFragmentRef('https://gitlab.com/' + glPrefix[1], fragmentRef, fragmentSkillFilter));
+  const gistPrefix = body.match(/^gist:(.+)$/);
+  if (gistPrefix) {
+    const out = { type: 'gist', url: 'https://gist.github.com/' + gistPrefix[1].replace(/\.git$/, '') + '.git' };
+    if (fragmentRef) out.ref = fragmentRef;
+    return out;
+  }
+
+  // shucky: archive + direct-file + gist classification before the loose git regexes.
+  if (body.startsWith('http://') || body.startsWith('https://')) {
+    const afmt = archiveFormat(body);
+    if (afmt) return { type: 'archive', url: body, archiveFormat: afmt };
+    const c = classifyHttpUrl(body, fragmentRef);
+    if (c) return c;
+  }
+
+  // GitHub URL with path: …/github.com/owner/repo/tree/<ref>/<subpath>
+  let m = body.match(/github\.com\/([^/]+)\/([^/]+)\/tree\/([^/]+)\/(.+)/);
+  if (m) {
+    return {
+      type: 'github',
+      url: 'https://github.com/' + m[1] + '/' + m[2] + '.git',
+      ref: m[3] || fragmentRef,
+      subpath: sanitizeSubpath(m[4])
+    };
+  }
+  // GitHub URL, branch only: …/github.com/owner/repo/tree/<ref>
+  m = body.match(/github\.com\/([^/]+)\/([^/]+)\/tree\/([^/]+)$/);
+  if (m) {
+    return { type: 'github', url: 'https://github.com/' + m[1] + '/' + m[2] + '.git', ref: m[3] || fragmentRef };
+  }
+  // GitHub URL: …/github.com/owner/repo
+  m = body.match(/github\.com\/([^/]+)\/([^/]+)/);
+  if (m) {
+    const out = { type: 'github', url: 'https://github.com/' + m[1] + '/' + m[2].replace(/\.git$/, '') + '.git' };
+    if (fragmentRef) out.ref = fragmentRef;
+    return out;
+  }
+
+  // GitLab URL with path (any instance): proto://host/<repoPath>/-/tree/<ref>/<subpath>
+  m = body.match(/^(https?):\/\/([^/]+)\/(.+?)\/-\/tree\/([^/]+)\/(.+)/);
+  if (m && m[2] !== 'github.com' && m[3]) {
+    return {
+      type: 'gitlab',
+      url: m[1] + '://' + m[2] + '/' + m[3].replace(/\.git$/, '') + '.git',
+      ref: m[4] || fragmentRef,
+      subpath: sanitizeSubpath(m[5])
+    };
+  }
+  // GitLab URL, branch only: proto://host/<repoPath>/-/tree/<ref>
+  m = body.match(/^(https?):\/\/([^/]+)\/(.+?)\/-\/tree\/([^/]+)$/);
+  if (m && m[2] !== 'github.com' && m[3]) {
+    return { type: 'gitlab', url: m[1] + '://' + m[2] + '/' + m[3].replace(/\.git$/, '') + '.git', ref: m[4] || fragmentRef };
+  }
+  // gitlab.com URL (official host only): gitlab.com/owner/repo or group/subgroup/repo
+  m = body.match(/gitlab\.com\/(.+?)(?:\.git)?\/?$/);
+  if (m && m[1].indexOf('/') !== -1) {
+    const out = { type: 'gitlab', url: 'https://gitlab.com/' + m[1] + '.git' };
+    if (fragmentRef) out.ref = fragmentRef;
+    return out;
+  }
+
+  // owner/repo@skill-name
+  m = body.match(/^([^/]+)\/([^/@]+)@(.+)$/);
+  if (m && body.indexOf(':') === -1 && !body.startsWith('.') && !body.startsWith('/')) {
+    const out = { type: 'github', url: 'https://github.com/' + m[1] + '/' + m[2] + '.git', skillFilter: fragmentSkillFilter || m[3] };
+    if (fragmentRef) out.ref = fragmentRef;
+    return out;
+  }
+  // owner/repo  or  owner/repo/sub/path
+  m = body.match(/^([^/]+)\/([^/]+)(?:\/(.+?))?\/?$/);
+  if (m && body.indexOf(':') === -1 && !body.startsWith('.') && !body.startsWith('/')) {
+    const out = { type: 'github', url: 'https://github.com/' + m[1] + '/' + m[2] + '.git' };
+    if (fragmentRef) out.ref = fragmentRef;
+    if (m[3]) out.subpath = sanitizeSubpath(m[3]);
+    if (fragmentSkillFilter) out.skillFilter = fragmentSkillFilter;
+    return out;
+  }
+
+  // Arbitrary HTTP(S) host (not git) → well-known discovery.
+  if (isWellKnownUrl(body)) {
+    return { type: 'well-known', url: body };
+  }
+
+  // Fallback: a direct git URL (git@…, ssh://…, https://….git).
+  const out = { type: 'git', url: body };
+  if (fragmentRef) out.ref = fragmentRef;
+  return out;
+}
+
+// Normalised owner/repo (lowercased input form) for trust-matching + lock provenance.
+// Returns null for local/rawfile/well-known (no owner/repo identity).
+function getOwnerRepo(parsed) {
+  if (!parsed || parsed.type === 'local') return null;
+  const url = parsed.url || '';
+
+  const ssh = url.match(/^git@[^:]+:(.+)$/);
+  if (ssh) {
+    const p = ssh[1].replace(/\.git$/, '');
+    return p.indexOf('/') !== -1 ? p : null;
+  }
+  if (url.startsWith('ssh://')) {
+    try {
+      const u = new URL(url);
+      const p = u.pathname.slice(1).replace(/\.git$/, '');
+      return p.indexOf('/') !== -1 ? p : null;
+    } catch (e) { return null; }
+  }
+  if (!url.startsWith('http://') && !url.startsWith('https://')) return null;
+  try {
+    const u = new URL(url);
+    // rawfile / well-known have no stable owner/repo identity for trust.
+    if (parsed.type === 'rawfile' || parsed.type === 'well-known' || parsed.type === 'archive') return null;
+    const p = u.pathname.slice(1).replace(/\.git$/, '');
+    return p.indexOf('/') !== -1 ? p : null;
+  } catch (e) { return null; }
+}
+
+module.exports = {
+  parseSource,
+  getOwnerRepo,
+  parseOwnerRepo,
+  sanitizeSubpath,
+  isLocalPath,
+  isWellKnownUrl
+};