skillmds 1.0.18 → 1.0.19

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to `skillmds` are documented here. Versions follow [semver](https://semver.org).
 
+## 1.0.19
+
+- **Clear diagnostics when the registry is blocked.** In sandboxed or proxied environments that deny network egress to `api.skillmd.com`, `skillmd add owner/name` used to fall back to GitHub and surface a misleading "repo not found" error. The CLI now tells 404 ("not in the registry" — GitHub fallback proceeds as before) apart from unreachable (DNS failure, proxy 403, 5xx): if the GitHub fallback also fails, the error names the blocked registry and says what fixes it (allowlist `api.skillmd.com`, or install via the SkillMD MCP server); if the fallback succeeds, a warning notes the copy came from GitHub, not the registry.
+
 ## 1.0.18
 
 - **Cleaner tool output for agents.** `skillmd_search`, `skillmd_trending`, and `skillmd_recommend` no longer echo site-oriented fields (`avg_rating`, `rating_count`, `install_count`, `save_count`, `verified`, `type`, `owner_avatar`, `category_slug`, and the internal `confident` ranker flag). Results now carry just what an agent needs to pick a skill: slug, title, description, category, agents, repo stars, and the install snippet.

package/bin/skillmd-mcp.mjs

@@ -13,6 +13,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { mkdir, writeFile } from "node:fs/promises";
 import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { join, resolve, dirname, sep } from "node:path";
 import { stringify as stringifyYaml } from "yaml";
@@ -36,6 +37,19 @@ try {
 const API = process.env.SKILLMD_API || "https://api.skillmd.com";
 const TOKEN = process.env.SKILLMD_TOKEN || "";
 
+// Companion files not in R2 carry a registry-supplied source_url. Ingest only
+// pins these to GitHub raw hosts, so anything else is a hostile/compromised
+// registry response — refuse to fetch it (client-side SSRF guard).
+const ALLOWED_SOURCE_HOSTS = new Set(["raw.githubusercontent.com", "gist.githubusercontent.com"]);
+function isAllowedSourceUrl(u) {
+  try {
+    const parsed = new URL(u);
+    return parsed.protocol === "https:" && ALLOWED_SOURCE_HOSTS.has(parsed.hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
 async function api(path, init = {}) {
   const headers = { accept: "application/json", ...(init.headers || {}) };
   if (TOKEN) headers.authorization = `Bearer ${TOKEN}`;
@@ -241,20 +255,37 @@ async function handleCall(name, args) {
         // bundle avoids adding an unzip dependency to this standalone binary.
         try {
           const bundle = await api(`/api/skills/${owner}/${slugName}/bundle?format=json`);
+          // Resolve + integrity-check every file BEFORE writing any, so a
+          // tampered pack refuses cleanly instead of leaving a partial install.
+          const resolved = [];
           for (const f of bundle.files ?? []) {
             if (f.path.includes("..") || f.path.startsWith("/")) continue;
             let buf;
-            if (f.content_base64 != null) buf = Buffer.from(f.content_base64, "base64");
-            else if (f.source_url) {
+            if (f.content_base64 != null) {
+              buf = Buffer.from(f.content_base64, "base64");
+              // R2 files are content-addressed; verify the bytes match the
+              // registry's sha256. Files without one (the reconstructed inline
+              // SKILL.md) carry no hash and are skipped.
+              if (f.sha256) {
+                const got = createHash("sha256").update(buf).digest("hex");
+                if (got !== f.sha256) {
+                  const err = new Error(`integrity check failed for "${f.path}"`);
+                  err.integrity = true;
+                  throw err;
+                }
+              }
+            } else if (f.source_url && isAllowedSourceUrl(f.source_url)) {
               const r = await fetch(f.source_url).catch(() => null);
               if (!r || !r.ok) continue;
               buf = Buffer.from(await r.arrayBuffer());
             } else continue;
-            await writeSafe(f.path, f.path === "SKILL.md" ? raw : buf);
+            resolved.push({ path: f.path, contents: f.path === "SKILL.md" ? raw : buf });
           }
-          written = (bundle.files ?? []).length || 1;
-          if (!(bundle.files ?? []).some((f) => f.path === "SKILL.md")) await writeSafe("SKILL.md", raw);
-        } catch {
+          for (const f of resolved) await writeSafe(f.path, f.contents);
+          written = resolved.length || 1;
+          if (!resolved.some((f) => f.path === "SKILL.md")) await writeSafe("SKILL.md", raw);
+        } catch (e) {
+          if (e && e.integrity) return text(`Refused: ${args.slug} failed integrity verification — ${e.message}. Not installed.`);
           await writeSafe("SKILL.md", raw);
           note = ` NOTE: pack assets could not be fetched — only SKILL.md was written. For the full pack run: npx skillmds add ${args.slug}`;
         }

package/dist/cli.js

@@ -739,6 +739,7 @@ import { Command as Command5 } from "commander";
 import pc5 from "picocolors";
 
 // ../cli/src/api.ts
+import { createHash } from "crypto";
 import { stringify as stringifyYaml } from "yaml";
 
 // ../cli/src/config.ts
@@ -769,16 +770,46 @@ function resolveApi(flags = {}) {
 }
 
 // ../cli/src/api.ts
+var IntegrityError = class extends Error {
+  integrity = true;
+  constructor(message) {
+    super(message);
+    this.name = "IntegrityError";
+  }
+};
+var RegistryError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "RegistryError";
+  }
+  status;
+};
+var ALLOWED_SOURCE_HOSTS = /* @__PURE__ */ new Set(["raw.githubusercontent.com", "gist.githubusercontent.com"]);
+function isAllowedSourceUrl(u) {
+  try {
+    const parsed = new URL(u);
+    return parsed.protocol === "https:" && ALLOWED_SOURCE_HOSTS.has(parsed.hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
 function createClient(flags = {}) {
   const base = resolveApi(flags);
   const token = resolveToken(flags);
   async function api(path, init = {}) {
     const headers = { accept: "application/json", ...init.headers };
     if (token) headers.authorization = `Bearer ${token}`;
-    const res = await fetch(base + path, { ...init, headers });
+    let res;
+    try {
+      res = await fetch(base + path, { ...init, headers });
+    } catch (e) {
+      const cause = e instanceof Error ? e.cause?.message ?? e.message : String(e);
+      throw new RegistryError(`could not reach ${base}: ${cause}`);
+    }
     if (!res.ok) {
       const detail = await res.text().catch(() => "");
-      throw new Error(`SkillMD API ${res.status} on ${path}: ${detail}`);
+      throw new RegistryError(`SkillMD API ${res.status} on ${path}: ${detail}`, res.status);
     }
     return await res.json();
   }
@@ -794,8 +825,15 @@ async function fetchBundle(base, slug, token) {
   const out = [];
   for (const f of data.files) {
     if (f.content_base64 != null) {
-      out.push({ path: f.path, contents: Buffer.from(f.content_base64, "base64") });
-    } else if (f.source_url) {
+      const contents = Buffer.from(f.content_base64, "base64");
+      if (f.sha256) {
+        const got = createHash("sha256").update(contents).digest("hex");
+        if (got !== f.sha256) {
+          throw new IntegrityError(`integrity check failed for "${f.path}" (expected ${f.sha256.slice(0, 12)}\u2026, got ${got.slice(0, 12)}\u2026)`);
+        }
+      }
+      out.push({ path: f.path, contents });
+    } else if (f.source_url && isAllowedSourceUrl(f.source_url)) {
       const r = await fetch(f.source_url).catch(() => null);
       if (r && r.ok) out.push({ path: f.path, contents: Buffer.from(await r.arrayBuffer()) });
     }
@@ -995,12 +1033,31 @@ async function resolvePackFiles(skill, fetchTree = resolveTree) {
   }
   return null;
 }
+function registryFallbackNote(host) {
+  return `installed from GitHub because the SkillMD registry (${host}) was unreachable \u2014 this copy is not the registry-reviewed version`;
+}
+function registryUnreachableError(arg, host, e) {
+  const why = e.status ? `HTTP ${e.status}` : "network error";
+  return new Error(
+    `could not reach the SkillMD registry at ${host} (${why}), and "${arg}" was not found on GitHub either.
+If this environment restricts network access (sandbox, proxy, CI), ask an administrator to allow ${host} \u2014 or install through the SkillMD MCP server, which many sandboxed agents can already reach.
+Registry error: ${e.message}`
+  );
+}
 var defaultDeps = {
   async resolve(arg, flags) {
     if (isLocalish(arg)) {
-      const rs2 = await resolveSource(arg);
-      return rs2.map((r) => ({ name: r.slug, raw: r.raw, slug: r.slug }));
+      const rs = await resolveSource(arg);
+      return rs.map((r) => ({ name: r.slug, raw: r.raw, slug: r.slug }));
     }
+    let registryDown = null;
+    const registryHost = (() => {
+      try {
+        return new URL(createClient(flags).base).host;
+      } catch {
+        return "api.skillmd.com";
+      }
+    })();
     if (/^[^/\s:]+\/[^/\s:]+$/.test(arg)) {
       const { api, base: apiBase, token } = createClient(flags);
       const [owner, name] = arg.split("/");
@@ -1025,11 +1082,19 @@ var defaultDeps = {
           if (pack) return [{ ...meta, ...pack }];
         }
         return [{ ...meta, raw: skillMdFor(skill) }];
-      } catch {
+      } catch (e) {
+        if (e instanceof IntegrityError) throw e;
+        if (e instanceof RegistryError && e.status !== 404) registryDown = e;
       }
     }
-    const rs = await resolveSource(arg);
-    return rs.map((r) => ({ name: r.slug, raw: r.raw, slug: r.slug }));
+    try {
+      const rs = await resolveSource(arg);
+      const note2 = registryDown ? registryFallbackNote(registryHost) : void 0;
+      return rs.map((r) => ({ name: r.slug, raw: r.raw, slug: r.slug, note: note2 }));
+    } catch (e) {
+      if (registryDown) throw registryUnreachableError(arg, registryHost, registryDown);
+      throw e;
+    }
   },
   fireInstall(registrySlug, flags) {
     const { api } = createClient(flags);
@@ -1043,7 +1108,20 @@ var defaultDeps = {
   }
 };
 async function runAdd(arg, flags, deps = defaultDeps) {
-  let candidates = await deps.resolve(arg, flags);
+  let candidates;
+  try {
+    candidates = await deps.resolve(arg, flags);
+  } catch (e) {
+    if (e instanceof IntegrityError) {
+      return {
+        written: [],
+        blocked: [{ name: arg, reason: e.message }],
+        exitCode: 1,
+        output: pc7.red(`\u2717 ${arg} blocked \u2014 ${e.message}`)
+      };
+    }
+    throw e;
+  }
   if (flags.skill?.length) candidates = candidates.filter((c) => flags.skill.includes(c.name) || flags.skill.includes("*"));
   const deny = new Set(flags.deny ?? []);
   const written = [];
@@ -1075,6 +1153,9 @@ async function runAdd(arg, flags, deps = defaultDeps) {
     if (c.pinMiss) {
       lines.push(pc7.yellow(`\u26A0 ${c.name}: pinned commit unavailable upstream \u2014 fetched the source repo's default branch instead`));
     }
+    if (c.note) {
+      lines.push(pc7.yellow(`\u26A0 ${c.name}: ${c.note}`));
+    }
     if (c.type === "pack" && !c.files) {
       lines.push(pc7.yellow(`\u26A0 ${c.name} is a pack but its asset files could not be fetched \u2014 only SKILL.md was installed. It may reference missing files.`));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillmds",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "description": "SkillMD for agents: the `skillmds` MCP server + the `skillmd` CLI (lint, scan, search, install, publish Agent Skills) from skillmd.com.",
   "type": "module",
   "bin": {