skillvault 0.11.1 → 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.1';
+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/credentials.js

@@ -12,10 +12,63 @@
  *   <roots.configDir>/project.json (per install, project- or global-scoped)
  *     Active publishers in this specific install plus install metadata.
  */
-import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync, existsSync, openSync, closeSync, unlinkSync, } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { credentialsPath } from './scope.js';
+/**
+ * Run `fn` while holding an exclusive advisory lock on `<targetPath>.lock`.
+ * Same primitive as projects-registry.ts withFileLock — duplicated here so
+ * credentials.ts can be locked without crossing module boundaries. See that
+ * file for the design notes (POSIX O_EXCL semantics, busy-wait backoff,
+ * 1s stale-lock reclaim).
+ */
+function withFileLock(targetPath, fn) {
+    const lockPath = targetPath + '.lock';
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const start = Date.now();
+    const TIMEOUT_MS = 1000;
+    let fd = null;
+    while (fd === null) {
+        try {
+            fd = openSync(lockPath, 'wx', 0o600);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'EEXIST')
+                throw err;
+            if (Date.now() - start > TIMEOUT_MS) {
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch { }
+                try {
+                    fd = openSync(lockPath, 'wx', 0o600);
+                }
+                catch {
+                    throw new Error(`Could not acquire lock at ${lockPath} after ${TIMEOUT_MS}ms`);
+                }
+                break;
+            }
+            const buf = new SharedArrayBuffer(4);
+            const view = new Int32Array(buf);
+            Atomics.wait(view, 0, 0, 5 + Math.floor(Math.random() * 10));
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch { }
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { }
+    }
+}
 /**
  * Load customer credentials from ~/.skillvault/credentials.json.
  *
@@ -75,11 +128,20 @@ export function loadCredentials() {
 }
 /**
  * Persist customer credentials to ~/.skillvault/credentials.json with mode 0600.
+ *
+ * Wrapped in withFileLock so two concurrent invites with different invite
+ * codes can't race and silently drop one of each other's publishers from
+ * the publishers[] array. The caller is expected to read-modify-write the
+ * full credentials object themselves; this function only serializes the
+ * write step. For full read-modify-write atomicity, callers should hold
+ * the lock across both load + save (see redeemInvite() in cli.ts).
  */
 export function saveCredentials(creds) {
     const path = credentialsPath();
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(creds, null, 2), { mode: 0o600 });
+    withFileLock(path, () => {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(creds, null, 2), { mode: 0o600 });
+    });
 }
 function projectConfigPath(roots) {
     return join(roots.configDir, 'project.json');

package/dist/projects-registry.js

@@ -6,10 +6,80 @@
  * `getCurrentProject()` to figure out whether the current CWD already has a
  * registered SkillVault install.
  */
-import { mkdirSync, readFileSync, writeFileSync, existsSync, statSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync, existsSync, statSync, openSync, closeSync, unlinkSync, } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { projectsRegistryPath } from './scope.js';
 const REGISTRY_VERSION = 1;
+/**
+ * Run `fn` while holding an exclusive advisory lock on `<targetPath>.lock`.
+ *
+ * Uses `openSync(..., 'wx')` to atomically create the lockfile (POSIX
+ * O_EXCL semantics — exactly one process succeeds, the rest get EEXIST).
+ * On contention, busy-waits with a small backoff up to ~1s before giving
+ * up. The lockfile is unlinked on completion (success or thrown error)
+ * via try/finally so a crash mid-operation can't permanently wedge
+ * subsequent invocations — though if a process is SIGKILL'd between the
+ * openSync and the closeSync, the lockfile will linger and the next
+ * caller will time out and either inherit the stale lock (forced) or
+ * throw. For our use case (a single-user CLI doing read-modify-write on
+ * a small JSON file), 1s is plenty.
+ *
+ * Used by registerProject + unregisterProject to fix the lost-update race
+ * when two `--invite` commands run concurrently against the same
+ * ~/.skillvault/projects.json (audit scenario 12-concurrent-install).
+ */
+function withFileLock(targetPath, fn) {
+    const lockPath = targetPath + '.lock';
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const start = Date.now();
+    const TIMEOUT_MS = 1000;
+    let fd = null;
+    while (fd === null) {
+        try {
+            fd = openSync(lockPath, 'wx', 0o600);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'EEXIST')
+                throw err;
+            if (Date.now() - start > TIMEOUT_MS) {
+                // Stale lock — assume the previous holder crashed and reclaim it.
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch { }
+                // Loop one more time, but if it still fails, throw.
+                try {
+                    fd = openSync(lockPath, 'wx', 0o600);
+                }
+                catch {
+                    throw new Error(`Could not acquire lock at ${lockPath} after ${TIMEOUT_MS}ms`);
+                }
+                break;
+            }
+            // Busy-wait briefly. The Node.js event loop is single-threaded so
+            // we can't yield to a peer process via Promise without making the
+            // function async — and registerProject is sync. Atomics.wait on a
+            // SharedArrayBuffer is the cleanest sync sleep:
+            const buf = new SharedArrayBuffer(4);
+            const view = new Int32Array(buf);
+            Atomics.wait(view, 0, 0, 5 + Math.floor(Math.random() * 10));
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch { }
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { }
+    }
+}
 function readRegistry() {
     const path = projectsRegistryPath();
     if (!existsSync(path))
@@ -75,29 +145,39 @@ export function listProjects() {
 /**
  * Insert or update a project entry. Matching is by absolute path; if an entry
  * with the same path already exists, it is replaced.
+ *
+ * The read-modify-write is wrapped in withFileLock so two concurrent
+ * `--invite` calls can't race and lose one of each other's updates.
  */
 export function registerProject(entry) {
-    const reg = readRegistry();
-    const normalized = { ...entry, path: resolve(entry.path) };
-    const idx = reg.projects.findIndex((p) => resolve(p.path) === normalized.path);
-    if (idx >= 0) {
-        reg.projects[idx] = normalized;
-    }
-    else {
-        reg.projects.push(normalized);
-    }
-    writeRegistry(reg);
+    withFileLock(projectsRegistryPath(), () => {
+        const reg = readRegistry();
+        const normalized = { ...entry, path: resolve(entry.path) };
+        const idx = reg.projects.findIndex((p) => resolve(p.path) === normalized.path);
+        if (idx >= 0) {
+            reg.projects[idx] = normalized;
+        }
+        else {
+            reg.projects.push(normalized);
+        }
+        writeRegistry(reg);
+    });
 }
 /**
  * Remove the project entry whose path matches. No-op if not present.
+ *
+ * Wrapped in withFileLock for the same reason as registerProject — a
+ * concurrent uninstall + register would otherwise race.
  */
 export function unregisterProject(path) {
-    const reg = readRegistry();
-    const target = resolve(path);
-    const before = reg.projects.length;
-    reg.projects = reg.projects.filter((p) => resolve(p.path) !== target);
-    if (reg.projects.length !== before)
-        writeRegistry(reg);
+    withFileLock(projectsRegistryPath(), () => {
+        const reg = readRegistry();
+        const target = resolve(path);
+        const before = reg.projects.length;
+        reg.projects = reg.projects.filter((p) => resolve(p.path) !== target);
+        if (reg.projects.length !== before)
+            writeRegistry(reg);
+    });
 }
 /**
  * Look up the registry entry that matches the current working directory (or

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.1",
+  "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",