@khanhcan148/mk 0.1.13 → 0.1.15

package/README.md

@@ -134,7 +134,7 @@ User → /mk-* command (skill) → spawns utility agents → agents use knowledg
 | `/mk-docs` | Generate and update project documentation; maintains AGENTS.md; Impact Areas analysis produces human-readable "What changed / Who is affected / What could go wrong" narrative |
 | `/mk-git` | Git operations: branch, commit, push, PR, merge |
 | `/mk-research` | Deep multi-source research on technical topics |
-| `/mk-spike` | Investigate external service integrations: fetch API docs, evaluate options, produce spike.md with Go/No-Go |
+| `/mk-spike` | Investigate external service integrations: fetch API docs, evaluate options, produce <service-slug>-spike.md with Go/No-Go |
 | `/mk-overview` | Synthesize project artifacts into multi-tier stakeholder overview: Executive Brief, Product Report, Technical Report |
 | `/mk-workflow` | Trace REST endpoint call chains with upstream caller detection, variant branching, side effects/feature flags, Mermaid diagrams |
 | `/mk-log-analysis` | Analyze production logs from Datadog or Azure Application Insights via MCP; progressive severity triage, pattern detection, mandatory stack trace investigation, mk-debug integration |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhcan148/mk",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "CLI to install and manage MyClaudeKit (.claude/) in your projects",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "node --test test/lib/*.test.js test/commands/*.test.js test/integration/*.test.js test/characterization/*.characterization.test.js test/hooks/*.test.cjs",
+    "test": "node --test test/lib/*.test.js test/commands/*.test.js test/integration/*.test.js test/characterization/*.characterization.test.js .claude/hooks/tests/*.test.cjs",
     "lint": "node --check src/**/*.js bin/**/*.js 2>/dev/null",
     "selftest": "python3 .claude/skills/mk-selftest/scripts/validate_kit.py"
   },

package/src/commands/init.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { copyKitFiles, mergeSettingsJson } from '../lib/copy.js';
 import { writeManifest } from '../lib/manifest.js';
 import { computeChecksum } from '../lib/checksum.js';
-import { resolveTargetDir, resolveManifestPath } from '../lib/paths.js';
+import { resolveSourceDir, resolveTargetDir, resolveManifestPath } from '../lib/paths.js';
 import { MANIFEST_FILENAME } from '../lib/constants.js';
 import { resolveTokenOrLogin } from '../lib/auth.js';
 import { writeToken, readStoredToken } from '../lib/config.js';

package/src/commands/update.js

@@ -6,13 +6,39 @@ import { fileURLToPath } from 'node:url';
 import { readManifest, updateManifest, diffManifest } from '../lib/manifest.js';
 import { computeChecksum } from '../lib/checksum.js';
 import { copyKitFiles, collectDiskFiles, mergeSettingsJson } from '../lib/copy.js';
-import { resolveTargetDir, resolveManifestPath, deriveProjectRoot, assertSafePath } from '../lib/paths.js';
+import { resolveSourceDir, resolveTargetDir, resolveManifestPath, deriveProjectRoot, assertSafePath } from '../lib/paths.js';
 import { resolveTokenOrLogin } from '../lib/auth.js';
 import { writeToken, readStoredToken } from '../lib/config.js';
 import { downloadAndExtractKit, cleanupTempDir } from '../lib/download.js';
 import { fetchLatestRelease, compareVersions } from '../lib/releases.js';
 import { isEmptyDir } from '../lib/fs-utils.js';
 
