karma365-mcp 2.0.0 → 2.0.1

package/index.js

@@ -215,6 +215,74 @@ function resolveTodo(nameOrId) {
   return found
 }
 
+// ── Security & PIN System ─────────────────────────────────────────────────────
+
+function sha256(text) {
+  return crypto.createHash('sha256').update(String(text)).digest('hex')
+}
+
+function getSetting(key) {
+  try {
+    const row = db.prepare('SELECT value FROM settings WHERE key = ?').get(key)
+    return row ? row.value : null
+  } catch {
+    return null
+  }
+}
+
+function setSetting(key, value) {
+  db.prepare(`INSERT INTO settings (key, value) VALUES (?, ?)
+              ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(key, String(value))
+}
+
+function hasPin() {
+  const hash = getSetting('pin_hash')
+  const salt = getSetting('pin_salt')
+  return Boolean(hash && salt)
+}
+
+function setMasterPin(newPin) {
+  const trimmed = String(newPin ?? '').trim()
+  if (!trimmed) {
+    throw new Error('PIN cannot be empty. Please provide a numeric PIN (e.g. 111111).')
+  }
+  const salt = crypto.randomBytes(16).toString('hex')
+  const hash = sha256(salt + trimmed)
+  setSetting('pin_salt', salt)
+  setSetting('pin_hash', hash)
+  return true
+}
+
+function verifyPin(pin) {
+  const salt = getSetting('pin_salt')
+  const storedHash = getSetting('pin_hash')
+  if (!salt || !storedHash) return false
+  const trimmed = String(pin ?? '').trim()
+  if (!trimmed) return false
+  return sha256(salt + trimmed) === storedHash
+}
+
+/**
+ * Checks if a locked item requires PIN verification.
+ * Returns:
+ *   'ok'       -> Not locked OR valid PIN provided
+ *   'required' -> Item is locked and no PIN provided
+ *   'invalid'  -> Item is locked and wrong PIN provided
+ */
+function checkPinIfLocked(isPinned, pin) {
+  if (!isPinned || isPinned === 0) return 'ok'
+  if (!hasPin()) return 'required'
+  const trimmed = String(pin ?? '').trim()
+  if (!trimmed) return 'required'
+  return verifyPin(trimmed) ? 'ok' : 'invalid'
+}
+
+const PIN_REQ = (name, action = 'this action') =>
+  `PIN_REQUIRED: "${name}" is locked/PIN-protected 🔒. Prompt the user for their PIN to authorize ${action}, then retry with pin="<their_pin>".`
+
+const PIN_BAD = (name, action = 'performed') =>
+  `PIN_INVALID: Authentication failed — incorrect PIN entered ❌. "${name}" was NOT ${action}.`
+
 // ── Search helpers (DuckDuckGo / SearXNG / YouTube) ───────────────────────────
 
 const SEARCH_UA = 'Mozilla/5.0 (compatible; KarmaSearch/2.0)'
@@ -375,18 +443,19 @@ const TOOLS = [
   },
   {
     name: 'get_topic',
-    description: 'Get full details of a topic including all its resources',
+    description: 'Get full details of a topic including all its resources. PIN required if topic is locked.',
     inputSchema: {
       type: 'object',
       required: ['name'],
       properties: {
-        name: { type: 'string', description: 'Topic name or ID' }
+        name: { type: 'string', description: 'Topic name or ID' },
+        pin:  { type: 'string', description: 'Optional PIN required if the topic is locked' }
       }
     }
   },
   {
     name: 'create_topic',
-    description: 'Create a new topic in KARMA 365',
+    description: 'Create a new topic in KARMA 365. If parent major topic is locked, PIN is required.',
     inputSchema: {
       type: 'object',
       required: ['name'],
@@ -394,20 +463,24 @@ const TOOLS = [
         name:             { type: 'string', description: 'Topic name' },
         difficulty:       { type: 'string', enum: ['Easy', 'Medium', 'Hard'] },
         major_topic_name: { type: 'string', description: 'Assign to this major topic' },
-        color:            { type: 'string', description: 'Hex color code e.g. #FF5733' }
+        color:            { type: 'string', description: 'Hex color code e.g. #FF5733' },
+        is_pinned:        { type: 'boolean', description: 'Whether to lock/pin this topic' },
+        pin:              { type: 'string', description: 'Optional PIN if parent major topic is locked' }
       }
     }
   },
   {
     name: 'create_subtopic',
-    description: 'Create a subtopic under an existing topic',
+    description: 'Create a subtopic under an existing topic. If parent topic is locked, PIN is required.',
     inputSchema: {
       type: 'object',
       required: ['name', 'parent_topic_name'],
       properties: {
         name:              { type: 'string', description: 'Subtopic name' },
         parent_topic_name: { type: 'string', description: 'Parent topic name or ID' },
-        difficulty:        { type: 'string', enum: ['Easy', 'Medium', 'Hard'] }
+        difficulty:        { type: 'string', enum: ['Easy', 'Medium', 'Hard'] },
+        is_pinned:         { type: 'boolean', description: 'Whether to lock/pin this subtopic' },
+        pin:               { type: 'string', description: 'Optional PIN if parent topic is locked' }
       }
     }
   },
@@ -651,73 +724,102 @@ const TOOLS = [
   },
   {
     name: 'pin_major_topic',
-    description: 'Pin (lock) or unpin a major topic.',
+    description: 'Pin (lock) or unpin a major topic. Unpinning requires PIN if locked.',
     inputSchema: {
       type: 'object',
       required: ['name', 'pinned'],
       properties: {
         name:   { type: 'string', description: 'Major topic name or ID' },
-        pinned: { type: 'boolean', description: 'true = lock/pin, false = unlock/unpin' }
+        pinned: { type: 'boolean', description: 'true = lock/pin, false = unlock/unpin' },
+        pin:    { type: 'string', description: 'Optional PIN required if currently locked and unpinning' }
       }
     }
   },
   {
     name: 'pin_topic',
-    description: 'Pin (lock) or unpin a topic.',
+    description: 'Pin (lock) or unpin a topic. Unpinning requires PIN if locked.',
     inputSchema: {
       type: 'object',
       required: ['name', 'pinned'],
       properties: {
         name:   { type: 'string', description: 'Topic name or ID' },
-        pinned: { type: 'boolean', description: 'true = lock/pin, false = unlock/unpin' }
+        pinned: { type: 'boolean', description: 'true = lock/pin, false = unlock/unpin' },
+        pin:    { type: 'string', description: 'Optional PIN required if currently locked and unpinning' }
       }
     }
   },
   {
     name: 'set_major_topic_color',
-    description: 'Change the colour of a major topic.',
+    description: 'Change the colour of a major topic. PIN required if locked.',
     inputSchema: {
       type: 'object',
       required: ['name', 'color'],
       properties: {
         name:  { type: 'string', description: 'Major topic name or ID' },
-        color: { type: 'string', description: 'Hex colour or color name' }
+        color: { type: 'string', description: 'Hex colour or color name' },
+        pin:   { type: 'string', description: 'Optional PIN if locked' }
       }
     }
   },
   {
     name: 'set_topic_color',
-    description: 'Change the colour of a topic.',
+    description: 'Change the colour of a topic. PIN required if locked.',
     inputSchema: {
       type: 'object',
       required: ['name', 'color'],
       properties: {
         name:  { type: 'string', description: 'Topic name or ID' },
-        color: { type: 'string', description: 'Hex colour or color name' }
+        color: { type: 'string', description: 'Hex colour or color name' },
+        pin:   { type: 'string', description: 'Optional PIN if locked' }
       }
     }
   },
   {
     name: 'rename_major_topic',
-    description: 'Rename a major topic.',
+    description: 'Rename a major topic. PIN required if locked.',
     inputSchema: {
       type: 'object',
       required: ['name', 'new_name'],
       properties: {
         name:     { type: 'string', description: 'CURRENT major topic name or ID' },
-        new_name: { type: 'string', description: 'The NEW name' }
+        new_name: { type: 'string', description: 'The NEW name' },
+        pin:      { type: 'string', description: 'Optional PIN if locked' }
       }
     }
   },
   {
     name: 'rename_topic',
-    description: 'Rename a topic.',
+    description: 'Rename a topic. PIN required if locked.',
     inputSchema: {
       type: 'object',
       required: ['name', 'new_name'],
       properties: {
         name:     { type: 'string', description: 'CURRENT topic name or ID' },
-        new_name: { type: 'string', description: 'The NEW name' }
+        new_name: { type: 'string', description: 'The NEW name' },
+        pin:      { type: 'string', description: 'Optional PIN if locked' }
+      }
+    }
+  },
+  {
+    name: 'set_pin',
+    description: 'Set or update the security PIN for KARMA 365. Used to unlock, view, edit, or delete locked/PIN-protected topics and categories.',
+    inputSchema: {
+      type: 'object',
+      required: ['new_pin'],
+      properties: {
+        new_pin:     { type: 'string', description: 'New numeric PIN (e.g. 111111)' },
+        current_pin: { type: 'string', description: 'Current PIN (required if a PIN is already set)' }
+      }
+    }
+  },
+  {
+    name: 'verify_pin',
+    description: 'Verify if a PIN is correct against the KARMA 365 master PIN',
+    inputSchema: {
+      type: 'object',
+      required: ['pin'],
+      properties: {
+        pin: { type: 'string', description: 'PIN to test' }
       }
     }
   },
@@ -786,11 +888,12 @@ const TOOLS = [
 ]
 
 // ── Phone Live Bridge Setup & Auto-Discovery (Wi-Fi, Hotspot, USB) ─────────
-const EXPLICIT_PHONE_URL = process.env.KARMA365_PHONE_URL ? process.env.KARMA365_PHONE_URL.trim().replace(/\/+$/, '') : null
+const LOCAL_ONLY = process.env.KARMA365_LOCAL_ONLY === 'true' || process.env.KARMA365_PHONE_URL === 'none' || process.env.KARMA365_PHONE_URL === 'false'
+const EXPLICIT_PHONE_URL = (!LOCAL_ONLY && process.env.KARMA365_PHONE_URL) ? process.env.KARMA365_PHONE_URL.trim().replace(/\/+$/, '') : null
 const KARMA_TOKEN = process.env.KARMA365_TOKEN ? process.env.KARMA365_TOKEN.trim() : null
 const PHONE_CACHE_FILE = path.join(os.homedir(), '.karma365', 'last_phone_url.txt')
 
-let activePhoneUrl = EXPLICIT_PHONE_URL || readCachedPhoneUrl()
+let activePhoneUrl = LOCAL_ONLY ? null : (EXPLICIT_PHONE_URL || readCachedPhoneUrl())
 let isDiscoveryRunning = false
 let lastDiscoveryTime = 0
 
@@ -812,7 +915,7 @@ function writeCachedPhoneUrl(url) {
   } catch (_) {}
 }
 
-async function probePhoneHealth(baseUrl, timeoutMs = 600) {
+async function probePhoneHealth(baseUrl, timeoutMs = 1200) {
   try {
     const res = await fetch(`${baseUrl}/api/health`, { signal: AbortSignal.timeout(timeoutMs) })
     if (!res.ok) return false
@@ -824,6 +927,7 @@ async function probePhoneHealth(baseUrl, timeoutMs = 600) {
 }
 
 async function autoDiscoverPhone(force = false) {
+  if (LOCAL_ONLY) return null
   if (EXPLICIT_PHONE_URL) return EXPLICIT_PHONE_URL
   const now = Date.now()
   if (!force && activePhoneUrl && (now - lastDiscoveryTime < 15000)) {
@@ -842,7 +946,7 @@ async function autoDiscoverPhone(force = false) {
     ].filter(Boolean)
 
     for (const url of quickCandidates) {
-      if (await probePhoneHealth(url, 350)) {
+      if (await probePhoneHealth(url, 1500)) {
         activePhoneUrl = url
         writeCachedPhoneUrl(url)
         process.stderr.write(`[karma365-mcp] 📱 Connected to KARMA 365 Mobile App: ${url}\n`)
@@ -927,7 +1031,12 @@ async function callPhoneBridge(name, args) {
 
     if (res.status === 401) {
       const data = await res.json().catch(() => ({}))
-      throw new Error(`Phone Authentication Failed (401): ${data.error || 'Invalid or missing KARMA365_TOKEN'}. Check your pairing token in Karma 365 app settings.`)
+      if (EXPLICIT_PHONE_URL) {
+        throw new Error(`Phone Authentication Failed (401): ${data.error || 'Invalid or missing KARMA365_TOKEN'}. Check your pairing token in Karma 365 app settings.`)
+      }
+      process.stderr.write(`[karma365-mcp] Auto-discovered phone returned 401 (not paired). Falling back to local SQLite DB.\n`)
+      activePhoneUrl = null
+      return null
     }
 
     if (!res.ok) {
@@ -943,7 +1052,7 @@ async function callPhoneBridge(name, args) {
     return data.result
   } catch (err) {
     clearTimeout(timeoutId)
-    if (err.message && err.message.includes('401')) {
+    if (err.message && err.message.includes('401') && EXPLICIT_PHONE_URL) {
       throw err
     }
     process.stderr.write(`[karma365-mcp] Phone bridge unreachable at ${targetBase} (${err.message}). Checking auto-discovery or local SQLite...\n`)
@@ -1024,6 +1133,11 @@ async function handleTool(name, args) {
 
     case 'delete_major_topic': {
       const item = resolveMajorTopic(args.name)
+      if (item.is_pinned === 1) {
+        const guard = checkPinIfLocked(item.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(item.name, 'deletion')
+        if (guard === 'invalid')  return PIN_BAD(item.name, 'deleted')
+      }
       db.prepare('UPDATE topics SET major_topic_id = NULL WHERE major_topic_id = ?').run(item.id)
       db.prepare('DELETE FROM major_topics WHERE id = ?').run(item.id)
       return `✓ Deleted major topic "${item.name}". Subtopics under it have been kept.`
@@ -1031,6 +1145,11 @@ async function handleTool(name, args) {
 
     case 'rename_major_topic': {
       const item = resolveMajorTopic(args.name)
+      if (item.is_pinned === 1) {
+        const guard = checkPinIfLocked(item.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(item.name, 'renaming')
+        if (guard === 'invalid')  return PIN_BAD(item.name, 'renamed')
+      }
       const newName = args.new_name.trim()
       db.prepare('UPDATE major_topics SET name = ? WHERE id = ?').run(newName, item.id)
       return `✓ Renamed major topic from "${item.name}" to "${newName}"`
@@ -1038,6 +1157,11 @@ async function handleTool(name, args) {
 
     case 'set_major_topic_color': {
       const item = resolveMajorTopic(args.name)
+      if (item.is_pinned === 1) {
+        const guard = checkPinIfLocked(item.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(item.name, 'changing colour')
+        if (guard === 'invalid')  return PIN_BAD(item.name, 'color-changed')
+      }
       const color = resolveColor(args.color)
       db.prepare('UPDATE major_topics SET color = ? WHERE id = ?').run(color, item.id)
       return `✓ Changed colour of major topic "${item.name}" to ${color}`
@@ -1046,6 +1170,11 @@ async function handleTool(name, args) {
     case 'pin_major_topic': {
       const item = resolveMajorTopic(args.name)
       const pinned = args.pinned === true || String(args.pinned).toLowerCase() === 'true' ? 1 : 0
+      if (!pinned && item.is_pinned === 1) {
+        const guard = checkPinIfLocked(item.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(item.name, 'unlocking')
+        if (guard === 'invalid')  return PIN_BAD(item.name, 'unlocked')
+      }
       db.prepare('UPDATE major_topics SET is_pinned = ? WHERE id = ?').run(pinned, item.id)
       return pinned ? `✓ Locked/pinned major topic "${item.name}" 🔒` : `✓ Unlocked major topic "${item.name}"`
     }
@@ -1094,6 +1223,18 @@ async function handleTool(name, args) {
 
     case 'get_topic': {
       const topic = resolveTopic(args.name)
+      let majorIsPinned = 0
+      if (topic.major_topic_id) {
+        const m = db.prepare('SELECT is_pinned, name FROM major_topics WHERE id = ?').get(topic.major_topic_id)
+        if (m && m.is_pinned === 1) majorIsPinned = 1
+      }
+      const isLocked = topic.is_pinned === 1 || majorIsPinned === 1
+      if (isLocked) {
+        const guard = checkPinIfLocked(1, args.pin)
+        if (guard === 'required') return PIN_REQ(topic.name, 'opening / reading')
+        if (guard === 'invalid')  return PIN_BAD(topic.name, 'opened')
+      }
+
       const resources = db.prepare('SELECT * FROM resources WHERE topic_id = ? ORDER BY sort_order ASC, created_at DESC').all(topic.id)
       let majorName = null
       if (topic.major_topic_id) {
@@ -1124,25 +1265,48 @@ async function handleTool(name, args) {
       let majorId = null
       if (args.major_topic_name) {
         const m = resolveMajorTopic(args.major_topic_name)
+        if (m.is_pinned === 1) {
+          const guard = checkPinIfLocked(m.is_pinned, args.pin)
+          if (guard === 'required') return PIN_REQ(m.name, 'adding topic under it')
+          if (guard === 'invalid')  return PIN_BAD(m.name, 'modified')
+        }
         majorId = m.id
       }
       const id = newId()
       const color = resolveColor(args.color)
-      db.prepare(`INSERT INTO topics (id, name, difficulty, major_topic_id, color, created_at, synced)
-                  VALUES (?, ?, ?, ?, ?, ?, 1)`).run(id, args.name.trim(), args.difficulty || 'Medium', majorId, color, nowIso())
-      return `✓ Created topic "${args.name}" (ID: ${id})`
+      const isPinned = args.is_pinned === true || args.pinned === true || String(args.is_pinned).toLowerCase() === 'true' || String(args.pinned).toLowerCase() === 'true' ? 1 : 0
+      db.prepare(`INSERT INTO topics (id, name, difficulty, major_topic_id, color, is_pinned, created_at, synced)
+                  VALUES (?, ?, ?, ?, ?, ?, ?, 1)`).run(id, args.name.trim(), args.difficulty || 'Medium', majorId, color, isPinned, nowIso())
+      return `✓ Created topic "${args.name}" (ID: ${id})${isPinned ? ' 🔒' : ''}`
     }
 
     case 'create_subtopic': {
       const parent = resolveTopic(args.parent_topic_name)
+      if (parent.is_pinned === 1) {
+        const guard = checkPinIfLocked(parent.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(parent.name, 'adding subtopic under it')
+        if (guard === 'invalid')  return PIN_BAD(parent.name, 'modified')
+      }
       const id = newId()
-      db.prepare(`INSERT INTO topics (id, name, difficulty, parent_topic_id, major_topic_id, created_at, synced)
-                  VALUES (?, ?, ?, ?, ?, ?, 1)`).run(id, args.name.trim(), args.difficulty || 'Medium', parent.id, parent.major_topic_id, nowIso())
-      return `✓ Created subtopic "${args.name}" under parent "${parent.name}" (ID: ${id})`
+      const isPinned = args.is_pinned === true || args.pinned === true || String(args.is_pinned).toLowerCase() === 'true' || String(args.pinned).toLowerCase() === 'true' ? 1 : 0
+      db.prepare(`INSERT INTO topics (id, name, difficulty, parent_topic_id, major_topic_id, is_pinned, created_at, synced)
+                  VALUES (?, ?, ?, ?, ?, ?, ?, 1)`).run(id, args.name.trim(), args.difficulty || 'Medium', parent.id, parent.major_topic_id, isPinned, nowIso())
+      return `✓ Created subtopic "${args.name}" under parent "${parent.name}" (ID: ${id})${isPinned ? ' 🔒' : ''}`
     }
 
     case 'delete_topic': {
       const topic = resolveTopic(args.name)
+      let majorIsPinned = 0
+      if (topic.major_topic_id) {
+        const m = db.prepare('SELECT is_pinned FROM major_topics WHERE id = ?').get(topic.major_topic_id)
+        if (m && m.is_pinned === 1) majorIsPinned = 1
+      }
+      const isLocked = topic.is_pinned === 1 || majorIsPinned === 1
+      if (isLocked) {
+        const guard = checkPinIfLocked(1, args.pin)
+        if (guard === 'required') return PIN_REQ(topic.name, 'deletion')
+        if (guard === 'invalid')  return PIN_BAD(topic.name, 'deleted')
+      }
       db.prepare('DELETE FROM resources WHERE topic_id = ?').run(topic.id)
       db.prepare('DELETE FROM topics WHERE id = ?').run(topic.id)
       return `✓ Deleted topic "${topic.name}" and all its resources.`
@@ -1150,6 +1314,11 @@ async function handleTool(name, args) {
 
     case 'rename_topic': {
       const topic = resolveTopic(args.name)
+      if (topic.is_pinned === 1) {
+        const guard = checkPinIfLocked(topic.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(topic.name, 'renaming')
+        if (guard === 'invalid')  return PIN_BAD(topic.name, 'renamed')
+      }
       const newName = args.new_name.trim()
       db.prepare('UPDATE topics SET name = ?, updated_at = ? WHERE id = ?').run(newName, nowIso(), topic.id)
       return `✓ Renamed topic from "${topic.name}" to "${newName}"`
@@ -1157,6 +1326,11 @@ async function handleTool(name, args) {
 
     case 'set_topic_color': {
       const topic = resolveTopic(args.name)
+      if (topic.is_pinned === 1) {
+        const guard = checkPinIfLocked(topic.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(topic.name, 'changing colour')
+        if (guard === 'invalid')  return PIN_BAD(topic.name, 'color-changed')
+      }
       const color = resolveColor(args.color)
       db.prepare('UPDATE topics SET color = ?, updated_at = ? WHERE id = ?').run(color, nowIso(), topic.id)
       return `✓ Changed colour of topic "${topic.name}" to ${color}`
@@ -1165,6 +1339,11 @@ async function handleTool(name, args) {
     case 'pin_topic': {
       const topic = resolveTopic(args.name)
       const pinned = args.pinned === true || String(args.pinned).toLowerCase() === 'true' ? 1 : 0
+      if (!pinned && topic.is_pinned === 1) {
+        const guard = checkPinIfLocked(topic.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(topic.name, 'unlocking')
+        if (guard === 'invalid')  return PIN_BAD(topic.name, 'unlocked')
+      }
       db.prepare('UPDATE topics SET is_pinned = ?, updated_at = ? WHERE id = ?').run(pinned, nowIso(), topic.id)
       return pinned ? `✓ Locked/pinned topic "${topic.name}" 🔒` : `✓ Unlocked topic "${topic.name}"`
     }
@@ -1199,6 +1378,11 @@ async function handleTool(name, args) {
     case 'add_image':
     case 'add_code': {
       const topic = resolveTopic(args.topic_name)
+      if (topic.is_pinned === 1) {
+        const guard = checkPinIfLocked(topic.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(topic.name, 'adding resource to it')
+        if (guard === 'invalid')  return PIN_BAD(topic.name, 'modified')
+      }
       const type = RESOURCE_TYPE_MAP[name]
       const id = newId()
       let finalPathOrUrl = String(args.url || '').trim()
@@ -1218,10 +1402,54 @@ async function handleTool(name, args) {
     case 'delete_resource': {
       const row = db.prepare('SELECT * FROM resources WHERE id = ?').get(args.resource_id)
       if (!row) throw new Error(`Resource not found with ID: "${args.resource_id}"`)
+      let isLocked = row.is_pinned || 0
+      if (!isLocked && row.topic_id) {
+        const t = db.prepare('SELECT is_pinned, major_topic_id FROM topics WHERE id = ?').get(row.topic_id)
+        if (t && t.is_pinned === 1) isLocked = 1
+        else if (t && t.major_topic_id) {
+          const m = db.prepare('SELECT is_pinned FROM major_topics WHERE id = ?').get(t.major_topic_id)
+          if (m && m.is_pinned === 1) isLocked = 1
+        }
+      }
+      if (isLocked) {
+        const guard = checkPinIfLocked(1, args.pin)
+        if (guard === 'required') return PIN_REQ(row.description || 'Resource', 'deletion')
+        if (guard === 'invalid')  return PIN_BAD(row.description || 'Resource', 'deleted')
+      }
       db.prepare('DELETE FROM resources WHERE id = ?').run(row.id)
       return `✓ Deleted resource "${row.description || row.path_or_url}"`
     }
 
+    case 'set_pin':
+    case 'update_pin': {
+      const newPin = String(args.new_pin ?? args.pin ?? '').trim()
+      const currentPin = args.current_pin ? String(args.current_pin).trim() : undefined
+      if (!newPin) {
+        return '❌ PIN cannot be empty. Please provide a numeric PIN (e.g. 111111).'
+      }
+      if (hasPin()) {
+        if (!currentPin) {
+          return 'PIN_REQUIRED: A PIN is already set. Please provide current_pin to authorize updating to a new PIN.'
+        }
+        if (!verifyPin(currentPin)) {
+          return 'PIN_INVALID: Current PIN is incorrect. Master PIN was NOT updated.'
+        }
+      }
+      setMasterPin(newPin)
+      return `✓ Master PIN successfully updated to ${newPin.replace(/./g, '•')} 🔒`
+    }
+
+    case 'verify_pin': {
+      const pin = String(args.pin ?? '').trim()
+      if (!hasPin()) {
+        return 'ℹ️ No master PIN is set yet. Use set_pin to create one.'
+      }
+      if (verifyPin(pin)) {
+        return '✓ PIN verified successfully.'
+      }
+      return 'PIN_INVALID: Incorrect PIN.'
+    }
+
     case 'mark_resource_complete': {
       const isCompleted = args.is_completed === true || String(args.is_completed).toLowerCase() === 'true' ? 1 : 0
       const row = db.prepare('SELECT * FROM resources WHERE id = ?').get(args.resource_id)
@@ -1289,7 +1517,11 @@ async function handleTool(name, args) {
 
     case 'write_topic_note': {
       const topic = resolveTopic(args.topic_name)
-      checkPinIfLocked(topic.is_pinned, args.pin)
+      if (topic.is_pinned === 1) {
+        const guard = checkPinIfLocked(topic.is_pinned, args.pin)
+        if (guard === 'required') return PIN_REQ(topic.name, 'writing/updating note')
+        if (guard === 'invalid')  return PIN_BAD(topic.name, 'updated')
+      }
       const existing = (topic.note || '').trim()
       const newNote = existing ? `${existing}\n\n${args.note.trim()}` : args.note.trim()
       const title = args.title ? args.title.trim() : topic.note_title
@@ -1421,7 +1653,7 @@ async function handleTool(name, args) {
 // ── MCP Server Startup ────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: 'karma365-mcp', version: '2.0.0' },
+  { name: 'karma365-mcp', version: '2.0.1' },
   { capabilities: { tools: {} } }
 )
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karma365-mcp",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "KARMA 365 MCP server — connect Claude to your learning workspace",
   "main": "index.js",
   "bin": {