@khanhcan148/mk 0.1.12 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhcan148/mk",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "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,7 +6,7 @@ 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';
@@ -67,6 +67,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 +120,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

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';
 

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,323 @@
-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
+
+/**
+ * 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)
+ * @param {string} url
+ * @throws {Error} if hostname is not a GitHub domain
+ */
+function assertGitHubHostname(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`SSRF guard: invalid URL "${url}"`);
+  }
+  const { hostname } = parsed;
+  const ALLOWED_HOSTS = new Set(['github.com', 'api.github.com', 'codeload.github.com']);
+  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'
+      },
+      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 });
+}