+// ---------------------------------------------------------------------------
+// Security: strip terminal escape sequences from untrusted content
+// ---------------------------------------------------------------------------
+
+/**
+ * Strip terminal escape sequences from a string to prevent terminal injection
+ * when printing content sourced from the GitHub API (e.g. release notes).
+ *
+ * Removes:
+ *   - CSI sequences: ESC [ ... <letter>  (e.g. color codes, cursor movement, screen clear)
+ *   - OSC sequences: ESC ] ... BEL/ST    (e.g. window title manipulation)
+ *   - Fe two-character sequences: ESC <char> (e.g. ESC c = RIS terminal reset, ESC P = DCS)
+ *   - Raw C0 control characters (0x00-0x08, 0x0b, 0x0c, 0x0e-0x1f) excluding
+ *     printable whitespace (\t, \n, \r which are 0x09, 0x0a, 0x0d)
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+function stripTerminalEscapes(str) {
+  return str
+    .replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '')         // CSI sequences
+    .replace(/\x1b\].*?(\x07|\x1b\\)/gs, '')         // OSC sequences (dotAll for multiline)
+    .replace(/\x1b[^[\]]/g, '')                       // Fe two-char sequences (ESC c, ESC P, etc.)
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '');  // raw control chars (preserve \t \n \r)
+}
+
 // ---------------------------------------------------------------------------
 // Prompt helper
 // ---------------------------------------------------------------------------
@@ -67,6 +93,10 @@ export async function runUpdate(params = {}) {
   const projectRoot = deriveProjectRoot(manifest, manifestPath);
   const claudeRoot = resolve(join(projectRoot, '.claude'));
   const sourceFileList = copyKitFiles(sourceDir, targetDir, { dryRun: true });
+  // Fix 11-12 (performance): Build a Map for O(1) lookups in applyCopy.
+  // Previously sourceFileList.find() in applyCopy was O(n) per call, causing O(n²)
+  // behaviour when many files need updating. The Map is built once in O(n).
+  const sourceFileMap = new Map(sourceFileList.map(e => [e.relativePath, e]));
   const sourceFiles = {};
   for (const entry of sourceFileList) {
     const checksum = computeChecksum(entry.sourceAbsPath);
@@ -116,10 +146,11 @@ export async function runUpdate(params = {}) {
 
   /**
    * Copy a source file entry to its destination.
+   * Fix 11-12: Uses O(1) Map lookup instead of O(n) Array.find to eliminate O(n²) worst case.
    * @param {string} relPath
    */
   function applyCopy(relPath) {
-    const entry = sourceFileList.find(f => f.relativePath === relPath);
+    const entry = sourceFileMap.get(relPath);
     if (!entry) return;
     const destAbs = join(projectRoot, relPath);
     // Bounds check: destination must stay inside .claude/ subtree
@@ -322,10 +353,13 @@ export async function updateAction(options = {}, deps = {}) {
         chalk.cyan(`Update available: v${local} -> v${remote}\n`)
       );
 
-      // Show release notes (if any), truncated to 500 chars
+      // Show release notes (if any), truncated to 500 chars.
+      // S4: Strip terminal escape sequences before printing to prevent injection via
+      // crafted GitHub release bodies (CSI/OSC sequences can clear screen, set window titles, etc.).
       const body = release.body;
       if (body && body.trim().length > 0) {
-        const notes = body.length > 500 ? body.slice(0, 500) + '...' : body;
+        const rawNotes = body.length > 500 ? body.slice(0, 500) + '...' : body;
+        const notes = stripTerminalEscapes(rawNotes);
         process.stdout.write('\nRelease notes:\n');
         process.stdout.write(notes + '\n\n');
       }

package/src/lib/auth.js

@@ -5,7 +5,11 @@ import { GITHUB_API, KIT_REPO } from './constants.js';
 // Constants
 // ---------------------------------------------------------------------------
 
-export const GITHUB_CLIENT_ID = 'Ov23li35aA2A1xVa01B6';
+// Public OAuth App client ID (no secret) — override via env for rotation without a code release.
+// This is a public-flow client ID: GitHub Device Flow does not use a client secret,
+// so committing this value is safe. The env override allows operators to rotate the
+// OAuth app without publishing a new npm package.
+export const GITHUB_CLIENT_ID = process.env.GITHUB_CLIENT_ID || 'Ov23li35aA2A1xVa01B6';
 export const GITHUB_DEVICE_CODE_URL = 'https://github.com/login/device/code';
 export const GITHUB_TOKEN_URL = 'https://github.com/login/oauth/access_token';
 
@@ -123,7 +127,9 @@ export async function startDeviceFlow(opts = {}) {
       'Content-Type': 'application/x-www-form-urlencoded',
       Accept: 'application/json'
     },
-    body: `client_id=${GITHUB_CLIENT_ID}&scope=repo`
+    // Empty scope sufficient for public repos (5000 req/hr). Set MK_OAUTH_SCOPE=repo for private forks.
+    // Use URLSearchParams to prevent parameter injection via env var containing '&' chars.
+    body: new URLSearchParams({ client_id: GITHUB_CLIENT_ID, scope: process.env.MK_OAUTH_SCOPE || '' }).toString()
   });
 
   if (!codeRes.ok) {

package/src/lib/config.js

@@ -1,72 +1,90 @@
-import { join } from 'node:path';
-import { homedir } from 'node:os';
-import { mkdirSync, writeFileSync, readFileSync, unlinkSync, chmodSync, existsSync } from 'node:fs';
-
-/**
- * Returns the config directory for mk.
- * XDG-compliant: ~/.config/mk on Unix/macOS, %APPDATA%/mk on Windows.
- * @returns {string}
- */
-export function getConfigDir() {
-  const appData = process.env.APPDATA;
-  // Reject UNC paths (\\server\share) — these could redirect token storage to attacker-controlled
-  // network shares. Fall back to the XDG path if APPDATA looks suspicious.
-  if (appData && !appData.startsWith('\\\\')) {
-    return join(appData, 'mk');
-  }
-  return join(homedir(), '.config', 'mk');
-}
-
-/**
- * Returns the token file path.
- * @returns {string}
- */
-export function getTokenPath() {
-  return join(getConfigDir(), 'token');
-}
-
-/**
- * Read the stored token from disk.
- * @returns {string|null} Token string or null if not found.
- */
-export function readStoredToken() {
-  const tokenPath = getTokenPath();
-  if (!existsSync(tokenPath)) {
-    return null;
-  }
-  try {
-    return readFileSync(tokenPath, 'utf8').trim();
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Write the token to disk. Creates config dir if needed. Sets chmod 600 on Unix.
- * @param {string} token
- */
-export function writeToken(token) {
-  const configDir = getConfigDir();
-  const tokenPath = getTokenPath();
-  mkdirSync(configDir, { recursive: true });
-  // Write with mode 0o600 atomically — prevents TOCTOU window between write and chmod.
-  // On Windows the mode flag is ignored; home-dir ACLs provide equivalent protection.
-  writeFileSync(tokenPath, token, { encoding: 'utf8', mode: 0o600 });
-  if (process.platform !== 'win32') {
-    // Explicit chmod ensures mode is set even if umask overrides the O_CREAT mode.
-    chmodSync(tokenPath, 0o600);
-  }
-}
-
-/**
- * Delete the stored token file.
- * Does not throw if the file does not exist.
- */
-export function deleteToken() {
-  const tokenPath = getTokenPath();
-  try {
-    unlinkSync(tokenPath);
-  } catch {
-    // File doesn't exist — that's fine
-  }
-}
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { mkdirSync, writeFileSync, readFileSync, unlinkSync, chmodSync, existsSync } from 'node:fs';
+
+/**
+ * Returns the config directory for mk.
+ * XDG-compliant: ~/.config/mk on Unix/macOS, %APPDATA%/mk on Windows.
+ * @returns {string}
+ */
+export function getConfigDir() {
+  const appData = process.env.APPDATA;
+  // Reject UNC paths (\\server\share) — these could redirect token storage to attacker-controlled
+  // network shares. Fall back to the XDG path if APPDATA looks suspicious.
+  if (appData && !appData.startsWith('\\\\')) {
+    return join(appData, 'mk');
+  }
+  return join(homedir(), '.config', 'mk');
+}
+
+/**
+ * Returns the token file path.
+ * @returns {string}
+ */
+export function getTokenPath() {
+  return join(getConfigDir(), 'token');
+}
+
+/**
+ * Read the stored token from disk.
+ * @returns {string|null} Token string or null if not found.
+ */
+export function readStoredToken() {
+  const tokenPath = getTokenPath();
+  if (!existsSync(tokenPath)) {
+    return null;
+  }
+  try {
+    return readFileSync(tokenPath, 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate that a token string matches the expected GitHub token format.
+ * Accepted prefixes: ghp_ (personal access token), gho_ (OAuth token),
+ * github_pat_ (fine-grained PAT). Rejects garbage values from spoofed API responses.
+ * @param {string} token
+ * @throws {Error} if the token format is invalid
+ */
+function assertTokenFormat(token) {
+  if (typeof token !== 'string' || !/^(ghp_|gho_|github_pat_)[A-Za-z0-9_]+$/.test(token)) {
+    throw new Error(
+      `Invalid GitHub token format. Expected a token starting with ghp_, gho_, or github_pat_. ` +
+      `Got: "${typeof token === 'string' ? '<redacted>' : typeof token}"`
+    );
+  }
+}
+
+/**
+ * Write the token to disk. Creates config dir if needed. Sets chmod 600 on Unix.
+ * Validates token format before writing to reject spoofed or malformed values.
+ * @param {string} token
+ */
+export function writeToken(token) {
+  assertTokenFormat(token);
+  const configDir = getConfigDir();
+  const tokenPath = getTokenPath();
+  mkdirSync(configDir, { recursive: true });
+  // Write with mode 0o600 atomically — prevents TOCTOU window between write and chmod.
+  // On Windows the mode flag is ignored; home-dir ACLs provide equivalent protection.
+  writeFileSync(tokenPath, token, { encoding: 'utf8', mode: 0o600 });
+  if (process.platform !== 'win32') {
+    // Explicit chmod ensures mode is set even if umask overrides the O_CREAT mode.
+    chmodSync(tokenPath, 0o600);
+  }
+}
+
+/**
+ * Delete the stored token file.
+ * Does not throw if the file does not exist.
+ */
+export function deleteToken() {
+  const tokenPath = getTokenPath();
+  try {
+    unlinkSync(tokenPath);
+  } catch {
+    // File doesn't exist — that's fine
+  }
+}

package/src/lib/copy.js

@@ -1,5 +1,5 @@
 import { join, relative } from 'node:path';
-import { statSync, lstatSync, existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { statSync, lstatSync, existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
 import fsExtra from 'fs-extra';
 import { KIT_SUBDIRS, COPY_FILTER_PATTERNS, WINDOWS_PATH_WARN_LENGTH } from './constants.js';
 
@@ -154,16 +154,38 @@ export function copyKitFiles(sourceDir, targetDir, options = {}) {
   return fileList;
 }
 
+/**
+ * Create a timestamped backup of a file.
+ * @param {string} filePath - Absolute path to the file to back up
+ * @returns {string|null} Backup path, or null if source doesn't exist
+ */
+function backupFile(filePath) {
+  if (!existsSync(filePath)) return null;
+  const now = new Date();
+  const ts = [
+    now.getFullYear(), String(now.getMonth() + 1).padStart(2, '0'),
+    String(now.getDate()).padStart(2, '0'), '-',
+    String(now.getHours()).padStart(2, '0'), String(now.getMinutes()).padStart(2, '0')
+  ].join('');
+  const backupPath = `${filePath}.${ts}.bak`;
+  copyFileSync(filePath, backupPath);
+  return backupPath;
+}
+
 /**
  * Merge kit's settings.json into user's existing settings.json.
- * Strategy: deep-merge "hooks" key from kit source; preserve all other user keys.
- * If user has no settings.json, copy kit source as-is.
+ * Strategy: merge "hooks" key from kit source; preserve all other user keys.
+ * When a matcher already exists, the kit's hooks REPLACE the user's hooks for
+ * that matcher — this ensures updated hook commands propagate on update instead
+ * of accumulating stale duplicates.
+ * If user has no settings.json, create one with hooks only.
  * If kit source has no settings.json, do nothing.
+ * A timestamped backup is created before any write to an existing file.
  *
  * @param {string} sourceDir - Absolute path to source .claude/
  * @param {string} targetDir - Absolute path to target .claude/
  * @param {{ dryRun: boolean }} options
- * @returns {{ action: 'created'|'merged'|'skipped', merged?: string[] }}
+ * @returns {{ action: 'created'|'merged'|'skipped', merged?: string[], backup?: string }}
  */
 export function mergeSettingsJson(sourceDir, targetDir, options = {}) {
   const { dryRun = false } = options;
@@ -179,11 +201,14 @@ export function mergeSettingsJson(sourceDir, targetDir, options = {}) {
     return { action: 'skipped' };
   }
 
-  // No existing user settings — copy kit source as-is
+  // No existing user settings — create with hooks only (not permissions or other keys).
+  // Copying the full kit settings.json would duplicate permissions.deny entries when both
+  // global (~/.claude/settings.json) and project (.claude/settings.json) are initialised.
   if (!existsSync(destPath)) {
     if (!dryRun) {
+      const hooksOnly = kitSettings.hooks ? { hooks: kitSettings.hooks } : {};
       mkdirSync(targetDir, { recursive: true });
-      writeFileSync(destPath, JSON.stringify(kitSettings, null, 2) + '\n', 'utf-8');
+      writeFileSync(destPath, JSON.stringify(hooksOnly, null, 2) + '\n', 'utf-8');
     }
     return { action: 'created' };
   }
@@ -199,7 +224,9 @@ export function mergeSettingsJson(sourceDir, targetDir, options = {}) {
 
   const merged = [];
 
-  // Merge hooks: kit entries are added/updated, user entries not in kit are preserved
+  // Merge hooks: kit entries are added or replaced by matcher; user-only matchers preserved.
+  // Replace strategy: when the kit ships an updated hook command for an existing matcher,
+  // the old command is replaced instead of appended — preventing stale duplicates.
   if (kitSettings.hooks) {
     if (!userSettings.hooks) userSettings.hooks = {};
     for (const [event, kitEntries] of Object.entries(kitSettings.hooks)) {
@@ -207,31 +234,25 @@ export function mergeSettingsJson(sourceDir, targetDir, options = {}) {
         userSettings.hooks[event] = kitEntries;
         merged.push(event);
       } else {
-        // Merge by matcher: add kit entries whose matcher doesn't already exist
         for (const kitEntry of kitEntries) {
           const kitMatcher = kitEntry.matcher || '*';
-          const exists = userSettings.hooks[event].some(
+          const idx = userSettings.hooks[event].findIndex(
             e => (e.matcher || '*') === kitMatcher
           );
-          if (!exists) {
+          if (idx === -1) {
+            // New matcher — add it
             userSettings.hooks[event].push(kitEntry);
-            merged.push(`${event}[${kitMatcher}]`);
-          }
-          // If matcher exists, check if kit hooks are present
-          if (exists) {
-            const userEntry = userSettings.hooks[event].find(
-              e => (e.matcher || '*') === kitMatcher
-            );
-            if (userEntry && userEntry.hooks && kitEntry.hooks) {
-              for (const kh of kitEntry.hooks) {
-                const hookExists = userEntry.hooks.some(
-                  uh => uh.command === kh.command
-                );
-                if (!hookExists) {
-                  userEntry.hooks.push(kh);
-                  merged.push(`${event}[${kitMatcher}]:${kh.command}`);
-                }
-              }
+            merged.push(`${event}[${kitMatcher}]:added`);
+          } else {
+            // Existing matcher — replace with kit version if hooks differ
+            const userEntry = userSettings.hooks[event][idx];
+            const userCmds = (userEntry.hooks || []).map(h => h.command).sort();
+            const kitCmds = (kitEntry.hooks || []).map(h => h.command).sort();
+            const same = userCmds.length === kitCmds.length &&
+              userCmds.every((c, i) => c === kitCmds[i]);
+            if (!same) {
+              userSettings.hooks[event][idx] = kitEntry;
+              merged.push(`${event}[${kitMatcher}]:replaced`);
             }
           }
         }
@@ -242,7 +263,9 @@ export function mergeSettingsJson(sourceDir, targetDir, options = {}) {
   if (merged.length === 0) return { action: 'skipped' };
 
   if (!dryRun) {
+    const backup = backupFile(destPath);
     writeFileSync(destPath, JSON.stringify(userSettings, null, 2) + '\n', 'utf-8');
+    return { action: 'merged', merged, backup };
   }
   return { action: 'merged', merged };
 }

package/src/lib/download.js

@@ -1,276 +1,352 @@
-import { createGunzip } from 'node:zlib';
-import { mkdirSync, writeFileSync, rmSync, mkdtempSync } from 'node:fs';
-import { join, dirname, resolve, sep } from 'node:path';
-import { tmpdir } from 'node:os';
-import { Writable, Readable } from 'node:stream';
-import { pipeline } from 'node:stream/promises';
-import { GITHUB_API, KIT_REPO } from './constants.js';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const KIT_BRANCH = 'main';
-const TARBALL_URL = `${GITHUB_API}/repos/${KIT_REPO}/tarball/${KIT_BRANCH}`;
-
-// ---------------------------------------------------------------------------
-// Manual tar stream parser (zero-dependency, handles regular files + dirs)
-// ---------------------------------------------------------------------------
-
-/**
- * A Writable stream that parses tar format and writes matching entries to disk.
- * Only processes entries whose paths contain '.claude/' after stripping the root prefix.
- *
- * Tar format: 512-byte header blocks followed by data blocks (padded to 512 bytes).
- * Two consecutive 512-byte zero blocks mark end of archive.
- */
-class TarExtractor extends Writable {
-  /**
-   * @param {string} destDir - Destination directory (resolved to absolute path)
-   */
-  constructor(destDir) {
-    super();
-    this.destDir = resolve(destDir);
-    // Chunk list avoids O(n²) Buffer.concat on every write
-    this._chunks = [];
-    this._totalLen = 0;
-    this._state = 'header'; // 'header' | 'data' | 'skip'
-    this._remaining = 0;    // bytes left in current entry data
-    this._paddedSize = 0;   // padded size of current entry (multiple of 512)
-    this._currentPath = '';  // relative path being written ('' if not .claude/)
-    this._rootPrefix = null; // first root directory prefix to strip
-    this._zeroBlocks = 0;
-  }
-
-  _write(chunk, encoding, callback) {
-    this._chunks.push(chunk);
-    this._totalLen += chunk.length;
-    try {
-      this._process();
-      callback();
-    } catch (err) {
-      callback(err);
-    }
-  }
-
-  /** Consolidate pending chunks into one Buffer (lazy — only when access needed). */
-  _getBuffer() {
-    if (this._chunks.length !== 1) {
-      this._chunks = [Buffer.concat(this._chunks)];
-    }
-    return this._chunks[0];
-  }
-
-  /** Consume n bytes from the front of the chunk list. */
-  _consumeBuffer(n) {
-    const buf = this._getBuffer();
-    const remaining = buf.slice(n);
-    this._chunks = remaining.length > 0 ? [remaining] : [];
-    this._totalLen -= n;
-  }
-
-  _process() {
-    while (this._totalLen >= 512) {
-      if (this._state === 'header') {
-        this._parseHeader();
-      } else if (this._state === 'data') {
-        this._readData();
-      } else if (this._state === 'skip') {
-        this._skipData();
-      }
-
-      // Don't loop if we can't make progress (need paddedSize bytes to consume a data/skip entry)
-      if (this._state === 'data' && this._totalLen < this._paddedSize) break;
-      if (this._state === 'skip' && this._totalLen < this._paddedSize) break;
-    }
-  }
-
-  /**
-   * Assert that resolvedPath is safely contained within this.destDir.
-   * Throws if the path would escape the destination directory.
-   * @param {string} resolvedPath
-   */
-  _assertSafe(resolvedPath) {
-    if (resolvedPath !== this.destDir && !resolvedPath.startsWith(this.destDir + sep)) {
-      throw new Error(`Path traversal detected: "${resolvedPath}" escapes destination directory`);
-    }
-  }
-
-  _parseHeader() {
-    const block = this._getBuffer().slice(0, 512);
-
-    // Check for zero block (end of archive)
-    if (block[0] === 0 && block.every(b => b === 0)) {
-      this._zeroBlocks++;
-      this._consumeBuffer(512);
-      return;
-    }
-    this._zeroBlocks = 0;
-
-    // Parse header fields
-    const rawName = block.slice(0, 100).toString('utf8').replace(/\0+$/, '');
-    const prefix = block.slice(345, 500).toString('utf8').replace(/\0+$/, '');
-    const fullName = prefix ? `${prefix}/${rawName}` : rawName;
-
-    const sizeOctal = block.slice(124, 136).toString('utf8').replace(/\0/g, '').trim();
-    const size = sizeOctal ? parseInt(sizeOctal, 8) : 0;
-
-    const typeFlag = String.fromCharCode(block[156]) || '0';
-
-    // Skip PAX extended headers ('x') and PAX global headers ('g') without
-    // participating in root-prefix detection.  GitHub tarballs prepend a
-    // pax_global_header whose name has no slash; if we let it set rootPrefix
-    // to '' every subsequent entry fails the '.claude/' filter → 0 files.
-    if (typeFlag === 'g' || typeFlag === 'x') {
-      this._consumeBuffer(512);
-      if (size > 0) {
-        this._paddedSize = Math.ceil(size / 512) * 512;
-        this._state = 'skip';
-      }
-      return;
-    }
-
-    // Detect and strip root prefix (first directory component)
-    if (this._rootPrefix === null) {
-      const firstSlash = fullName.indexOf('/');
-      this._rootPrefix = firstSlash >= 0 ? fullName.slice(0, firstSlash + 1) : '';
-    }
-
-    const strippedName = fullName.startsWith(this._rootPrefix)
-      ? fullName.slice(this._rootPrefix.length)
-      : fullName;
-
-    this._consumeBuffer(512);
-
-    // Block symlinks and hard links entirely — prevents symlink-based escapes
-    if (typeFlag === '1' || typeFlag === '2') {
-      this._state = 'header';
-      return;
-    }
-
-    // Only process entries under .claude/
-    const isClaudePath = strippedName.startsWith('.claude/');
-
-    if (typeFlag === '5' || typeFlag === '\0' || typeFlag === '') {
-      // Directory entry
-      if (isClaudePath && strippedName) {
-        const dirPath = resolve(join(this.destDir, strippedName));
-        this._assertSafe(dirPath);
-        mkdirSync(dirPath, { recursive: true });
-      }
-      this._state = 'header';
-      return;
-    }
-
-    // Regular file entry (typeFlag '0' or empty/null)
-    if (size === 0) {
-      if (isClaudePath) {
-        const filePath = resolve(join(this.destDir, strippedName));
-        this._assertSafe(filePath);
-        mkdirSync(dirname(filePath), { recursive: true });
-        writeFileSync(filePath, Buffer.alloc(0));
-      }
-      this._state = 'header';
-      return;
-    }
-
-    this._remaining = size;
-    this._paddedSize = Math.ceil(size / 512) * 512;
-
-    if (isClaudePath) {
-      this._currentPath = strippedName;
-      this._state = 'data';
-    } else {
-      this._state = 'skip';
-    }
-  }
-
-  _readData() {
-    if (this._totalLen < this._paddedSize && this._totalLen < 512) {
-      return; // Wait for more data
-    }
-
-    if (this._totalLen >= this._paddedSize) {
-      // We have all the data for this entry
-      const buf = this._getBuffer();
-      const rawData = buf.slice(0, this._remaining);
-      this._consumeBuffer(this._paddedSize);
-
-      const filePath = resolve(join(this.destDir, this._currentPath));
-      this._assertSafe(filePath);
-      mkdirSync(dirname(filePath), { recursive: true });
-      writeFileSync(filePath, rawData);
-
-      this._currentPath = '';
-      this._state = 'header';
-    }
-    // else: not enough data yet — wait
-  }
-
-  _skipData() {
-    if (this._totalLen < this._paddedSize) {
-      return; // Wait for more data
-    }
-    this._consumeBuffer(this._paddedSize);
-    this._state = 'header';
-  }
-
-  _final(callback) {
-    callback();
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Download the kit repository as a tarball and extract .claude/ to targetDir.
- *
- * @param {string} token - GitHub Bearer token
- * @param {{ targetDir?: string, url?: string }} [opts]
- *   - url: override the download URL (e.g. a release tarball URL). Defaults to main-branch TARBALL_URL.
- * @returns {Promise<string>} The targetDir path
- */
-export async function downloadAndExtractKit(token, opts = {}) {
-  const { targetDir = mkdtempSync(join(tmpdir(), 'mk-kit-')), url = TARBALL_URL } = opts;
-
-  let res;
-  try {
-    res = await fetch(url, {
-      headers: {
-        Authorization: `Bearer ${token}`,
-        Accept: 'application/vnd.github.v3+json'
-      },
-      redirect: 'follow'
-    });
-  } catch (err) {
-    throw new Error(`Network connection failed: ${err.message}`);
-  }
-
-  if (!res.ok) {
-    throw new Error(`GitHub API error: ${res.status} ${res.statusText}`);
-  }
-
-  mkdirSync(targetDir, { recursive: true });
-
-  const gunzip = createGunzip();
-  const extractor = new TarExtractor(targetDir);
-
-  await pipeline(
-    Readable.fromWeb(res.body),
-    gunzip,
-    extractor
-  );
-
-  return targetDir;
-}
-
-/**
- * Remove a temp directory created by downloadAndExtractKit.
- *
- * @param {string} tempDir
- */
-export function cleanupTempDir(tempDir) {
-  rmSync(tempDir, { recursive: true, force: true });
-}
+import { createGunzip } from 'node:zlib';
+import { mkdirSync, writeFileSync, rmSync, mkdtempSync } from 'node:fs';
+import { join, dirname, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+import { Writable, Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { GITHUB_API, KIT_REPO } from './constants.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const KIT_BRANCH = 'main';
+const TARBALL_URL = `${GITHUB_API}/repos/${KIT_REPO}/tarball/${KIT_BRANCH}`;
+
+/** Maximum size (bytes) allowed for a single tar entry. Prevents memory-exhaustion
+ *  from crafted tarballs with large size fields. 50 MB is well above any kit file. */
+const MAX_ENTRY_SIZE = 50 * 1024 * 1024; // 52428800 bytes
+
+/** Hostnames allowed for kit downloads. Hoisted to module scope to avoid rebuilding on each call. */
+const ALLOWED_HOSTS = new Set(['github.com', 'api.github.com', 'codeload.github.com']);
+
+/** HTTP status codes that indicate a redirect. Hoisted to module scope alongside ALLOWED_HOSTS. */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+/**
+ * Validate that the download URL's hostname is a GitHub domain.
+ * Prevents SSRF: caller-supplied URLs (e.g. tarballUrl from GitHub API JSON) could be
+ * redirected to an attacker-controlled host, exfiltrating the Bearer token.
+ * Allowed: api.github.com, *.github.com (e.g. codeload.github.com)
+ * Exported so that releases.js can validate tarball_url at the source.
+ * @param {string} url
+ * @throws {Error} if hostname is not a GitHub domain
+ */
+export function assertGitHubHostname(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`SSRF guard: invalid URL "${url}"`);
+  }
+  const { hostname } = parsed;
+  if (!ALLOWED_HOSTS.has(hostname)) {
+    throw new Error(
+      `SSRF guard: URL hostname "${hostname}" is not allowed. ` +
+      `Only github.com domains are permitted for kit downloads.`
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Manual tar stream parser (zero-dependency, handles regular files + dirs)
+// ---------------------------------------------------------------------------
+
+/**
+ * A Writable stream that parses tar format and writes matching entries to disk.
+ * Only processes entries whose paths contain '.claude/' after stripping the root prefix.
+ *
+ * Tar format: 512-byte header blocks followed by data blocks (padded to 512 bytes).
+ * Two consecutive 512-byte zero blocks mark end of archive.
+ */
+class TarExtractor extends Writable {
+  /**
+   * @param {string} destDir - Destination directory (resolved to absolute path)
+   */
+  constructor(destDir) {
+    super();
+    this.destDir = resolve(destDir);
+    // Chunk list avoids O(n²) Buffer.concat on every write
+    this._chunks = [];
+    this._totalLen = 0;
+    this._state = 'header'; // 'header' | 'data' | 'skip'
+    this._remaining = 0;    // bytes left in current entry data
+    this._paddedSize = 0;   // padded size of current entry (multiple of 512)
+    this._currentPath = '';  // relative path being written ('' if not .claude/)
+    this._rootPrefix = null; // first root directory prefix to strip
+    this._zeroBlocks = 0;
+  }
+
+  _write(chunk, encoding, callback) {
+    this._chunks.push(chunk);
+    this._totalLen += chunk.length;
+    try {
+      this._process();
+      callback();
+    } catch (err) {
+      callback(err);
+    }
+  }
+
+  /** Consolidate pending chunks into one Buffer (lazy — only when access needed). */
+  _getBuffer() {
+    if (this._chunks.length !== 1) {
+      this._chunks = [Buffer.concat(this._chunks)];
+    }
+    return this._chunks[0];
+  }
+
+  /** Consume n bytes from the front of the chunk list. */
+  _consumeBuffer(n) {
+    const buf = this._getBuffer();
+    const remaining = buf.slice(n);
+    this._chunks = remaining.length > 0 ? [remaining] : [];
+    this._totalLen -= n;
+  }
+
+  _process() {
+    while (this._totalLen >= 512) {
+      if (this._state === 'header') {
+        this._parseHeader();
+      } else if (this._state === 'data') {
+        this._readData();
+      } else if (this._state === 'skip') {
+        this._skipData();
+      }
+
+      // Don't loop if we can't make progress (need paddedSize bytes to consume a data/skip entry)
+      if (this._state === 'data' && this._totalLen < this._paddedSize) break;
+      if (this._state === 'skip' && this._totalLen < this._paddedSize) break;
+    }
+  }
+
+  /**
+   * Assert that resolvedPath is safely contained within this.destDir.
+   * Throws if the path would escape the destination directory.
+   * Fix 7: On case-insensitive filesystems (win32, darwin) compare lowercased paths
+   * to prevent mixed-case bypass (e.g. /tmp/Mk-Kit-abc matching /tmp/mk-kit-abc).
+   * @param {string} resolvedPath
+   */
+  _assertSafe(resolvedPath) {
+    const isCaseInsensitive = process.platform === 'win32' || process.platform === 'darwin';
+    const a = isCaseInsensitive ? resolvedPath.toLowerCase() : resolvedPath;
+    const b = isCaseInsensitive ? this.destDir.toLowerCase() : this.destDir;
+    if (a !== b && !a.startsWith(b + sep)) {
+      throw new Error(`Path traversal detected: "${resolvedPath}" escapes destination directory`);
+    }
+  }
+
+  _parseHeader() {
+    const block = this._getBuffer().slice(0, 512);
+
+    // Check for zero block (end of archive)
+    if (block[0] === 0 && block.every(b => b === 0)) {
+      this._zeroBlocks++;
+      this._consumeBuffer(512);
+      return;
+    }
+    this._zeroBlocks = 0;
+
+    // Parse header fields
+    const rawName = block.slice(0, 100).toString('utf8').replace(/\0+$/, '');
+    const prefix = block.slice(345, 500).toString('utf8').replace(/\0+$/, '');
+    const fullName = prefix ? `${prefix}/${rawName}` : rawName;
+
+    const sizeOctal = block.slice(124, 136).toString('utf8').replace(/\0/g, '').trim();
+    const size = sizeOctal ? parseInt(sizeOctal, 8) : 0;
+
+    // Fix 6: Per-entry size cap — reject crafted tarballs with enormous size fields
+    // that would cause _readData to buffer the whole entry in memory (DoS vector).
+    if (size > MAX_ENTRY_SIZE) {
+      throw new Error(
+        `Tar entry size ${size} bytes exceeds maximum allowed ${MAX_ENTRY_SIZE} bytes (50 MB): ` +
+        `entry "${fullName}"`
+      );
+    }
+
+    const typeFlag = String.fromCharCode(block[156]) || '0';
+
+    // Skip PAX extended headers ('x') and PAX global headers ('g') without
+    // participating in root-prefix detection.  GitHub tarballs prepend a
+    // pax_global_header whose name has no slash; if we let it set rootPrefix
+    // to '' every subsequent entry fails the '.claude/' filter → 0 files.
+    if (typeFlag === 'g' || typeFlag === 'x') {
+      this._consumeBuffer(512);
+      if (size > 0) {
+        this._paddedSize = Math.ceil(size / 512) * 512;
+        this._state = 'skip';
+      }
+      return;
+    }
+
+    // Detect and strip root prefix (first directory component)
+    if (this._rootPrefix === null) {
+      const firstSlash = fullName.indexOf('/');
+      this._rootPrefix = firstSlash >= 0 ? fullName.slice(0, firstSlash + 1) : '';
+    }
+
+    const strippedName = fullName.startsWith(this._rootPrefix)
+      ? fullName.slice(this._rootPrefix.length)
+      : fullName;
+
+    this._consumeBuffer(512);
+
+    // Block symlinks and hard links entirely — prevents symlink-based escapes
+    if (typeFlag === '1' || typeFlag === '2') {
+      this._state = 'header';
+      return;
+    }
+
+    // Only process entries under .claude/
+    const isClaudePath = strippedName.startsWith('.claude/');
+
+    if (typeFlag === '5' || typeFlag === '\0' || typeFlag === '') {
+      // Directory entry
+      if (isClaudePath && strippedName) {
+        const dirPath = resolve(join(this.destDir, strippedName));
+        this._assertSafe(dirPath);
+        mkdirSync(dirPath, { recursive: true });
+      }
+      this._state = 'header';
+      return;
+    }
+
+    // Regular file entry (typeFlag '0' or empty/null)
+    if (size === 0) {
+      if (isClaudePath) {
+        const filePath = resolve(join(this.destDir, strippedName));
+        this._assertSafe(filePath);
+        mkdirSync(dirname(filePath), { recursive: true });
+        writeFileSync(filePath, Buffer.alloc(0));
+      }
+      this._state = 'header';
+      return;
+    }
+
+    this._remaining = size;
+    this._paddedSize = Math.ceil(size / 512) * 512;
+
+    if (isClaudePath) {
+      this._currentPath = strippedName;
+      this._state = 'data';
+    } else {
+      this._state = 'skip';
+    }
+  }
+
+  _readData() {
+    if (this._totalLen < this._paddedSize && this._totalLen < 512) {
+      return; // Wait for more data
+    }
+
+    if (this._totalLen >= this._paddedSize) {
+      // We have all the data for this entry
+      const buf = this._getBuffer();
+      const rawData = buf.slice(0, this._remaining);
+      this._consumeBuffer(this._paddedSize);
+
+      const filePath = resolve(join(this.destDir, this._currentPath));
+      this._assertSafe(filePath);
+      mkdirSync(dirname(filePath), { recursive: true });
+      writeFileSync(filePath, rawData);
+
+      this._currentPath = '';
+      this._state = 'header';
+    }
+    // else: not enough data yet — wait
+  }
+
+  _skipData() {
+    if (this._totalLen < this._paddedSize) {
+      return; // Wait for more data
+    }
+    this._consumeBuffer(this._paddedSize);
+    this._state = 'header';
+  }
+
+  _final(callback) {
+    callback();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Download the kit repository as a tarball and extract .claude/ to targetDir.
+ *
+ * @param {string} token - GitHub Bearer token
+ * @param {{ targetDir?: string, url?: string }} [opts]
+ *   - url: override the download URL (e.g. a release tarball URL). Defaults to main-branch TARBALL_URL.
+ * @returns {Promise<string>} The targetDir path
+ */
+export async function downloadAndExtractKit(token, opts = {}) {
+  const { targetDir = mkdtempSync(join(tmpdir(), 'mk-kit-')), url = TARBALL_URL } = opts;
+
+  // Fix 4: SSRF guard — assert hostname is a GitHub domain before forwarding Bearer token.
+  // A compromised or MITM'd GitHub API response could supply an attacker-controlled URL.
+  assertGitHubHostname(url);
+
+  let res;
+  try {
+    res = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github.v3+json'
+      },
+      // S1: Use redirect: 'manual' to prevent the Authorization header from being forwarded
+      // to the redirect target (e.g. codeload.github.com). We handle the redirect manually:
+      // validate the Location hostname, then re-fetch without the auth header.
+      redirect: 'manual'
+    });
+  } catch (err) {
+    throw new Error(`Network connection failed: ${err.message}`);
+  }
+
+  // Handle 3xx redirects: validate Location hostname, then re-fetch without auth header.
+  // This prevents the Bearer token from leaking to third-party servers via a compromised redirect.
+  if (REDIRECT_STATUSES.has(res.status)) {
+    const location = res.headers.get('location');
+    if (!location) {
+      throw new Error(`GitHub API redirect (${res.status}) had no Location header`);
+    }
+    // Validate the redirect target is a GitHub hostname before following
+    assertGitHubHostname(location);
+    try {
+      res = await fetch(location, {
+        // No Authorization header on the redirect target — the token is only for api.github.com
+        headers: { Accept: 'application/vnd.github.v3+json' },
+        redirect: 'follow'
+      });
+    } catch (err) {
+      throw new Error(`Network connection failed on redirect: ${err.message}`);
+    }
+  }
+
+  if (!res.ok) {
+    throw new Error(`GitHub API error: ${res.status} ${res.statusText}`);
+  }
+
+  mkdirSync(targetDir, { recursive: true });
+
+  const gunzip = createGunzip();
+  const extractor = new TarExtractor(targetDir);
+
+  await pipeline(
+    Readable.fromWeb(res.body),
+    gunzip,
+    extractor
+  );
+
+  return targetDir;
+}
+
+/**
+ * Remove a temp directory created by downloadAndExtractKit.
+ *
+ * @param {string} tempDir
+ */
+export function cleanupTempDir(tempDir) {
+  rmSync(tempDir, { recursive: true, force: true });
+}

package/src/lib/releases.js

@@ -1,5 +1,6 @@
 import semver from 'semver';
 import { GITHUB_API, KIT_REPO } from './constants.js';
+import { assertGitHubHostname } from './download.js';
 
 // ---------------------------------------------------------------------------
 // GitHub Releases API helpers
@@ -53,6 +54,14 @@ export async function fetchLatestRelease(token) {
 
   const { tag_name: tag, body = null, tarball_url: tarballUrl } = data;
 
+  // S3: Validate tarball_url hostname before returning it to callers.
+  // A compromised GitHub API response could supply an attacker-controlled URL for SSRF.
+  try {
+    assertGitHubHostname(tarballUrl);
+  } catch {
+    return { available: false, reason: 'Tarball URL failed hostname validation' };
+  }
+
   // Parse version: try clean() first (handles v-prefix), then coerce() as fallback.
   // coerce('release-0.2.0') => '0.2.0', coerce('totally-not-semver') => null
   const version = semver.clean(tag) ?? (semver.coerce(tag) ? semver.coerce(tag).version : null);