obsidian-mcp-brain 0.2.0

package/lib/access.mjs

@@ -0,0 +1,108 @@
+// Pure path-normalisation and access-control functions.
+// denyPaths is passed explicitly so these functions are side-effect-free and testable.
+
+export function normPath(...parts) {
+  const joined = parts.filter(Boolean).join('/').replace(/\/+/g, '/').replace(/^\/+|\/+$/g, '');
+  const segments = [];
+  for (const seg of joined.split('/')) {
+    if (seg === '..') segments.pop();
+    else if (seg && seg !== '.') segments.push(seg);
+  }
+  return segments.join('/');
+}
+
+export function isDenied(denyPaths, path) {
+  if (!denyPaths.length || !path) return false;
+  const p = normPath(path);
+  return denyPaths.some(denied => p === denied || p.startsWith(denied + '/'));
+}
+
+// Returns an error message string if the tool call should be blocked, else null.
+export function checkAccess(denyPaths, toolName, args) {
+  if (!denyPaths.length) return null;
+
+  switch (toolName) {
+    case 'read-note':
+    case 'create-note':
+    case 'edit-note': {
+      const p = normPath(args.folder, args.filename);
+      if (isDenied(denyPaths, p)) return `Access denied: '${p}' is restricted`;
+      break;
+    }
+
+    case 'delete-note': {
+      const p = normPath(args.folder, args.filename);
+      if (isDenied(denyPaths, p)) return `Access denied: '${p}' is restricted`;
+      break;
+    }
+
+    case 'move-note': {
+      const src = normPath(args.folder, args.filename);
+      const dst = normPath(args.newFolder, args.newFilename);
+      if (isDenied(denyPaths, src)) return `Access denied: source '${src}' is restricted`;
+      if (isDenied(denyPaths, dst)) return `Access denied: destination '${dst}' is restricted`;
+      break;
+    }
+
+    case 'create-binary-file':
+    case 'fetch-binary-file': {
+      const p = normPath(args.folder, args.filename);
+      if (isDenied(denyPaths, p)) return `Access denied: '${p}' is restricted`;
+      break;
+    }
+
+    case 'delete-binary-file': {
+      const p = normPath(args.folder, args.filename);
+      if (isDenied(denyPaths, p)) return `Access denied: '${p}' is restricted`;
+      break;
+    }
+
+    case 'move-binary-file': {
+      const src = normPath(args.folder, args.filename);
+      const dst = normPath(args.newFolder, args.newFilename);
+      if (isDenied(denyPaths, src)) return `Access denied: source '${src}' is restricted`;
+      if (isDenied(denyPaths, dst)) return `Access denied: destination '${dst}' is restricted`;
+      break;
+    }
+
+    case 'find-backlinks': {
+      const p = normPath(args.folder, args.filename);
+      if (isDenied(denyPaths, p)) return `Access denied: '${p}' is restricted`;
+      break;
+    }
+
+    case 'resolve-wikilink': {
+      // The target is a free-text string, not a known path — this is a cheap upfront
+      // check on the literal string; walkAllFiles's own per-candidate filtering is what
+      // actually keeps denied files out of the result regardless.
+      if (args.target) {
+        const p = normPath(args.target);
+        if (isDenied(denyPaths, p)) return `Access denied: '${p}' is restricted`;
+      }
+      break;
+    }
+
+    case 'add-tags':
+    case 'remove-tags': {
+      const files = Array.isArray(args.files) ? args.files : [];
+      const blocked = files.map(f => normPath(f)).find(f => isDenied(denyPaths, f));
+      if (blocked) return `Access denied: '${blocked}' is restricted`;
+      break;
+    }
+
+    case 'create-folder': {
+      const p = normPath(args.folder);
+      if (isDenied(denyPaths, p)) return `Access denied: '${p}' is restricted`;
+      break;
+    }
+
+    case 'search-vault': {
+      if (args.path) {
+        const p = normPath(args.path);
+        if (isDenied(denyPaths, p)) return `Access denied: '${p}' is restricted`;
+      }
+      break;
+    }
+  }
+  return null;
+}

package/lib/fetch.mjs

