MCP (Model Context Protocol) server for reading and writing an Obsidian vault, gated by OAuth-issued JWT bearer tokens. See README.md for setup.
This commit is contained in:
@@ -0,0 +1,55 @@
|
||||
using System.Text.Json;
|
||||
|
||||
namespace ObsidianMcp.Services;
|
||||
|
||||
/// <summary>
|
||||
/// 写操作审计日志（JSON lines 格式，按天 rotate）。
|
||||
/// 输出到 /app/logs/audit-YYYY-MM-DD.log。
|
||||
/// 注册为 Singleton，内部用 lock 保证多线程写入安全。
|
||||
/// </summary>
|
||||
public class AuditLogger
|
||||
{
|
||||
private readonly string _logDir;
|
||||
private readonly object _lock = new();
|
||||
|
||||
public AuditLogger(IConfiguration config)
|
||||
{
|
||||
// 允许通过配置覆盖日志目录，默认 /app/logs
|
||||
_logDir = config["AuditLog:Directory"] ?? "/app/logs";
|
||||
Directory.CreateDirectory(_logDir);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 记录一次写操作审计条目。
|
||||
/// </summary>
|
||||
public void LogWrite(
|
||||
string user,
|
||||
string clientId,
|
||||
string tool,
|
||||
string path,
|
||||
long bytes,
|
||||
bool ok,
|
||||
string? error = null)
|
||||
{
|
||||
var entry = new
|
||||
{
|
||||
timestamp = DateTime.UtcNow.ToString("O"),
|
||||
user,
|
||||
tool,
|
||||
path,
|
||||
bytes,
|
||||
client_id = clientId,
|
||||
ok,
|
||||
error,
|
||||
};
|
||||
|
||||
var line = JsonSerializer.Serialize(entry);
|
||||
var fileName = $"audit-{DateTime.UtcNow:yyyy-MM-dd}.log";
|
||||
var filePath = Path.Combine(_logDir, fileName);
|
||||
|
||||
lock (_lock)
|
||||
{
|
||||
File.AppendAllText(filePath, line + Environment.NewLine);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,142 @@
|
||||
using ObsidianMcp.Config;
|
||||
using Microsoft.Extensions.Options;
|
||||
|
||||
namespace ObsidianMcp.Services;
|
||||
|
||||
/// <summary>
|
||||
/// Vault 路径安全守卫（chroot 语义）。
|
||||
///
|
||||
/// 职责：
|
||||
/// - 把相对路径拼接到 VaultRoot，防止路径穿越（../）
|
||||
/// - 拒绝绝对路径输入
|
||||
/// - 拒绝命中黑名单的路径段
|
||||
///
|
||||
/// 线程安全，注册为 Singleton。
|
||||
/// </summary>
|
||||
public class VaultPathResolver
|
||||
{
|
||||
// hardcode 黑名单路径段（任意路径段命中即拒）。
|
||||
// 这几个是 Obsidian / Git 的内部目录，访问它们既无意义也容易踩坑（例如读取 .obsidian
|
||||
// 配置可能泄露插件 secret）。用户可通过 Vault__Blacklist__N 追加自己的敏感目录。
|
||||
private static readonly HashSet<string> HardcodeBlacklist =
|
||||
new(StringComparer.OrdinalIgnoreCase)
|
||||
{
|
||||
".obsidian",
|
||||
".trash",
|
||||
".git",
|
||||
};
|
||||
|
||||
private readonly string _root;
|
||||
private readonly HashSet<string> _blacklist;
|
||||
|
||||
public VaultPathResolver(IOptions<VaultOptions> opts)
|
||||
{
|
||||
var o = opts.Value;
|
||||
_root = Path.GetFullPath(o.Root);
|
||||
|
||||
// 合并 hardcode + env 配置的黑名单，去重
|
||||
_blacklist = new HashSet<string>(HardcodeBlacklist, StringComparer.OrdinalIgnoreCase);
|
||||
foreach (var b in o.Blacklist)
|
||||
if (!string.IsNullOrWhiteSpace(b))
|
||||
_blacklist.Add(b.Trim());
|
||||
}
|
||||
|
||||
/// <summary>返回 vault 根目录的绝对路径（规范化后）。</summary>
|
||||
public string VaultRoot => _root;
|
||||
|
||||
/// <summary>
|
||||
/// 将相对路径解析为 vault 内的绝对路径。
|
||||
///
|
||||
/// 可能抛出：
|
||||
/// UnauthorizedAccessException — 路径穿越、绝对路径、命中黑名单、目标是 symlink
|
||||
/// ArgumentException — relativePath 为空
|
||||
/// </summary>
|
||||
public string Resolve(string relativePath)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(relativePath))
|
||||
throw new ArgumentException("路径不能为空。", nameof(relativePath));
|
||||
|
||||
// 拒绝绝对路径输入（防止容器外访问；包括 Linux /etc/... 与 Windows C:\... / UNC \\server）
|
||||
if (Path.IsPathRooted(relativePath))
|
||||
throw new UnauthorizedAccessException(
|
||||
$"拒绝绝对路径输入：{relativePath}");
|
||||
|
||||
// 把 Windows 反斜杠归一化成 Unix 分隔符，避免 Linux 容器上把 "..\\.." 当成单段不消解。
|
||||
// 注意：仅对相对路径输入做归一化；root 路径已经由 Path.GetFullPath 处理过。
|
||||
var normalizedRel = relativePath.Replace('\\', '/');
|
||||
|
||||
// 拼接并规范化（自动消解 .. 和 .）
|
||||
var target = Path.GetFullPath(Path.Combine(_root, normalizedRel));
|
||||
|
||||
// 确认解析后的路径仍在 vault root 内
|
||||
if (!IsUnderRoot(target))
|
||||
throw new UnauthorizedAccessException(
|
||||
$"路径穿越 vault 根目录：{relativePath}");
|
||||
|
||||
// 逐段检查黑名单
|
||||
CheckBlacklist(target, relativePath);
|
||||
|
||||
// 拒绝 symlink（无论指向 vault 内外，统一禁；vault 真实内容应是普通文件 / 目录）。
|
||||
// 这是兜底防线：万一 WebDAV / 操作失误把 symlink 落到 vault 里，避免 Tool 跟随到容器外。
|
||||
RejectSymlink(target, relativePath);
|
||||
|
||||
return target;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 检查路径自身（以及任一父级路径段）是否是 symlink。是 → 拒绝。
|
||||
/// 防御链外文件 leak（例如有人在 vault 里建一个指向 /etc/passwd 的软链）。
|
||||
/// </summary>
|
||||
private void RejectSymlink(string absPath, string original)
|
||||
{
|
||||
// 从 absPath 一直向上检查到 _root（不含 root 本体；root 是已知信任的挂载点）
|
||||
var current = absPath;
|
||||
while (current != null && current.Length > _root.Length)
|
||||
{
|
||||
try
|
||||
{
|
||||
var info = new FileInfo(current);
|
||||
if (info.Exists && info.LinkTarget != null)
|
||||
throw new UnauthorizedAccessException($"拒绝 symlink 路径：{original}");
|
||||
if (!info.Exists)
|
||||
{
|
||||
var di = new DirectoryInfo(current);
|
||||
if (di.Exists && di.LinkTarget != null)
|
||||
throw new UnauthorizedAccessException($"拒绝 symlink 路径：{original}");
|
||||
}
|
||||
}
|
||||
catch (UnauthorizedAccessException) { throw; }
|
||||
catch
|
||||
{
|
||||
// I/O 异常不在这里阻断；后续真正读文件时会自然抛
|
||||
}
|
||||
var parent = Path.GetDirectoryName(current);
|
||||
if (parent == null || parent == current) break;
|
||||
current = parent;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>检查绝对路径是否在 vault root 下（含等于 root）。</summary>
|
||||
private bool IsUnderRoot(string absPath)
|
||||
{
|
||||
return absPath == _root
|
||||
|| absPath.StartsWith(_root + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase);
|
||||
}
|
||||
|
||||
/// <summary>逐个路径段检查黑名单。</summary>
|
||||
private void CheckBlacklist(string absPath, string original)
|
||||
{
|
||||
// 把 absPath 中 root 之后的部分按分隔符拆分，逐段比对
|
||||
var relative = absPath[_root.Length..].TrimStart(Path.DirectorySeparatorChar);
|
||||
var segments = relative.Split(
|
||||
[Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar],
|
||||
StringSplitOptions.RemoveEmptyEntries);
|
||||
|
||||
foreach (var seg in segments)
|
||||
{
|
||||
if (_blacklist.Contains(seg))
|
||||
throw new UnauthorizedAccessException(
|
||||
$"路径命中黑名单段 '{seg}'：{original}");
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,104 @@
|
||||
using Microsoft.Extensions.FileSystemGlobbing;
|
||||
using Microsoft.Extensions.FileSystemGlobbing.Abstractions;
|
||||
|
||||
namespace ObsidianMcp.Services;
|
||||
|
||||
/// <summary>
|
||||
/// Vault 全文搜索服务。
|
||||
/// 纯 C# 实现，大小写不敏感子串匹配（不支持 regex）。
|
||||
/// V3 可替换为 ripgrep 调用。
|
||||
/// </summary>
|
||||
public class VaultSearchService
|
||||
{
|
||||
private readonly VaultPathResolver _resolver;
|
||||
|
||||
public VaultSearchService(VaultPathResolver resolver)
|
||||
{
|
||||
_resolver = resolver;
|
||||
}
|
||||
|
||||
/// <param name="query">大小写不敏感的子串</param>
|
||||
/// <param name="glob">glob 过滤，例如 "Notes/**/*.md"，为 null 时搜全 vault</param>
|
||||
/// <param name="limit">最多返回条数</param>
|
||||
/// <param name="ct">CancellationToken</param>
|
||||
public async Task<List<SearchHit>> SearchAsync(
|
||||
string query,
|
||||
string? glob,
|
||||
int limit,
|
||||
CancellationToken ct = default)
|
||||
{
|
||||
var root = _resolver.VaultRoot;
|
||||
var files = GetFilesToSearch(root, glob);
|
||||
|
||||
var hits = new List<SearchHit>();
|
||||
foreach (var file in files)
|
||||
{
|
||||
if (ct.IsCancellationRequested) break;
|
||||
if (hits.Count >= limit) break;
|
||||
|
||||
await SearchFileAsync(file, root, query, limit, hits, ct);
|
||||
}
|
||||
|
||||
return hits;
|
||||
}
|
||||
|
||||
private static IEnumerable<string> GetFilesToSearch(string root, string? glob)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(glob))
|
||||
{
|
||||
// 全 vault 搜索，只搜 .md 文件（.json/.yaml 通常不需要全文检索）
|
||||
return Directory.EnumerateFiles(root, "*.md", SearchOption.AllDirectories);
|
||||
}
|
||||
|
||||
// 用 Microsoft.Extensions.FileSystemGlobbing 做 glob 过滤
|
||||
var matcher = new Matcher(StringComparison.OrdinalIgnoreCase);
|
||||
matcher.AddInclude(glob);
|
||||
var dirInfo = new DirectoryInfoWrapper(new DirectoryInfo(root));
|
||||
var result = matcher.Execute(dirInfo);
|
||||
return result.Files.Select(f => Path.Combine(root, f.Path));
|
||||
}
|
||||
|
||||
private static async Task SearchFileAsync(
|
||||
string filePath,
|
||||
string root,
|
||||
string query,
|
||||
int limit,
|
||||
List<SearchHit> hits,
|
||||
CancellationToken ct)
|
||||
{
|
||||
// 跳过过大的文件（>5MB），避免 OOM
|
||||
var fi = new FileInfo(filePath);
|
||||
if (!fi.Exists || fi.Length > 5 * 1024 * 1024) return;
|
||||
|
||||
try
|
||||
{
|
||||
int lineNumber = 0;
|
||||
await foreach (var line in File.ReadLinesAsync(filePath, ct))
|
||||
{
|
||||
lineNumber++;
|
||||
if (hits.Count >= limit) break;
|
||||
|
||||
if (line.Contains(query, StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
hits.Add(new SearchHit
|
||||
{
|
||||
File = Path.GetRelativePath(root, filePath).Replace('\\', '/'),
|
||||
Line = lineNumber,
|
||||
Preview = line.Length > 200 ? line[..200] + "..." : line,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
catch (IOException)
|
||||
{
|
||||
// 文件读取失败（权限、锁定等），跳过不影响其他结果
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public class SearchHit
|
||||
{
|
||||
public string File { get; set; } = "";
|
||||
public int Line { get; set; }
|
||||
public string Preview { get; set; } = "";
|
||||
}
|
||||
@@ -0,0 +1,91 @@
|
||||
using ObsidianMcp.Config;
|
||||
using Microsoft.Extensions.Options;
|
||||
|
||||
namespace ObsidianMcp.Services;
|
||||
|
||||
/// <summary>
|
||||
/// 写入门禁——在路径安全（VaultPathResolver）之上再加写入白名单控制。
|
||||
///
|
||||
/// 规则优先级（从高到低）：
|
||||
/// 1. 永禁写入：AGENTS.md / README.md / CLAUDE.md（任何路径下的同名文件）
|
||||
/// 2. 必须命中写入白名单之一才允许（由 Vault__WriteWhitelist__N 配置）
|
||||
///
|
||||
/// 白名单格式：
|
||||
/// - 以 / 或 \ 结尾 → 前缀匹配（例如 "Notes/" 允许 Notes 目录及其子树）
|
||||
/// - 不以斜杠结尾 → 精确路径匹配（例如 "todo.md"）
|
||||
///
|
||||
/// 默认白名单为空：未配置 Vault__WriteWhitelist__N 时所有写入都会被拒绝。
|
||||
/// </summary>
|
||||
public class VaultWriteGuard
|
||||
{
|
||||
// 永禁写入的文件名（任意目录下的同名文件都禁写）。
|
||||
// 这几个是 agent / 仓库根常见的元信息文件，写坏会导致工具自身或下游 agent 行为异常。
|
||||
private static readonly HashSet<string> ForbiddenFileNames =
|
||||
new(StringComparer.OrdinalIgnoreCase)
|
||||
{
|
||||
"AGENTS.md",
|
||||
"README.md",
|
||||
"CLAUDE.md",
|
||||
};
|
||||
|
||||
private readonly VaultPathResolver _resolver;
|
||||
private readonly string[] _writeWhitelist;
|
||||
|
||||
public VaultWriteGuard(VaultPathResolver resolver, IOptions<VaultOptions> opts)
|
||||
{
|
||||
_resolver = resolver;
|
||||
_writeWhitelist = opts.Value.WriteWhitelist ?? [];
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 校验相对路径是否允许写入。
|
||||
/// 通过则返回规范化后的绝对路径；不通过则抛 UnauthorizedAccessException。
|
||||
/// </summary>
|
||||
public string EnsureWritable(string relativePath)
|
||||
{
|
||||
// 先过路径安全守卫（防穿越 + 黑名单）
|
||||
var absPath = _resolver.Resolve(relativePath);
|
||||
|
||||
// 规范化相对路径（用于白名单匹配），统一用 /
|
||||
var normalized = NormalizeRelative(relativePath);
|
||||
|
||||
// 1. 永禁文件名
|
||||
var fileName = Path.GetFileName(absPath);
|
||||
if (ForbiddenFileNames.Contains(fileName))
|
||||
throw new UnauthorizedAccessException(
|
||||
$"禁止写入保护文件：{relativePath}");
|
||||
|
||||
// 2. 写入白名单
|
||||
if (!IsInWhitelist(normalized))
|
||||
throw new UnauthorizedAccessException(
|
||||
$"路径不在写入白名单内：{relativePath}");
|
||||
|
||||
return absPath;
|
||||
}
|
||||
|
||||
private bool IsInWhitelist(string normalized)
|
||||
{
|
||||
foreach (var entry in _writeWhitelist)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(entry)) continue;
|
||||
var normalizedEntry = NormalizeRelative(entry);
|
||||
if (normalizedEntry.EndsWith('/'))
|
||||
{
|
||||
// 前缀匹配
|
||||
if (normalized.StartsWith(normalizedEntry, StringComparison.OrdinalIgnoreCase))
|
||||
return true;
|
||||
}
|
||||
else
|
||||
{
|
||||
// 精确匹配
|
||||
if (string.Equals(normalized, normalizedEntry, StringComparison.OrdinalIgnoreCase))
|
||||
return true;
|
||||
}
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
/// <summary>统一用 / 作分隔符，用于白名单匹配。</summary>
|
||||
private static string NormalizeRelative(string path) =>
|
||||
path.Replace('\\', '/');
|
||||
}
|
||||
Reference in New Issue
Block a user