feat(vscode): add vault write protection mode setting

Introduce `obsidianVFS.vault.mode` (`"rw" | "ro" | "partial"`) to
control write access through the obs:// FileSystemProvider. Read-only
mode registers the provider with `isReadonly: true`; partial mode
restricts writes to autoMount paths via mount tree validation.

Guards all five write methods (writeFile, createDirectory, delete,
rename, copy) with a `checkVaultMode` check before path validation.
Provider re-registers dynamically on mode change to update the
isReadonly flag. Status bar shows lock icon with mode suffix for
non-rw modes.

Protection covers obs:// tree view operations, drag-and-drop into the
tree, and obs:// editor saves. The file:// workspace folder (Explorer,
Quick Open, Search) bypasses the provider — documented as a known
limitation pending FileSearchProvider/TextSearchProvider stabilization.

Assisted-by: Claude

Author: otaviof

AGENTS.md

@@ -35,6 +35,7 @@ Style, file layout, patterns: [CONTRIBUTING.md#conventions](CONTRIBUTING.md#conv
 - **Vault-side exclusion toggles** — `vault.excludeDotfiles` + `vault.excludeDotfilePattern` control dotfile hiding; `vault.excludeBlocked` controls blocked-path hiding; `vault.gitIgnore` controls `git.ignoredRepositories` management. Each is independently toggleable at runtime.
 - **Sub-path exclusion** — when `autoMount` contains nested paths (e.g., `["20-areas/idea"]`), `files.exclude` patterns hide sibling directories (`20-areas/career`, `20-areas/otaviof`) to match tree view visibility. Computed via mount tree (`packages/core/src/mount-tree.ts`). Controlled by `workspace.excludeUnmountedFolders`.
 - **File-level exclusion** — `obsidianVFS.workspace.excludeUnmountedFilePattern` provides a regex tested against file basenames at partially-mounted levels. Matching files generate `{prefix}/*{ext}` glob patterns in the folder-scoped `files.exclude` tier, hiding Obsidian files (`.md`, `.base`, `.canvas`) from Explorer and Quick Open without affecting same-named files in other workspace folders. Gated by `workspace.excludeUnmountedFiles` toggle. Default: `\\.(md|base|canvas)$`.
+- **Vault write protection** — `obsidianVFS.vault.mode` controls write access through the `obs://` FileSystemProvider. `"ro"` registers the provider with `isReadonly: true`; `"partial"` enforces autoMount-scoped writes at the provider level. Protection covers tree view operations, drag-and-drop into the tree, and `obs://` editor saves. The `file://` workspace folder (Explorer panel, Quick Open, Search) bypasses the provider entirely — drag-and-drop, rename, delete, and editor saves via `file://` remain writable regardless of vault mode. This gap closes when `FileSearchProvider`/`TextSearchProvider` stabilize.
 - **`obs://` FileSystemProvider** remains registered for the Explorer tree view sidebar, wikilinks, drag-and-drop, and watch events — it does not back a workspace folder.
 - **`FileSearchProvider`/`TextSearchProvider` are proposed (unstable) APIs** as of `@types/vscode@1.118.0`. When stabilized, the extension can switch to a single `obs://` workspace folder with native search, eliminating the `files.exclude` workaround. Check `@types/vscode` for stable availability — do not use while proposed.
 

packages/core/src/index.ts

@@ -13,14 +13,15 @@ export type {
   MentionResult,
   ResolutionResult,
   VaultContext,
+  VaultMode,
   VFSConfig,
   VFSError,
   VFSFileStat,
   VFSFileType,
   VFSResult,
   WikilinkResolution,
 } from "./types.js";
-export { ERR, ERRNO } from "./types.js";
+export { ERR, ERRNO, VAULT_MODE } from "./types.js";
 
 /**
  * Parsed `obs://` URI components.
@@ -88,6 +89,7 @@ export {
   canonicalizePath,
   isAllowedPath,
   checkBlockedFolder,
+  checkVaultMode,
 } from "./path-security.js";
 
 /**

packages/core/src/path-security.test.ts

@@ -5,10 +5,12 @@ import {
   checkAllowedFolder,
   checkBlockedFolder,
   checkSymlink,
+  checkVaultMode,
   isAllowedPath,
   validatePath,
   validatePathForWrite,
 } from "./path-security.js";
+import type { VaultMode } from "./types.js";
 import { mockFsFunction } from "./test-helpers.js";
 
 vi.mock("node:fs/promises", () => ({
@@ -409,3 +411,112 @@ describe("validatePathForWrite", () => {
     expect(result).toEqual({ ok: true, value: "/vault/notes/new.md" });
   });
 });
+
+describe("checkVaultMode", () => {
+  it.each<{
+    name: string;
+    path: string;
+    mode: VaultMode;
+    autoMount: string[];
+    ok: boolean;
+    message?: string;
+  }>([
+    { name: "rw permits any path", path: "any/path.md", mode: "rw", autoMount: [], ok: true },
+    {
+      name: "rw permits path even with autoMount set",
+      path: "unmounted/file.md",
+      mode: "rw",
+      autoMount: ["Notes"],
+      ok: true,
+    },
+    {
+      name: "ro denies any path",
+      path: "Notes/file.md",
+      mode: "ro",
+      autoMount: [],
+      ok: false,
+      message: "Vault is read-only",
+    },
+    {
+      name: "ro denies with autoMount set",
+      path: "Notes/file.md",
+      mode: "ro",
+      autoMount: ["Notes"],
+      ok: false,
+      message: "Vault is read-only",
+    },
+    {
+      name: "partial with exact match permits write",
+      path: "Notes/file.md",
+      mode: "partial",
+      autoMount: ["Notes"],
+      ok: true,
+    },
+    {
+      name: "partial with nested mount permits write",
+      path: "20-areas/idea/plan.md",
+      mode: "partial",
+      autoMount: ["20-areas/idea"],
+      ok: true,
+    },
+    {
+      name: "partial with parent of mount denies write",
+      path: "20-areas/work/plan.md",
+      mode: "partial",
+      autoMount: ["20-areas/idea"],
+      ok: false,
+      message: "Path not within mounted folders",
+    },
+    {
+      name: "partial with unmounted path denies write",
+      path: "Archive/old.md",
+      mode: "partial",
+      autoMount: ["Notes"],
+      ok: false,
+      message: "Path not within mounted folders",
+    },
+    {
+      name: "partial with empty autoMount denies all paths",
+      path: "any/path.md",
+      mode: "partial",
+      autoMount: [],
+      ok: false,
+      message: "Path not within mounted folders",
+    },
+    {
+      name: "partial with root-level file not in mount denies write",
+      path: "readme.md",
+      mode: "partial",
+      autoMount: ["Notes"],
+      ok: false,
+      message: "Path not within mounted folders",
+    },
+    {
+      name: "partial permits writing to mounted dir itself",
+      path: "Notes",
+      mode: "partial",
+      autoMount: ["Notes"],
+      ok: true,
+    },
+    {
+      name: "partial permits deeply nested path in mount",
+      path: "Notes/deep/nested/file.md",
+      mode: "partial",
+      autoMount: ["Notes"],
+      ok: true,
+    },
+    {
+      name: "partial with multiple mounts permits any mounted path",
+      path: "Projects/active/todo.md",
+      mode: "partial",
+      autoMount: ["Notes", "Projects"],
+      ok: true,
+    },
+  ])("$name", ({ path, mode, autoMount, ok, message }) => {
+    const result = checkVaultMode(path, mode, autoMount);
+    expect(result.ok).toBe(ok);
+    if (!ok && message) {
+      expect((result as { ok: false; error: { message: string } }).error.message).toBe(message);
+    }
+  });
+});

packages/core/src/path-security.ts

@@ -1,8 +1,9 @@
 import { realpath } from "node:fs/promises";
 import path from "node:path";
 
-import { ERR, ERRNO } from "./types.js";
-import type { VFSResult } from "./types.js";
+import { ERR, ERRNO, VAULT_MODE } from "./types.js";
+import type { VFSResult, VaultMode } from "./types.js";
+import { buildMountTree } from "./mount-tree.js";
 
 /**
  * Immutable parameters for path security checks — vault root, folder allowlist,
@@ -120,6 +121,43 @@ export async function checkSymlink(
   }
 }
 
+/**
+ * Check whether a write to `virtualPath` is permitted under the given
+ * vault mode. Returns `PERMISSION_DENIED` when the write is blocked.
+ *
+ * - `"rw"`: always permits.
+ * - `"ro"`: always rejects.
+ * - `"partial"`: permits if `virtualPath` falls within an `autoMount` entry.
+ */
+export function checkVaultMode(
+  virtualPath: string,
+  mode: VaultMode,
+  autoMount: readonly string[],
+): VFSResult<string> {
+  if (mode === VAULT_MODE.RW) return { ok: true, value: virtualPath };
+  if (mode === VAULT_MODE.RO) {
+    return {
+      ok: false,
+      error: { code: ERR.PERMISSION_DENIED, message: "Vault is read-only" },
+    };
+  }
+  const tree = buildMountTree(autoMount);
+  const segments = virtualPath.split("/").filter(Boolean);
+  let node: ReturnType<typeof buildMountTree> | null = tree;
+  for (const seg of segments) {
+    if (node === null) return { ok: true, value: virtualPath };
+    const child = node.get(seg);
+    if (child === undefined) {
+      return {
+        ok: false,
+        error: { code: ERR.PERMISSION_DENIED, message: "Path not within mounted folders" },
+      };
+    }
+    node = child;
+  }
+  return { ok: true, value: virtualPath };
+}
+
 /**
  * Compose all path security checks in order: canonicalize → allowed/blocked →
  * symlink. Short-circuits on first failure. Returns the validated absolute path.

packages/core/src/types.ts

@@ -79,6 +79,16 @@ export interface Disposable {
   dispose(): void;
 }
 
+/** Vault access mode constants. */
+export const VAULT_MODE = {
+  RW: "rw",
+  RO: "ro",
+  PARTIAL: "partial",
+} as const;
+
+/** Vault access mode controlling write operations through the obs:// FileSystemProvider. */
+export type VaultMode = (typeof VAULT_MODE)[keyof typeof VAULT_MODE];
+
 /**
  * Filesystem entry type for directory enumeration.
  */

packages/vscode/README.md

@@ -54,6 +54,7 @@ Controls vault-side `files.exclude` policy written to `<vault>/.vscode/settings.
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
+| `obsidianVFS.vault.mode` | `"rw" \| "ro" \| "partial"` | `"rw"` | Write access mode: `"rw"` (read-write, all writes allowed), `"ro"` (read-only, no writes through `obs://`), `"partial"` (writes only to `autoMount` paths) |
 | `obsidianVFS.vault.gitIgnore` | `boolean` | `true` | Add the vault to `git.ignoredRepositories` so VS Code's Git extension skips it |
 | `obsidianVFS.vault.excludeBlocked` | `boolean` | `true` | Hide `blocked` folders (from `.obsidian/obsidian-vfs.json`) via `files.exclude` |
 | `obsidianVFS.vault.excludeDotfiles` | `boolean` | `true` | Hide dotfiles and dotdirs at the vault root (`.obsidian`, `.trash`, etc.) |
@@ -122,6 +123,7 @@ This matches the tree view — only mounted paths appear in both views.
 
 - **Vault `.vscode/` directory:** The extension creates `.vscode/settings.json` inside the vault for vault-global `files.exclude` patterns (dotfiles and `blocked` paths). These patterns are independent of `autoMount` and apply to any workspace that includes the vault. The `.vscode/` directory itself is never managed by the extension — if you want to hide it, add `.vscode` to your own `files.exclude`. When `obsidianVFS.workspace.enabled` is disabled, all managed patterns are removed from both folder and workspace settings. If your vault is git-tracked, consider adding `.vscode/` to the vault's `.gitignore`.
 - **Not a security boundary:** `files.exclude` hides content from Explorer and Quick Open but does not enforce access restrictions. The `obs://` `FileSystemProvider`'s path security (`allowed`/`blocked` lists in `.obsidian-vfs.json`) applies to tree view, wikilink, and drag-and-drop operations.
+- **Write protection covers `obs://` only:** `vault.mode` (`"ro"` / `"partial"`) guards write operations through the `obs://` `FileSystemProvider` — tree view sidebar, drag-and-drop into the tree, and `obs://` editor saves. The `file://` workspace folder (Explorer panel, Quick Open, Search) bypasses the provider and remains writable regardless of vault mode. This gap closes when VS Code stabilizes `FileSearchProvider`/`TextSearchProvider`, allowing a single `obs://` workspace folder.
 - **Temporary workaround:** `files.exclude` is used because VS Code's [`FileSearchProvider`/`TextSearchProvider`](https://github.com/microsoft/vscode/issues/73524) APIs are still proposed (unstable). When stabilized, the extension can switch to a single `obs://` workspace folder with native search, eliminating the `files.exclude` patterns entirely.
 - **Title bar:** Adding the vault as a workspace folder creates a multi-root workspace. VS Code may show "UNTITLED (WORKSPACE)" in the title bar.
 

packages/vscode/package.json

@@ -136,6 +136,16 @@
           "default": "^\\.",
           "markdownDescription": "Regex tested against entry names at the vault root. Only dotfiles matching this pattern are hidden when `vault.excludeDotfiles` is enabled. Default `^\\\\.` matches all dotfiles. Example: `^\\\\.(obsidian|trash)` to hide only `.obsidian` and `.trash`."
         },