@@ -0,0 +1,184 @@
+// SSRF-safe URL fetching for fetch-binary-file. A caller-supplied URL is effectively
+// a request to make this host issue an arbitrary outbound call — on any deployment,
+// that host may have private network services reachable that shouldn't be — so every
+// function here exists to keep that call scoped to the public internet.
+
+import dns from 'node:dns/promises';
+import http from 'node:http';
+import https from 'node:https';
+
+const MAX_REDIRECTS = 5;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+function ipv4ToInt(ip) {
+  const parts = ip.split('.').map(Number);
+  return ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0;
+}
+
+function ipv4InRange(ip, base, bits) {
+  const mask = bits === 0 ? 0 : (0xffffffff << (32 - bits)) >>> 0;
+  return (ipv4ToInt(ip) & mask) === (ipv4ToInt(base) & mask);
+}
+
+// Loopback, link-local, and the three RFC1918 private ranges.
+const PRIVATE_V4_RANGES = [
+  ['0.0.0.0', 8],
+  ['127.0.0.0', 8],
+  ['169.254.0.0', 16],
+  ['10.0.0.0', 8],
+  ['172.16.0.0', 12],
+  ['192.168.0.0', 16],
+];
+
+export function isPrivateIPv4(ip) {
+  return PRIVATE_V4_RANGES.some(([base, bits]) => ipv4InRange(ip, base, bits));
+}
+
+export function isPrivateIPv6(ip) {
+  const lower = ip.toLowerCase();
+  if (lower === '::1' || lower === '::') return true; // loopback / unspecified
+  if (/^fe[89ab][0-9a-f]:/.test(lower)) return true; // fe80::/10 link-local
+  if (/^f[cd][0-9a-f]{2}:/.test(lower)) return true; // fc00::/7 unique-local
+  const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/); // IPv4-mapped IPv6
+  if (mapped) return isPrivateIPv4(mapped[1]);
+  return false;
+}
+
+/**
+ * Validates that url is an http(s) URL whose hostname resolves only to public
+ * addresses. Throws with a clear message otherwise.
+ * @returns {Promise<{parsed: URL, addresses: {address: string, family: number}[]}>}
+ *   The resolved addresses are returned so the caller can pin its connection to them
+ *   (see fetchToBuffer) — re-resolving the hostname later, e.g. inside a plain
+ *   fetch()/http.request() call, would reopen a DNS-rebinding gap between this check
+ *   and the actual connection.
+ */
+export async function validateUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`URL scheme must be http or https: ${url}`);
+  }
+
+  // URL.hostname serializes an IPv6 literal with brackets (e.g. "[::1]"), but
+  // dns.lookup expects the bare address — passing the bracketed form fails to
+  // resolve it at all, which would make an IPv6-literal URL error out instead of
+  // actually being checked (as happened here: a CI environment without IPv6
+  // correctly failed to resolve "[::1]", exposing that a same-host environment
+  // resolving it by coincidence was never validating the address, just erroring).
+  const lookupHost = parsed.hostname.startsWith('[') && parsed.hostname.endsWith(']')
+    ? parsed.hostname.slice(1, -1)
+    : parsed.hostname;
+
+  let addresses;
+  try {
+    addresses = await dns.lookup(lookupHost, { all: true, verbatim: true });
+  } catch {
+    throw new Error(`Could not resolve hostname: ${parsed.hostname}`);
+  }
+  if (!addresses.length) {
+    throw new Error(`Could not resolve hostname: ${parsed.hostname}`);
+  }
+  for (const { address, family } of addresses) {
+    const isPrivate = family === 4 ? isPrivateIPv4(address) : isPrivateIPv6(address);
+    if (isPrivate) {
+      throw new Error(`URL resolves to a disallowed address (${address}): ${url}`);
+    }
+  }
+  return { parsed, addresses };
+}
+
+// A dns.lookup-compatible function that ignores whatever hostname it's asked to
+// resolve and always returns the address(es) validateUrl already vetted — this is
+// what pins the actual socket to the validated IP, closing the DNS-rebinding gap
+// between validation and connection (the hostname could otherwise resolve to a
+// different, private address on a second, independent lookup).
+function pinnedLookup(addresses) {
+  const first = addresses[0];
+  return (_hostname, _options, callback) => callback(null, first.address, first.family);
+}
+
+/**
+ * Downloads url and returns its body as a Buffer, enforcing maxBytes while streaming
+ * (aborting mid-transfer rather than after the fact) and a hard per-hop timeoutMs
+ * (covering both DNS resolution via validateUrl and the HTTP request itself).
+ * Redirects are followed manually, up to MAX_REDIRECTS hops, with validateUrl re-run
+ * on every hop's target — never just the first. Uses node:http/https directly (not
+ * the global fetch) so the connection can be pinned to the exact address validateUrl
+ * already checked, rather than letting the request re-resolve the hostname itself.
+ */
+export async function fetchToBuffer(url, { maxBytes, timeoutMs }) {
+  let currentUrl = url;
+
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; controller.abort(); }, timeoutMs);
+
+    try {
+      // validateUrl's dns.lookup has no cancellation of its own, so a hostname
+      // pointed at a slow or unresponsive resolver (fully attacker-controlled,
+      // since the URL is caller-supplied) could otherwise stall past timeoutMs
+      // despite the "hard per-hop timeout" this function promises. Racing it
+      // against the same abort signal bounds the wait even though the underlying
+      // lookup can't itself be cancelled; the losing promise is given a no-op
+      // catch so its eventual settlement doesn't surface as an unhandled rejection.
+      const validatePromise = validateUrl(currentUrl);
+      validatePromise.catch(() => {});
+      const { parsed, addresses } = await Promise.race([
+        validatePromise,
+        new Promise((_resolve, reject) => {
+          controller.signal.addEventListener('abort', () => reject(new Error('timed out')));
+        }),
+      ]);
+      if (timedOut) throw new Error('timed out');
+
+      const client = parsed.protocol === 'https:' ? https : http;
+      const response = await new Promise((resolve, reject) => {
+        const req = client.request(parsed, {
+          lookup: pinnedLookup(addresses),
+          servername: parsed.hostname, // keep TLS SNI/cert hostname checks against the real hostname
+          signal: controller.signal,
+        }, resolve);
+        req.on('error', reject);
+        req.end();
+      });
+
+      if (REDIRECT_STATUSES.has(response.statusCode)) {
+        response.resume(); // discard the redirect body
+        const location = response.headers.location;
+        if (!location) throw new Error(`Redirect response (${response.statusCode}) had no Location header`);
+        currentUrl = new URL(location, parsed).toString();
+        continue;
+      }
+
+      if (response.statusCode < 200 || response.statusCode >= 300) {
+        response.resume();
+        throw new Error(`Request failed with status ${response.statusCode}`);
+      }
+
+      const chunks = [];
+      let total = 0;
+      for await (const chunk of response) {
+        total += chunk.length;
+        if (total > maxBytes) {
+          response.destroy();
+          throw new Error(`Response exceeded maxBytes (${maxBytes} bytes)`);
+        }
+        chunks.push(chunk);
+      }
+      return Buffer.concat(chunks);
+    } catch (err) {
+      if (timedOut) throw new Error(`Request timed out after ${timeoutMs}ms`);
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  throw new Error(`Too many redirects (limit ${MAX_REDIRECTS})`);
+}

