skillvault 0.11.2 → 0.12.0

package/dist/cli.js

@@ -21,10 +21,12 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync
 import { dirname, join, resolve as pathResolve } from 'node:path';
 import { createDecipheriv, createHmac, createPublicKey, diffieHellman, hkdfSync, generateKeyPairSync, } from 'node:crypto';
 import { resolveScope, resolveRoots, } from './scope.js';
+import { isValidSkillName, } from './skill-name.js';
+import { ensureSafeDir } from './safe-dir.js';
 import { loadCredentials, saveCredentials, loadProjectConfig, saveProjectConfig, } from './credentials.js';
 import { registerProject, unregisterProject, getCurrentProject, listProjects, } from './projects-registry.js';
 import { confirmInstall } from './prompts.js';
-const VERSION = '0.11.2';
+const VERSION = '0.12.0';
 const HOME = process.env.HOME || process.env.USERPROFILE || '~';
 const API_URL = process.env.SKILLVAULT_API_URL || 'https://api.getskillvault.com';
 const CONFIG_DIR = join(HOME, '.skillvault');
@@ -771,6 +773,14 @@ async function syncSkills(roots = getActiveRoots()) {
                 const localVaults = readdirSync(pubVaultDir).filter(f => f.endsWith('.vault'));
                 for (const vaultFile of localVaults) {
                     const localSkillName = vaultFile.replace(/\.vault$/, '');
+                    // Defense in depth: a poisoned local vault directory (from an
+                    // older buggy CLI version, or a hand-crafted file) might contain
+                    // a path-traversal name. Skip anything that doesn't pass the
+                    // current validator instead of feeding it into rmSync below.
+                    if (!isValidSkillName(localSkillName)) {
+                        console.error(`[sync] Skipping invalid local vault filename: ${JSON.stringify(vaultFile)}`);
+                        continue;
+                    }
                     if (!remoteSkillNames.has(localSkillName)) {
                         console.error(`[sync] Grant revoked: "${localSkillName}" from ${pub.name}`);
                         // Remove from this install's claude skill dir
@@ -807,6 +817,18 @@ async function syncSkills(roots = getActiveRoots()) {
         // Download missing or updated vaults
         let pubSynced = 0;
         for (const skill of skills) {
+            // Reject server-supplied skill names that would escape pubVaultDir
+            // or break the stub frontmatter. The server already validates at
+            // publish time (see packages/server/src/routes/skills.ts), but a
+            // compromised or downgraded server could still hand us a malicious
+            // name. Defense in depth — fail closed on the customer side.
+            // See packages/agent/src/skill-name.ts and
+            // docs/security-test-outstanding.md § 2.1.
+            if (!isValidSkillName(skill.skill_name)) {
+                errors.push(`${pub.name}: refusing skill with unsafe name ${JSON.stringify(skill.skill_name)}`);
+                console.error(`[sync] Refusing skill from ${pub.name} with unsafe name: ${JSON.stringify(skill.skill_name)}`);
+                continue;
+            }
             const vaultPath = join(pubVaultDir, `${skill.skill_name}.vault`);
             const vaultExists = existsSync(vaultPath);
             let needsDownload = !vaultExists;
@@ -901,6 +923,16 @@ async function installSkillStubs(roots = getActiveRoots()) {
         const vaultFiles = readdirSync(pubVaultDir).filter(f => f.endsWith('.vault'));
         for (const vaultFile of vaultFiles) {
             const skillName = vaultFile.replace(/\.vault$/, '');
+            // Defense in depth: validate before using as a path component or
+            // interpolating into stub frontmatter. Server already validates
+            // at publish, sync re-validates, but a buggy/older CLI may have
+            // left poisoned files in the vault directory. Skip them rather
+            // than letting them reach `join` and writeFileSync.
+            if (!isValidSkillName(skillName)) {
+                errors.push(`Skipping invalid local skill name: ${JSON.stringify(skillName)}`);
+                console.error(`[install] Skipping invalid local skill name: ${JSON.stringify(skillName)}`);
+                continue;
+            }
             const vaultPath = join(pubVaultDir, vaultFile);
             const installStubDir = join(installSkillsDir, skillName);
             const manifestPath = join(installStubDir, 'manifest.json');
@@ -1008,7 +1040,13 @@ ${multiFileSection}`;
                 encrypted: true,
             }, null, 2);
             // Write the stub into this install's claude skills directory.
-            mkdirSync(installStubDir, { recursive: true });
+            // ensureSafeDir refuses if the directory already exists as a
+            // symlink (defense against pre-created symlinks pointing at
+            // ~/.ssh, ~/.config, etc).
+            if (!ensureSafeDir(installStubDir)) {
+                errors.push(`Skipping ${skillName}: install dir is a symlink`);
+                continue;
+            }
             writeFileSync(join(installStubDir, 'SKILL.md'), stub, { mode: 0o600 });
             writeFileSync(join(installStubDir, 'manifest.json'), manifestData, { mode: 0o600 });
             if (vaultFileList.length > 0) {
@@ -1018,16 +1056,18 @@ ${multiFileSection}`;
             // and any other detected agent platforms (Cursor, Windsurf, Codex).
             if (isGlobal) {
                 const agentSkillDir = join(AGENTS_SKILLS_DIR, skillName);
-                mkdirSync(agentSkillDir, { recursive: true });
-                writeFileSync(join(agentSkillDir, 'SKILL.md'), stub, { mode: 0o600 });
-                writeFileSync(join(agentSkillDir, 'manifest.json'), manifestData, { mode: 0o600 });
-                if (vaultFileList.length > 0) {
-                    writeFileSync(join(agentSkillDir, 'files.json'), JSON.stringify(vaultFileList, null, 2), { mode: 0o600 });
+                if (ensureSafeDir(agentSkillDir)) {
+                    writeFileSync(join(agentSkillDir, 'SKILL.md'), stub, { mode: 0o600 });
+                    writeFileSync(join(agentSkillDir, 'manifest.json'), manifestData, { mode: 0o600 });
+                    if (vaultFileList.length > 0) {
+                        writeFileSync(join(agentSkillDir, 'files.json'), JSON.stringify(vaultFileList, null, 2), { mode: 0o600 });
+                    }
                 }
                 for (const platform of detectedPlatforms) {
                     const platformSkillDir = join(platform.dir, skillName);
+                    if (!ensureSafeDir(platformSkillDir))
+                        continue;
                     try {
-                        mkdirSync(platformSkillDir, { recursive: true });
                         writeFileSync(join(platformSkillDir, 'SKILL.md'), stub, { mode: 0o600 });
                         writeFileSync(join(platformSkillDir, 'manifest.json'), manifestData, { mode: 0o600 });
                         if (vaultFileList.length > 0) {
@@ -1991,14 +2031,18 @@ function watermark(content, id, email, publisherName, skillName) {
     const { content: withHeartbeats, heartbeatPair } = watermarkLayer5(result, id, skillName); // stealth heartbeats
     return { content: withHeartbeats, heartbeatPair };
 }
-function validateSkillName(name) {
-    return /^[a-zA-Z0-9_-]+$/.test(name) && name.length > 0 && name.length <= 128;
-}
+// validateSkillName / isValidSkillName are imported from ./skill-name.js
+// ensureSafeDir is imported from ./safe-dir.js
 /**
  * Quick sync for a single skill — checks for vault update before decrypting.
  * Returns true if the vault was updated. Status goes to stderr.
  */
 async function syncSingleSkill(skillName, pub, config, roots = getActiveRoots()) {
+    // Hard-fail this entry rather than letting an unsafe name reach the
+    // path joins below. Callers already validate at CLI parse time, but
+    // this is the second line of defense if any caller forgets.
+    if (!isValidSkillName(skillName))
+        return false;
     try {
         const capabilityName = `skill/${skillName.toLowerCase()}`;
         const res = await fetch(`${config.api_url}/skills/check-update?capability=${encodeURIComponent(capabilityName)}&current_version=0.0.0`, { signal: AbortSignal.timeout(5000) });
@@ -2054,7 +2098,7 @@ async function backgroundSyncAll(_config, roots = getActiveRoots()) {
  * List files in a skill vault without outputting content.
  */
 async function listSkillFiles(skillName) {
-    if (!validateSkillName(skillName)) {
+    if (!isValidSkillName(skillName)) {
         console.error('Error: Invalid skill name.');
         process.exit(1);
     }
@@ -2112,7 +2156,7 @@ async function listSkillFiles(skillName) {
  * Status messages go to stderr so they don't pollute the skill content.
  */
 async function loadSkill(skillName) {
-    if (!validateSkillName(skillName)) {
+    if (!isValidSkillName(skillName)) {
         console.error('Error: Invalid skill name. Skill names can only contain letters, numbers, hyphens, and underscores (max 128 chars).');
         console.error('Example: npx skillvault --load my-skill-name');
         process.exit(1);

package/dist/safe-dir.js

@@ -0,0 +1,46 @@
+/**
+ * Symlink-aware directory creation.
+ *
+ * The customer agent CLI writes skill stubs into well-known paths like
+ * `~/.claude/skills/<name>/` and `~/.agents/skills/<name>/`. A local
+ * attacker (or another process running as the customer) can pre-create
+ * one of those targets as a symbolic link pointing at a sensitive
+ * directory — `~/.ssh/`, `~/.config/`, the project root, etc. Without a
+ * check, `mkdirSync(target, { recursive: true })` is a no-op when the
+ * target already exists, and the subsequent `writeFileSync` follows the
+ * symlink and drops attacker-influenced content into the linked target.
+ *
+ * `ensureSafeDir` refuses that case explicitly:
+ *
+ *   - If the path exists AND is a symlink, return false and log a clear
+ *     diagnostic. The caller is expected to skip this skill rather than
+ *     fail the whole sync.
+ *   - If the path exists AND is a real directory, return true.
+ *   - If the path does not exist, create it (recursive) and return true.
+ *   - Any other failure (e.g. EACCES) returns false with a diagnostic.
+ *
+ * Regression coverage for docs/security-test-outstanding.md § 2.1.
+ */
+import { lstatSync, mkdirSync } from 'node:fs';
+const defaultLogger = { error: (m) => console.error(m) };
+export function ensureSafeDir(dirPath, logger = defaultLogger) {
+    try {
+        const stat = lstatSync(dirPath);
+        if (stat.isSymbolicLink()) {
+            logger.error(`[install] Refusing to write into symlinked directory: ${dirPath}`);
+            logger.error(`[install] If this is intentional, remove the symlink and re-run --sync.`);
+            return false;
+        }
+    }
+    catch {
+        // Doesn't exist — fall through and create it.
+    }
+    try {
+        mkdirSync(dirPath, { recursive: true });
+        return true;
+    }
+    catch (err) {
+        logger.error(`[install] Failed to create ${dirPath}: ${err instanceof Error ? err.message : 'unknown error'}`);
+        return false;
+    }
+}

package/dist/skill-name.js

@@ -0,0 +1,78 @@
+/**
+ * Customer-side skill-name validator (mirror of
+ * `packages/shared/src/skill-name.ts`).
+ *
+ * The agent CLI is published as a standalone npm package and does NOT
+ * import from `skillvault-shared`, so the validator is duplicated here.
+ * Both copies must agree — if you change one, change the other and rerun
+ * `packages/shared/test/skill-name.test.ts` plus the agent test below.
+ *
+ * Why duplicate at all? Defense in depth. The server already rejects
+ * malicious names at publish time (see `packages/server/src/routes/skills.ts`),
+ * but the customer agent must not assume the server is honest. A
+ * compromised server, a downgrade to an older server version, or a
+ * locally-poisoned vault directory could otherwise hand the agent a name
+ * that traverses out of the vault directory or breaks the stub
+ * frontmatter.
+ *
+ * Allowed: ASCII letters (any case), digits, dashes, underscores.
+ * 1–64 characters. Must start with a letter or digit.
+ * Rejects: path separators, parent traversal, null bytes, control chars,
+ * shell/YAML metacharacters, ANSI escape sequences, non-ASCII, oversized.
+ */
+export const MAX_SKILL_NAME_LENGTH = 64;
+const ALLOWED_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+export class InvalidSkillNameError extends Error {
+    reason;
+    skillName;
+    constructor(reason, skillName) {
+        super(`invalid skill name: ${reason}`);
+        this.reason = reason;
+        this.skillName = skillName;
+        this.name = 'InvalidSkillNameError';
+    }
+}
+/** Returns true when `name` is safe to use as a path component. */
+export function isValidSkillName(name) {
+    if (typeof name !== 'string')
+        return false;
+    if (name.length === 0 || name.length > MAX_SKILL_NAME_LENGTH)
+        return false;
+    for (let i = 0; i < name.length; i++) {
+        const code = name.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f)
+            return false;
+    }
+    if (name.includes('..'))
+        return false;
+    if (name.includes('/') || name.includes('\\'))
+        return false;
+    return ALLOWED_PATTERN.test(name);
+}
+/** Throws `InvalidSkillNameError` if `name` is unsafe. */
+export function validateSkillName(name) {
+    if (typeof name !== 'string') {
+        throw new InvalidSkillNameError('must be a string', String(name));
+    }
+    if (name.length === 0) {
+        throw new InvalidSkillNameError('must not be empty', name);
+    }
+    if (name.length > MAX_SKILL_NAME_LENGTH) {
+        throw new InvalidSkillNameError(`exceeds ${MAX_SKILL_NAME_LENGTH} characters`, name);
+    }
+    for (let i = 0; i < name.length; i++) {
+        const code = name.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f) {
+            throw new InvalidSkillNameError(`contains control character (0x${code.toString(16).padStart(2, '0')})`, name);
+        }
+    }
+    if (name.includes('..')) {
+        throw new InvalidSkillNameError('contains parent-directory segment ".."', name);
+    }
+    if (name.includes('/') || name.includes('\\')) {
+        throw new InvalidSkillNameError('contains a path separator', name);
+    }
+    if (!ALLOWED_PATTERN.test(name)) {
+        throw new InvalidSkillNameError(`must match ${ALLOWED_PATTERN.source}`, name);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillvault",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "SkillVault — secure skill distribution for Claude Code",
   "type": "module",
   "bin": {
@@ -13,6 +13,10 @@
   "files": [
     "dist/**/*.js"
   ],
+  "homepage": "https://getskillvault.com",
+  "bugs": {
+    "url": "https://getskillvault.com"
+  },
   "keywords": [
     "skillvault",
     "claude",