+        "obsidianVFS.vault.mode": {
+          "type": "string",
+          "enum": [
+            "rw",
+            "ro",
+            "partial"
+          ],
+          "default": "rw",
+          "markdownDescription": "Vault access mode controlling write operations through the `obs://` file system.\n- `rw`: Read-write — all writes permitted (default).\n- `ro`: Read-only — no writes allowed.\n- `partial`: Only writes to `autoMount` paths are allowed; everything else is read-only.\n\nThis setting protects tree view operations, drag-and-drop, and `obs://` editor saves. The `file://` workspace folder (used for Quick Open and Search) is not affected."
+        },
         "obsidianVFS.statusBar.enabled": {
           "type": "boolean",
           "default": true,

packages/vscode/src/bootstrap.ts

@@ -1,6 +1,6 @@
 import * as vscode from "vscode";
-import { bootstrapTracker, resolveCliPath } from "@obsidian-vfs/core";
-import type { BootstrapResult, VFSResult } from "@obsidian-vfs/core";
+import { bootstrapTracker, resolveCliPath, VAULT_MODE } from "@obsidian-vfs/core";
+import type { BootstrapResult, VaultMode, VFSResult } from "@obsidian-vfs/core";
 
 import { CONFIG_PROP, CONFIG_SECTION } from "./types.js";
 import type { ExtensionConfig } from "./types.js";
@@ -18,6 +18,7 @@ export function readConfig(): ExtensionConfig {
     vaultExcludeBlocked: cfg.get<boolean>(CONFIG_PROP.vaultExcludeBlocked)!,
     vaultExcludeDotfiles: cfg.get<boolean>(CONFIG_PROP.vaultExcludeDotfiles)!,
     vaultExcludeDotfilePattern: cfg.get<string>(CONFIG_PROP.vaultExcludeDotfilePattern)!,
+    vaultMode: cfg.get<VaultMode>(CONFIG_PROP.vaultMode, VAULT_MODE.RW),
     // Status Bar
     statusBarEnabled: cfg.get<boolean>(CONFIG_PROP.statusBarEnabled)!,
     // Explorer