package/lib/frontmatter.mjs

@@ -0,0 +1,212 @@
+// Pure functions for Obsidian YAML frontmatter parsing and tag manipulation.
+// All functions take and return content strings; no filesystem I/O.
+
+import { escRe } from './utils.mjs';
+
+const FM_RE = /^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/;
+const TAGS_INLINE_RE = /^tags:\s*\[([^\]]*)\]/m;
+const TAGS_BLOCK_RE = /^tags:\s*\r?\n((?:[ \t]+-[^\r\n]*\r?\n?)*)/m;
+
+/** Matches `field: [...]` inline-array style, for any field name. */
+function fieldInlineRe(field) {
+  return new RegExp(`^${escRe(field)}:[ \\t]*\\[[^\\]]*\\][ \\t]*$`, 'm');
+}
+
+/** Matches `field:\n  - ...` block-sequence style, for any field name. */
+function fieldBlockRe(field) {
+  return new RegExp(`^${escRe(field)}:\\s*\\r?\\n((?:[ \\t]+-[^\\r\\n]*\\r?\\n?)*)`, 'm');
+}
+
+/** Matches a plain `field: value` scalar line, for any field name. */
+function fieldScalarRe(field) {
+  return new RegExp(`^${escRe(field)}:[ \\t]*[^\\r\\n]*$`, 'm');
+}
+
+const YAML_SPECIAL_LEADING = /^[-?:,[\]{}#&*!|>'"%@`]/;
+const YAML_LOOKS_LIKE_NUMBER = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
+const YAML_LOOKS_LIKE_KEYWORD = /^(true|false|null|~)$/i;
+
+/**
+ * Serializes a scalar value (string/number/boolean) for a single YAML
+ * frontmatter line, quoting a string only when required to keep it a string.
+ * @returns {string} The serialized value, quoted if necessary.
+ */
+export function serializeScalar(value) {
+  if (typeof value === 'boolean' || typeof value === 'number') return String(value);
+  const needsQuoting =
+    value === '' ||
+    /[\r\n]/.test(value) ||
+    value.includes(': ') ||
+    YAML_SPECIAL_LEADING.test(value) ||
+    YAML_LOOKS_LIKE_NUMBER.test(value) ||
+    YAML_LOOKS_LIKE_KEYWORD.test(value);
+  return needsQuoting ? JSON.stringify(value) : value;
+}
+
+function parseTagsFromBody(body) {
+  const inline = TAGS_INLINE_RE.exec(body);
+  if (inline) {
+    return inline[1]
+      .split(',')
+      .map(t => t.trim().replace(/^['"]|['"]$/g, ''))
+      .filter(Boolean);
+  }
+  const block = TAGS_BLOCK_RE.exec(body);
+  if (block) {
+    return block[1]
+      .split('\n')
+      .map(l => l.replace(/^[ \t]+-\s*/, '').trim())
+      .filter(Boolean);
+  }
+  return [];
+}
+
+/**
+ * Extracts tag list from YAML frontmatter (inline or block format).
+ * @returns {string[]} Tag names, or empty array if no frontmatter or tags found.
+ */
+export function parseTags(content) {
+  const fm = FM_RE.exec(content);
+  return fm ? parseTagsFromBody(fm[1]) : [];
+}
+
+function buildTagsSection(tags) {
+  if (tags.length === 0) return 'tags: []';
+  return `tags:\n${tags.map(t => `  - ${t}`).join('\n')}`;
+}
+
+function replaceTagsInBody(body, tags) {
+  const newSection = buildTagsSection(tags);
+  if (TAGS_INLINE_RE.test(body)) {
+    return body.replace(TAGS_INLINE_RE, newSection);
+  }
+  if (TAGS_BLOCK_RE.test(body)) {
+    // Block regex captures trailing newlines in each entry; replace whole block + trailing newline
+    return body.replace(TAGS_BLOCK_RE, newSection + '\n');
+  }
+  return body.trimEnd() + '\n' + newSection;
+}
+
+/**
+ * Replaces the tags section in frontmatter, creating frontmatter if missing.
+ */
+export function setTags(content, tags) {
+  const fm = FM_RE.exec(content);
+  if (!fm) {
+    return `---\n${buildTagsSection(tags)}\n---\n${content}`;
+  }
+  const newBody = replaceTagsInBody(fm[1], tags);
+  const after = content.slice(fm.index + fm[0].length);
+  return `---\n${newBody.trimEnd()}\n---${fm[2]}${after}`;
+}
+
+/**
+ * Adds tags to frontmatter, skipping duplicates. Returns content unchanged if all tags already exist.
+ */
+export function addTags(content, tagsToAdd) {
+  const existing = parseTags(content);
+  const existingSet = new Set(existing);
+  const toAdd = tagsToAdd.filter(t => !existingSet.has(t));
+  if (!toAdd.length) return content;
+  return setTags(content, [...existing, ...toAdd]);
+}
+
+/**
+ * Removes tags from frontmatter. Returns content unchanged if no tags were removed.
+ */
+export function removeTags(content, tagsToRemove) {
+  const existing = parseTags(content);
+  const removeSet = new Set(tagsToRemove);
+  const remaining = existing.filter(t => !removeSet.has(t));
+  if (remaining.length === existing.length) return content;
+  return setTags(content, remaining);
+}
+
+/**
+ * Renames a tag in frontmatter only. Returns content unchanged if tag not found.
+ */
+export function renameFrontmatterTag(content, oldTag, newTag) {
+  const tags = parseTags(content);
+  if (!tags.includes(oldTag)) return content;
+  return setTags(content, tags.map(t => (t === oldTag ? newTag : t)));
+}
+
+/**
+ * Renames inline tags (e.g., #tag syntax) in content, respecting word boundaries.
+ * Matches tags preceded by whitespace or start-of-line, not followed by tag-valid characters.
+ */
+export function renameInlineTag(content, oldTag, newTag) {
+  // Match #tag preceded by whitespace or start-of-line, not followed by tag-valid chars
+  // Tag-valid chars in Obsidian: [a-zA-Z0-9_/-]
+  const re = new RegExp(`(^|[ \\t])#${escRe(oldTag)}(?![a-zA-Z0-9_/\\-])`, 'gm');
+  return content.replace(re, (_, prefix) => `${prefix}#${newTag}`);
+}
+
+/**
+ * Renames a tag everywhere: in frontmatter and inline (#tag syntax).
+ */
+export function renameTag(content, oldTag, newTag) {
+  let result = renameFrontmatterTag(content, oldTag, newTag);
+  result = renameInlineTag(result, oldTag, newTag);
+  return result;
+}
+
+/** Replaces a field with a new line, handling inline, block, scalar, or missing cases. */
+function replaceFieldInBody(body, field, newLine) {
+  if (fieldInlineRe(field).test(body)) {
+    return body.replace(fieldInlineRe(field), newLine);
+  }
+  if (fieldBlockRe(field).test(body)) {
+    return body.replace(fieldBlockRe(field), newLine + '\n');
+  }
+  if (fieldScalarRe(field).test(body)) {
+    return body.replace(fieldScalarRe(field), newLine);
+  }
+  const trimmed = body.trimEnd();
+  return trimmed ? trimmed + '\n' + newLine : newLine;
+}
+
+/**
+ * Sets a single frontmatter field to a scalar value, creating the
+ * frontmatter block or the field itself if either is missing. Overwrites
+ * an existing inline, block, or scalar value for that field.
+ */
+export function setFrontmatterField(content, field, value) {
+  const newLine = `${field}: ${serializeScalar(value)}`;
+  const fm = FM_RE.exec(content);
+  if (!fm) {
+    return `---\n${newLine}\n---\n${content}`;
+  }
+  const newBody = replaceFieldInBody(fm[1], field, newLine);
+  const after = content.slice(fm.index + fm[0].length);
+  return `---\n${newBody.trimEnd()}\n---${fm[2]}${after}`;
+}
+
+/** Removes a field and its value from the body; returns null if the field is not found. */
+function removeFieldFromBody(body, field) {
+  if (fieldInlineRe(field).test(body)) {
+    return body.replace(new RegExp(`^${escRe(field)}:[ \\t]*\\[[^\\]]*\\][ \\t]*\\r?\\n?`, 'm'), '');
+  }
+  if (fieldBlockRe(field).test(body)) {
+    return body.replace(fieldBlockRe(field), '');
+  }
+  if (fieldScalarRe(field).test(body)) {
+    return body.replace(new RegExp(`^${escRe(field)}:[ \\t]*[^\\r\\n]*\\r?\\n?`, 'm'), '');
+  }
+  return null;
+}
+
+/**
+ * Removes a single frontmatter field (its inline, block, or scalar value).
+ * Returns content unchanged if the field or the frontmatter block itself
+ * doesn't exist.
+ */
+export function removeFrontmatterField(content, field) {
+  const fm = FM_RE.exec(content);
+  if (!fm) return content;
+  const newBody = removeFieldFromBody(fm[1], field);
+  if (newBody === null) return content;
+  const after = content.slice(fm.index + fm[0].length);
+  const trimmed = newBody.trimEnd();
+  return trimmed ? `---\n${trimmed}\n---${fm[2]}${after}` : `---\n---${fm[2]}${after}`;
+}

package/lib/preconditions.mjs

@@ -0,0 +1,51 @@
+// Compare-and-swap write preconditions based on a file's last-modified time.
+// No filesystem I/O here except the single stat assertUnmodified performs.
+
+import fs from 'node:fs/promises';
+
+const ISO_MTIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+/**
+ * Formats a fs.Stats mtime the same way read-note and list-notes already do,
+ * so there is exactly one implementation a client's expectedMtime is compared against.
+ */
+export function formatMtime(stat) {
+  return stat.mtime.toISOString();
+}
+
+/**
+ * Throws if expectedMtime isn't the exact ISO 8601 string read-note/list-notes emit
+ * (a malformed value is rejected up front, before it's ever compared against a real
+ * file, so the failure clearly names the bad input rather than surfacing as a
+ * confusing mtime mismatch).
+ */
+export function validateExpectedMtime(expectedMtime) {
+  if (typeof expectedMtime !== 'string' || !ISO_MTIME_RE.test(expectedMtime)) {
+    throw new Error(`Invalid expectedMtime "${expectedMtime}": must be an ISO 8601 timestamp as returned by read-note/list-notes`);
+  }
+}
+
+/**
+ * Asserts that the file at absPath's current mtime matches expectedMtime, throwing a
+ * precondition-failure error (naming both values) if it doesn't, or a distinct error if
+ * the file no longer exists at all. Used as a compare-and-swap guard immediately before
+ * a write, not as a lock — the window between this check and the write itself is not
+ * closed, deliberately, since the realistic conflict this guards against is an edit
+ * seconds or minutes old, not a same-instant race.
+ */
+export async function assertUnmodified(absPath, expectedMtime) {
+  validateExpectedMtime(expectedMtime);
+  let stat;
+  try {
+    stat = await fs.stat(absPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new Error(`Precondition failed: file no longer exists (expected mtime ${expectedMtime})`);
+    }
+    throw err;
+  }
+  const actual = formatMtime(stat);
+  if (actual !== expectedMtime) {
+    throw new Error(`Precondition failed: file was modified (expected mtime ${expectedMtime}, actual ${actual}). Re-read and retry.`);
+  }
+}