proton-drive-mcp 1.10.0 → 1.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,61 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.11.0 — 2026-11-19
4
+
5
+ ### Behaviour change: human approval gate, fail closed by default
6
+ - **Destructive and outward-facing operations now need a human yes, asked by the server.** The default (`PROTON_DRIVE_APPROVAL` unset or `human`) is fail closed.
7
+ - With a client that can show MCP elicitation (Claude Code CLI does), you will now see a dialog on calls that used to pass silently when the assistant sent `confirmed: true`.
8
+ - With a client that cannot (whether Claude Desktop can is not verified), gated calls are refused with `approval_required` until you approve them in a terminal (`proton-drive-cli approve <code>`, or `npx -y -p proton-drive-mcp proton-drive-cli approve <code>` without a global install, then ask the assistant to repeat the call; the terminal must use the same `PROTON_DRIVE_APPROVAL_DIR` / `HOME` / `XDG_CACHE_HOME` as the server), or until you set `PROTON_DRIVE_APPROVAL=model` knowingly.
9
+ - `confirmed` is no longer an authorisation. It is still accepted in the schemas where it was, no longer required, and ignored in `human` and `strict`. On `drive_bulk_move` and `drive_bulk_trash` it remains the plan/apply switch. `PROTON_DRIVE_APPROVAL=model` restores the 1.10.1 behaviour (a startup warning is written to stderr).
10
+ - Unattended or scheduled runs that change Drive must set `PROTON_DRIVE_APPROVAL=model`, ideally with `PROTON_DRIVE_REMOTE_ROOTS` and the audit log.
11
+ - Tool descriptions no longer tell the assistant to pass `confirmed=true`; they say the server asks the user.
12
+ - The `next` field of a `drive_bulk_move` / `drive_bulk_trash` plan now says "Call again with confirmed=true to apply; the server will ask the user for approval itself" (human and strict; `model` keeps the old text).
13
+
14
+ ### Security
15
+ - The assistant can no longer approve its own destructive operation by sending `confirmed: true`. The prompt is built by the server from validated values (fixed first line per tool, one line per value; control, bidirectional and zero-width characters in names are made visible and cannot add or reorder lines; passwords and message texts are not shown), and what is shown is what is executed.
16
+ - New in the gated set: `drive_invitation_accept`, and `drive_copy`, `drive_move`, `drive_mkdir`, `drive_rename`, `drive_upload`, `drive_write_file`, `drive_trash`, `drive_restore` and the bulk tools when a path they read from or write to is under `/shared-with-me`. This closes a chain that needed no gated tool: accept an invitation, then copy files into the inviter's folder.
17
+ - Look-alike letters from another alphabet in an e-mail address, an inviter or an item name are listed by code point in the prompt; every Unicode format or default-ignorable character is shown as `\uXXXX`. Operations addressed by `uid` alone (`drive_delete`, invitation accept/reject) show the item, inviter and folder, looked up before the question (`(name not resolved)` when that fails).
18
+ - A closed or failed dialog discards an already approved terminal record for the same operation and writes a fresh pending one, so an old unused approval can no longer answer a question that was just asked; an accepted or declined dialog also removes leftover records (best effort).
19
+ - Backslashes are doubled in prompts, so the text `\u200b` in a name differs from a real zero-width space; the Braille blank and no-break or wide spaces (U+00A0, U+2000-200A, U+202F, U+205F, U+3000) are shown as `\uXXXX` in every field.
20
+ - Prompt text: every control character (C0, DEL, C1) is shown as `\uXXXX` instead of a space, escape sequences are no longer parsed (only the ESC byte becomes `\x1b`, the rest stays visible, so no letter is swallowed and an unterminated sequence hides nothing), and the Ogham space mark (U+1680) is escaped.
21
+ - Only one approval dialog is open at a time; further gated calls meanwhile are refused (`approval_unavailable`), not queued.
22
+ - A dialog that is cancelled, fails or times out falls back to the terminal route (`approval_required` with a code) instead of refusing outright; an explicit decline stays final.
23
+ - A misconfigured approvals folder (inside the sync folder) is reported on stderr at startup and the assistant is told it is a server setting.
24
+ - Bulk apply is tied to the plan the user approved: the plan is computed again after approval, and nothing is applied if it differs (`approval_changed`).
25
+ - The approvals folder cannot be written by `drive_download` or `photos_download`, and the server refuses to use one inside `PROTON_DRIVE_SYNC_PATH`.
26
+ - `drive_write_file` creates a new file exclusively; if the file appears after the existence check, the call goes through the gate like an overwrite.
27
+ - Documented limits: a client that gives the assistant a shell can run the official `proton-drive` CLI directly (deny rule example for Claude Code in the README); a client or hook that answers the dialog automatically switches the gate off; copies into an already shared folder under `/my-files` are not checked.
28
+
29
+ ### Added
30
+ - MCPB bundle: setting **Who approves destructive operations** (`approval_mode`: `human` by default, `strict` or `model`), passed to the server as `PROTON_DRIVE_APPROVAL`.
31
+ - `PROTON_DRIVE_APPROVAL=human|strict|model` and `PROTON_DRIVE_APPROVAL_DIR`.
32
+ - `strict` mode: every tool that changes Drive or the account needs a human yes, including single trash, restore, moves and uploads.
33
+ - Companion CLI commands `approvals`, `approve <code>` and `deny <code>` for terminal approval (`approve` needs an interactive terminal and a typed `yes`). A terminal approval is valid once, for that exact operation, for 5 minutes; a request lasts 10 minutes.
34
+ - Audit log: refusal codes `approval_required`, `approval_declined`, `approval_unavailable`, `approval_changed`, and an `approval` field (`channel`, short operation hash, `code` for terminal approvals) on approved calls. Existing logs still verify.
35
+ - Human approval section in the README, rewritten gate section in THREAT_MODEL.md, approval steps in the safe-use guide.
36
+
37
+ ### Deprecated
38
+ - `confirmed` as an authorisation. Removal from the non-bulk tools, and a rename of the bulk switch, are planned for 2.0.
39
+
40
+ ### Untested
41
+ - Whether Claude Desktop shows the approval dialog for a local server, how any client renders long prompts, and the terminal route on Windows.
42
+
43
+ ## 1.10.1 — 2026-11-19
44
+
45
+ ### Security
46
+ - Local path checks (upload, download, sync plan, photo tools) now ignore letter case on macOS and Windows and resolve existing paths with `realpath.native`, so `~/.SSH` is treated like `~/.ssh`. Linux stays case-sensitive. Windows behaviour is untested in CI.
47
+ - The local deny list also covers shell start-up files (`.zshrc`, `.bashrc`, `.profile`, the logout files and the other login-shell files) and `LaunchAgents`/`LaunchDaemons` folders.
48
+ - Downloads are checked under the name each item gets inside the destination folder, and a downloaded folder may not contain a protected location.
49
+ - Readonly mode: `drive_download` and `photos_download` refuse the `remove` conflict strategies, which delete existing local files. Plain downloads stay available. Documented in the README and THREAT_MODEL.
50
+ - Folder uploads are checked entry by entry, not only at the top. An upload is refused, with a message naming the entry, if the folder holds a folder named `.ssh`, `.aws` or `.gnupg`, a secret-looking file (`.env*`, keys and certificates, `.netrc`, `.npmrc`, `.pgpass`, `.git-credentials`, the gcloud files `credentials.db`, `access_tokens.db`, `application_default_credentials.json` and `legacy_credentials`, `.docker/config.json`, `.kube/config`, `.config/gcloud`), or a symlink that leads out of the folder. Other folders named `.docker`, `.kube` or `gcloud` are allowed. Files such as `.env.example` are refused too unless `PROTON_DRIVE_ALLOW_SENSITIVE_PATHS=1` is set. With `PROTON_DRIVE_LOCAL_ROOT` set only the symlink check applies. Folders with more than 200,000 entries are now refused, because they cannot be checked. Checks go by name: a renamed copy of a credential folder is not recognised.
51
+ - Local write tools: a download is refused when the path an item will be written to equals or lies inside the audit log, its `.lock` or a `.versions` snapshot folder of the sync folder, or (for a folder item) would contain them. The download folder itself may sit above them. A remote path without an item name is refused. A downloaded drive root (`/my-files`, `/photos`, ...) is written by the CLI as `<folder>/root`, so that name is checked, and for such a download the folder itself may not hold the audit log or a `.versions` folder. `drive_write_file` refuses `.versions` paths.
52
+
53
+ ### Fixed
54
+ - `PROTON_DRIVE_REMOTE_ROOTS`: the final path of `drive_move`, `drive_copy`, `drive_rename` and `drive_bulk_move` is now checked against the roots, not only the path arguments; `drive_move` can no longer target a root folder itself.
55
+
56
+ ### Changed
57
+ - THREAT_MODEL.md and the README now state that `confirmed: true` is an argument the model sets, not human approval, that bulk apply calls are not tied to a plan, and which controls do protect (readonly mode, remote roots, audit log, client tool approval, elicitation where supported). No behavior change.
58
+
3
59
  ## 1.10.0 — 2026-11-18
4
60
 
5
61
  ### Added
package/README.md CHANGED
@@ -42,7 +42,7 @@ Give Claude Desktop (or any MCP client) full access to your Proton Drive and Pro
42
42
  - "What is using my Drive space?" (`drive_usage`)
43
43
  - "Find duplicate files in my Drive." (`drive_find_duplicates`)
44
44
  - "Who has access to my shared folders?" (`drive_sharing_audit`)
45
- - "Tidy up /Downloads, show me a plan first." (`drive_bulk_move` / `drive_bulk_trash` preview first, nothing changes until you confirm)
45
+ - "Tidy up /Downloads, show me a plan first." (`drive_bulk_move` / `drive_bulk_trash` preview first, nothing changes until you approve)
46
46
  4. Sensitive files? Start read-only and confined: `PROTON_DRIVE_MODE=readonly` and `PROTON_DRIVE_REMOTE_ROOTS=/my-files/<folder>`, plus an audit log ([guard layer](#guard-layer-opt-in), [secure setup](SECURITY.md#secure-deployment-profile)).
47
47
  5. Optional: `PROTON_DRIVE_INDEX=1` keeps a plaintext local copy of file names so searches are instant after a restart ([details](#persistent-index-opt-in)); `PROTON_DRIVE_TOOL_TIER=core` exposes a smaller tool set.
48
48
 
@@ -79,14 +79,14 @@ Ask: "Who has access to my shared folders?" and then "Which public links expire
79
79
  - `drive_sharing_audit` lists public links (role, expiry, password), invitees and pending invitations, with risk flags such as `public-link-no-expiry`, `public-link-editor` and `external-invitee`.
80
80
  - `drive_share_expiry_report` lists public links with the time left, soonest first (`withinDays` sets what counts as soon).
81
81
 
82
- Both only read; they change nothing, and link URLs are left out of the results. Each checks at most 100 shared items, so on a big drive point it at one folder at a time. To act on a finding, `drive_share_remove_url` or `drive_share_revoke` change sharing; they ask for confirmation.
82
+ Both only read; they change nothing, and link URLs are left out of the results. Each checks at most 100 shared items, so on a big drive point it at one folder at a time. To act on a finding, `drive_share_remove_url` or `drive_share_revoke` change sharing; the server asks you to approve each one ([Human approval](#human-approval-on-by-default)).
83
83
 
84
84
  ### Tidy a folder safely
85
85
 
86
86
  Ask: "Move all the PDFs in /Downloads into /Documents/Inbox. Show me the plan first."
87
87
 
88
88
  1. `drive_bulk_move` (or `drive_bulk_trash` for clean-up) without `confirmed` returns a plan and any problems and changes nothing.
89
- 2. Read the plan. If it is right, say so, and Claude repeats the call with `confirmed=true`. It applies only if there are no problems.
89
+ 2. Read the plan. If it is right, say so, and Claude repeats the call with `confirmed=true`. That argument only switches from plan to apply; it is not your approval. Before anything moves, the server shows you the exact list (every path when there are 50 or fewer, otherwise counts per folder and the first 50) and asks you to approve it. It applies only if there are no problems, and only if the plan it computes after your approval is the same as the one you saw; if Drive changed in between, nothing is applied (`approval_changed`). If your client cannot show the dialog, the call is refused until you approve it in a terminal ([Human approval](#human-approval-on-by-default), [threat model](THREAT_MODEL.md)).
90
90
  3. Trash is reversible: `drive_restore` brings an item back (`drive_list_trash` shows what is there). `drive_empty_trash` and `drive_delete` are permanent, so do not ask for those during a tidy-up.
91
91
 
92
92
  Each call handles up to 200 items. For a first attempt on important data, use the [guard layer](#guard-layer-opt-in) (`PROTON_DRIVE_REMOTE_ROOTS` limits the folders Claude can touch).
@@ -100,7 +100,7 @@ New to this and want to stay cautious? See the [safe-use guide](docs/GUIDE.md).
100
100
  For syncing, backups and cron jobs, **use the official CLI directly**: it is simpler and that is what it is for. This project does not replace it; it needs it, and wraps it so an AI assistant can drive it. It is worth using when you want to work with your Drive by conversation:
101
101
 
102
102
  - **Things the CLI does not have** (it has no search, recursive listing, usage or content-reading commands, and Drive's end-to-end encryption rules out server-side search): `drive_search`, `drive_tree`, `drive_usage`, `drive_find_duplicates` (verified by sha256), `drive_sharing_audit`, `drive_read_content`, `drive_sync_plan`. They run locally on your computer, so encryption stays intact.
103
- - **Safe changes by an AI:** destructive or outward-facing actions need explicit confirmation, bulk move/trash is two steps (plan first, then apply), trash is reversible, and the duplicate finder never deletes anything. A bare CLI assumes you know exactly what you are doing.
103
+ - **Safe changes by an AI:** destructive or outward-facing actions need your own approval, asked by the server and not by the assistant (a dialog in your client, or a command you run in a terminal); bulk move/trash is two steps (plan first, then apply), trash is reversible, and the duplicate finder never deletes anything. A bare CLI assumes you know exactly what you are doing.
104
104
  - **Rough edges smoothed over:** the CLI reports some per-item failures with exit code 0, returns lists in random order, and can fail with `database is locked` under parallel calls. The server checks per-item results, sorts and paginates lists, and retries read-only calls.
105
105
 
106
106
  What to expect: search matches names, sizes and dates, not the text of every file (you read one file at a time); the first walk of a large drive takes minutes unless you enable the opt-in [persistent index](#persistent-index-opt-in); and this is an independent project, not an official Proton product.
@@ -189,7 +189,7 @@ Restart Claude Desktop. Check **`+` → Connectors → proton-drive-mcp** to con
189
189
 
190
190
  ### One-click install (MCPB bundle)
191
191
 
192
- Instead of editing JSON, download `proton-drive-mcp-<version>.mcpb` from the [latest GitHub release](https://github.com/googlarz/proton-drive-mcp/releases/latest) and open it (or drag it into **Settings → Extensions** in Claude Desktop). In the extension settings, set **proton-drive CLI path** to the output of `which proton-drive` (usually `~/.local/bin/proton-drive`); optionally set the **Proton Drive sync folder** to enable `drive_read_file` / `drive_write_file`, and the **Persistent search index** switch (off by default; it stores file names in plain text on this computer, see [Persistent index](#persistent-index-opt-in)). You still need the official `proton-drive` CLI installed and `proton-drive auth login` done once.
192
+ Instead of editing JSON, download `proton-drive-mcp-<version>.mcpb` from the [latest GitHub release](https://github.com/googlarz/proton-drive-mcp/releases/latest) and open it (or drag it into **Settings → Extensions** in Claude Desktop). In the extension settings, set **proton-drive CLI path** to the output of `which proton-drive` (usually `~/.local/bin/proton-drive`); optionally set the **Proton Drive sync folder** to enable `drive_read_file` / `drive_write_file`, and the **Persistent search index** switch (off by default; it stores file names in plain text on this computer, see [Persistent index](#persistent-index-opt-in)). The **Who approves destructive operations** setting (`human` by default, `strict`, or `model`) is `PROTON_DRIVE_APPROVAL`, see [Human approval](#human-approval-on-by-default). You still need the official `proton-drive` CLI installed and `proton-drive auth login` done once.
193
193
 
194
194
  ### If installed globally
195
195
 
@@ -314,6 +314,16 @@ proton-drive-cli restore /my-files/old-draft.pdf # restore from trash
314
314
  proton-drive-cli trash empty --confirm # permanently delete all trashed items
315
315
  ```
316
316
 
317
+ ### Approvals
318
+
319
+ Used when your MCP client cannot show an approval dialog (see [Human approval](#human-approval-on-by-default)). These commands only read and write local files; they need no Proton session.
320
+
321
+ ```bash
322
+ proton-drive-cli approvals # pending and approved requests: code, tool, status, time left, first line
323
+ proton-drive-cli approve K7Q2-M9XD # shows the server's record, asks you to type 'yes' (interactive terminal only)
324
+ proton-drive-cli deny K7Q2-M9XD # discard a request
325
+ ```
326
+
317
327
  ### Search, analytics and cleanup
318
328
  `drive_search` · `drive_tree` · `drive_usage` · `drive_find_duplicates` · `drive_sharing_audit` · `drive_sync_plan` · `drive_bulk_move` · `drive_bulk_trash`
319
329
 
@@ -333,7 +343,7 @@ proton-drive-cli index clear
333
343
  - The first walk of a large drive can take minutes (measured about 21 s per 1,200 files at the default concurrency (12); about 25 s at concurrency 8). `drive_search`, `drive_tree` and `drive_usage` stop waiting after 25 s (`PROTON_DRIVE_WALK_BUDGET_MS`, 0 = never) and return what was listed so far with `partial: true`, `continuing: true` (the walk is still running) and a `note`; the same walk keeps running in the background, so repeating the call returns the full result from cache. `drive_find_duplicates`, `drive_sharing_audit` and `drive_sync_plan` always wait for the complete walk. Later calls reuse a 5-minute in-memory cache; `refresh` bypasses it. With the opt-in persistent index, a saved copy up to 24 h old can answer first (marked `stale: true`).
334
344
  - Walks skip `.git` and `node_modules` by default.
335
345
  - With `PROTON_DRIVE_INDEX=1`, results may come from a saved index (`stale: true` = served from the saved index, not a walk made now) while a refresh runs; repeat the call or pass `refresh: true` for a fresh read. On a huge drive `drive_refresh_index` refreshes the index in resumable slices. Off by default, see [Persistent index](#persistent-index-opt-in).
336
- - Read-only tools (`drive_search`, `drive_tree`, `drive_usage`, `drive_find_duplicates`, `drive_sharing_audit`, `drive_share_expiry_report`, `drive_recent_changes`, `drive_sync_plan`) change nothing. `drive_bulk_move` and `drive_bulk_trash` are two-step: call without `confirmed` for the plan, then with `confirmed: true` to apply. Bulk trash is reversible with `drive_restore`.
346
+ - Read-only tools (`drive_search`, `drive_tree`, `drive_usage`, `drive_find_duplicates`, `drive_sharing_audit`, `drive_share_expiry_report`, `drive_recent_changes`, `drive_sync_plan`) change nothing. `drive_bulk_move` and `drive_bulk_trash` are two-step: call without `confirmed` for the plan, then with `confirmed: true` to apply; applying still needs your approval of the exact list. Bulk trash is reversible with `drive_restore`.
337
347
  - Duplicate detection uses the sha1 the uploader claimed, which is unverified. `verify: true` downloads the candidates and hashes them.
338
348
  - The sharing audit flags an invitee as external when the address is outside Proton domains, so Proton users on a custom domain are over-flagged.
339
349
  - Sizes are sums of file sizes, not your account quota.
@@ -454,7 +464,7 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
454
464
  | Tool | Description | Key parameters |
455
465
  |------|-------------|----------------|
456
466
  | `drive_auth_status` | Check if authenticated (probes `/my-files` — no native status command) | — |
457
- | `drive_auth_logout` | Log out (clear session) ⚠️ | `confirmed: true` |
467
+ | `drive_auth_logout` | Log out (clear session) ⚠️ | — |
458
468
  | `drive_version` | CLI and SDK version info | — |
459
469
  | `drive_list` | List files and folders at a path (paginated, default 200; `/` lists the roots) | `path`, `limit?`, `offset?` |
460
470
  | `drive_info` | Get metadata for one file/folder, including revision details (noise trimmed) | `path`, `verbose?` (raw CLI node) |
@@ -464,12 +474,12 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
464
474
  | `drive_tree` | Folder overview: per-folder file counts and size totals (largest first), depth-limited, cached 5 min | `path?`, `depth?` (default 2, max 10), `limit?`, `foldersOnly?`, `refresh?` |
465
475
  | `drive_search` | Find files/folders under a path in one cached walk: name (substring/glob; a glob containing `/` matches the path relative to `path`), type, extension, MIME prefix, size, modified date; sortable, paginated. Reports `walk.complete` — false means the walk was cut short and matches may be missing | `query?`, `glob?`, `path?`, `type?`, `mediaType?`, `extensions?`, `minSize?`, `maxSize?`, `modifiedAfter?`, `modifiedBefore?`, `sort?`, `limit?` (default 50, max 500), `offset?`, `refresh?` |
466
476
  | `drive_mkdir` | Create a new empty folder | `path` |
467
- | `drive_upload` | Upload local file or folder | `localPath`, `remotePath`, `fileConflictStrategy?` (skip/create-new-revision/rename/replace), `folderConflictStrategy?` (skip/merge/rename/replace), `confirmed?` (**required for `replace`** — it trashes the existing remote item) |
468
- | `drive_download` | Download to local path | `remotePath`, `localPath`, `fileConflictStrategy?` (skip/rename/remove), `folderConflictStrategy?` (skip/merge/rename/remove), `confirmed?` (**required for `remove`** — it deletes the existing local item) |
477
+ | `drive_upload` | Upload local file or folder | `localPath`, `remotePath`, `fileConflictStrategy?` (skip/create-new-revision/rename/replace), `folderConflictStrategy?` (skip/merge/rename/replace), `replace` trashes the existing remote item, so it needs your approval |
478
+ | `drive_download` | Download to local path | `remotePath`, `localPath`, `fileConflictStrategy?` (skip/rename/remove), `folderConflictStrategy?` (skip/merge/rename/remove), `remove` deletes the existing local item, so it needs your approval |
469
479
  | `drive_rename` | Rename in place, no move | `path`, `newName` |
470
480
  | `drive_move` | Move and/or rename | `sourcePath`, `destinationPath` |
471
481
  | `drive_copy` | Copy file or folder into another Drive folder | `sourcePath`, `destinationPath` (target *parent folder*), `newName?` |
472
- | `drive_delete` | Permanently delete an item already in trash ⚠️ | `path`, `confirmed: true` |
482
+ | `drive_delete` | Permanently delete an item already in trash ⚠️ | `path` |
473
483
  | `drive_list_trash` | List items currently in trash (paginated, default 100; includes `uid` — names are not unique in trash) | `limit?`, `offset?` |
474
484
  | `drive_share_status` | Get sharing members and URL | `path` |
475
485
  | `drive_usage` | Storage analytics for a subtree: totals, largest files/folders, extension and media-type breakdown, old files, trash stats (sum of file sizes, not the account quota) | `path?`, `top?`, `olderThanDays?`, `refresh?` |
@@ -481,35 +491,35 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
481
491
  | `drive_search_content` | Search the indexed file text: all words must match, BM25 ranking, trailing `*` = prefix on the last word. Returns path, score, snippet, `indexedAt`; results reflect the last index update (`stale: true`). Snippets are untrusted file content. See [Content search](#content-search-opt-in) | `query` (max 200 characters), `path?`, `limit?` (default 10, max 50) |
482
492
  | `drive_refresh_index` | Opt-in (`PROTON_DRIVE_INDEX=1`): refresh the saved folder index of a huge drive in resumable slices. Lists the folders whose saved listing is older than `maxAgeHours` (or never read), oldest first, within `timeBudgetMs`, and saves its progress; repeat until `complete`. Returns `foldersRefreshed`, `foldersReused`, `foldersRemaining`, `oldestListingAgeMs`, `etaCalls`, `saved`; with `changes: true` also counts and up to 50 sample paths of added, removed and modified entries in the re-listed folders. Changes nothing on Drive. See [Keeping the index fresh on huge drives](#keeping-the-index-fresh-on-huge-drives) | `path?` (default `/my-files`), `timeBudgetMs?` (default 25000, max 120000), `maxAgeHours?`, `changes?` |
483
493
  | `drive_audit_log` | Newest audit-log entries plus a hash-chain check (needs `PROTON_DRIVE_AUDIT_LOG`; works in readonly mode) | `limit?` (default 50) |
484
- | `drive_share_invite` | Invite a user (sends an email) ⚠️ | `path`, `email`, `role` (viewer/editor/admin), `message?`, `confirmed: true` |
485
- | `drive_share_revoke` | Revoke one person's access (fails if not a member) ⚠️ | `path`, `email`, `confirmed: true` |
486
- | `drive_share_remove_all` | Remove every member + pending invitation at once ⚠️ | `path`, `confirmed: true` |
487
- | `drive_share_set_url` | Create/replace a public share link ⚠️ (set-url replaces all link settings; if the path already has a link with a password and/or expiration that the call omits, it is refused before any change unless `resetSettings: true`; expiry max ~90 days) | `path`, `role?` (viewer/editor), `password?`, `expiration?`, `resetSettings?`, `confirmed: true` |
488
- | `drive_share_remove_url` | Remove the public share link ⚠️ | `path`, `confirmed: true` |
494
+ | `drive_share_invite` | Invite a user (sends an email) ⚠️ | `path`, `email`, `role` (viewer/editor/admin), `message?` |
495
+ | `drive_share_revoke` | Revoke one person's access (fails if not a member) ⚠️ | `path`, `email` |
496
+ | `drive_share_remove_all` | Remove every member + pending invitation at once ⚠️ | `path` |
497
+ | `drive_share_set_url` | Create/replace a public share link ⚠️ (set-url replaces all link settings; if the path already has a link with a password and/or expiration that the call omits, it is refused before any change unless `resetSettings: true`; expiry max ~90 days) | `path`, `role?` (viewer/editor), `password?`, `expiration?`, `resetSettings?` |
498
+ | `drive_share_remove_url` | Remove the public share link ⚠️ | `path` |
489
499
  | `drive_trash` | Move to trash | `path` |
490
500
  | `drive_sync_plan` | Read-only diff of a local folder vs a Drive folder (nothing transferred) | `localPath`, `drivePath`, `direction?` (up/down/both), `ignore?`, `compare?` (size-mtime/sha1), `limit?` |
491
- | `drive_bulk_move` | Move up to 200 items into an existing folder; without `confirmed` returns the plan and problems only | `sources`, `destinationFolder`, `confirmed?` (**required to apply**) |
492
- | `drive_bulk_trash` | Trash up to 200 items (recoverable); without `confirmed` returns the plan and problems only | `paths`, `confirmed?` (**required to apply**) |
501
+ | `drive_bulk_move` | Move up to 200 items into an existing folder; without `confirmed` returns the plan and problems only | `sources`, `destinationFolder`, `confirmed?` (plan/apply switch: `true` applies, after you approve the list) |
502
+ | `drive_bulk_trash` | Trash up to 200 items (recoverable); without `confirmed` returns the plan and problems only | `paths`, `confirmed?` (plan/apply switch: `true` applies, after you approve the list) |
493
503
  | `drive_restore` | Restore from trash | `path` |
494
- | `drive_empty_trash` | Permanently delete all trash ⚠️ | `confirmed: true` |
504
+ | `drive_empty_trash` | Permanently delete all trash ⚠️ | — |
495
505
  | `drive_read_file` | Read text file from local sync folder | `path` |
496
- | `drive_write_file` | Write text file to local sync folder ⚠️ (overwriting an existing file needs confirmation; max 5 MB) | `path`, `content`, `confirmed?` |
506
+ | `drive_write_file` | Write text file to local sync folder ⚠️ (overwriting an existing file needs your approval; max 5 MB) | `path`, `content` |
497
507
  | `drive_list_invitations` | List pending sharing invitations received | — |
498
- | `drive_invitation_accept` | Accept a pending invitation | `uid` (from `drive_list_invitations`) |
499
- | `drive_invitation_reject` | Reject a pending invitation ⚠️ | `uid` (from `drive_list_invitations`), `confirmed: true` |
500
- | `drive_share_leave` | Leave a shared folder shared with you ⚠️ | `path`, `confirmed: true` |
508
+ | `drive_invitation_accept` | Accept a pending invitation ⚠️ (needs your approval: it opens a folder someone else controls) | `uid` (from `drive_list_invitations`) |
509
+ | `drive_invitation_reject` | Reject a pending invitation ⚠️ | `uid` (from `drive_list_invitations`) |
510
+ | `drive_share_leave` | Leave a shared folder shared with you ⚠️ | `path` |
501
511
  | `photos_list_albums` | List all Proton Photos albums | — |
502
512
  | `photos_create_album` | Create a new empty album | `name` |
503
513
  | `photos_update_album` | Rename an album or change its cover photo | `albumPath`, `name?`, `coverPhotoUid?` |
504
- | `photos_delete_album` | Delete an album ⚠️ | `albumPath`, `confirmed: true`, `force?`, `save?` |
514
+ | `photos_delete_album` | Delete an album ⚠️ | `albumPath`, `force?`, `save?` |
505
515
  | `photos_list_album_photos` | List photos in an album (paginated, default 100) | `albumPath`, `loadDetails?`, `limit?`, `offset?` |
506
516
  | `photos_add_to_album` | Add a photo from your library to an album | `albumPath`, `photoPath` |
507
- | `photos_remove_from_album` | Remove a photo from an album (keeps it in library) ⚠️ | `albumPath`, `photoPath`, `confirmed: true` |
517
+ | `photos_remove_from_album` | Remove a photo from an album (keeps it in library) ⚠️ | `albumPath`, `photoPath` |
508
518
  | `photos_list_timeline` | List photos in your full library timeline (paginated, default 50) | `loadDetails?`, `limit?`, `offset?` |
509
- | `photos_download` | Download photos to a local folder | `photoPaths`, `localFolder`, `conflictStrategy?` (skip/rename/remove), `confirmed?` (**required for `remove`**) |
519
+ | `photos_download` | Download photos to a local folder | `photoPaths`, `localFolder`, `conflictStrategy?` (skip/rename/remove), `remove` needs your approval |
510
520
  | `photos_upload` | Upload local files directly into your Photos library | `localPaths`, `conflictStrategy?` (skip/rename) |
511
521
 
512
- > ⚠️ **Destructive and outward-facing tools** (deleting, sharing, public links, logout, and the `replace`/`remove` conflict strategies) require `confirmed: true`, and the CLI requires `--confirm` for the destructive ones. Describe the action to the user first, then pass `confirmed: true`. Tool arguments are validated against the published schema — unknown or mistyped arguments are rejected.
522
+ > ⚠️ **Destructive and outward-facing tools** (deleting, sharing, public links, logout, accepting or rejecting invitations, the `replace`/`remove` conflict strategies, overwriting a sync-folder file, and anything that writes into `/shared-with-me`) need a human yes that the server asks for itself: a dialog in your client, or `proton-drive-cli approve <code>` in a terminal. See [Human approval](#human-approval-on-by-default). The `confirmed` argument is **deprecated**: it is still accepted on the tools that had it, but it no longer authorises anything (except as the plan/apply switch of the two bulk tools, and in `PROTON_DRIVE_APPROVAL=model`). The companion CLI still requires `--confirm` for the destructive commands. Tool arguments are validated against the published schema — unknown or mistyped arguments are rejected.
513
523
 
514
524
  ---
515
525
 
@@ -529,12 +539,12 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
529
539
  ## Operational notes
530
540
 
531
541
  - Long listings are paginated (`limit` / `offset`, response `{total, offset, limit, hasMore, items}`) to keep responses small. Responses are compact JSON.
532
- - Local paths passed to upload/download/photos tools are checked: credential locations (`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.claude*`, keychains, `.env` files, …) are refused. Set `PROTON_DRIVE_LOCAL_ROOT` to allow only specific directories.
542
+ - Local paths passed to upload/download/photos tools are checked: credential and autostart locations (`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.claude*`, keychains, shell start-up files, `LaunchAgents`, `.env` files, …) are refused, ignoring letter case on macOS and Windows. A folder upload is checked entry by entry (a secret-looking file or a symlink out of the folder refuses it), and a download is checked under the name each item will get inside the folder. Set `PROTON_DRIVE_LOCAL_ROOT` to allow only specific directories.
533
543
  - The sync-folder tools (`drive_read_file` / `drive_write_file`) refuse to follow symlinks out of `PROTON_DRIVE_SYNC_PATH`.
534
544
  - Error messages come from the CLI's own output; the command line (and therefore any `--password`) is never echoed back.
535
545
  - `drive_move` accepts a full destination path (parent + new name) for a familiar interface, but the underlying CLI only has separate `move` (change parent) and `rename` (change name) commands — this MCP translates automatically, issuing one or both as needed.
536
546
  - `drive_delete` only works on items already in `/trash` or `/photos-trash` — the CLI rejects live paths. Trash an item first with `drive_trash`, or use `drive_empty_trash` to clear everything at once.
537
- - If the client declares MCP elicitation (form mode), a refused `confirmed` gate is put to the human instead, and `drive_bulk_move` / `drive_bulk_trash` ask before applying a `confirmed: true` call. Only an explicit approval runs the call; decline, cancel, timeout or error keep the refusal, and after 5 declined prompts in a minute the server stops prompting. This only upgrades refusals and bulk applies: a compromised model that supplies `confirmed: true` on any other tool is **not** stopped by it. Clients without elicitation behave as before. Confirmation prompts need a client that supports elicitation (Claude Code CLI today; Claude Desktop is unverified).
547
+ - Approval prompts use MCP elicitation (form mode), so the dialog needs a client that supports it. Claude Code CLI does; whether Claude Desktop shows the dialog for a local server is **not verified**. A client that cannot elicit gets the terminal route instead (`proton-drive-cli approve <code>`, or `npx -y -p proton-drive-mcp proton-drive-cli approve <code>` without a global install). See [Human approval](#human-approval-on-by-default). With `PROTON_DRIVE_APPROVAL=model` the old 1.10.1 behaviour applies: `confirmed: true` is enough, and an eliciting client is asked only when a call would otherwise be refused.
538
548
  - Walk-based tools (`drive_tree`, `drive_search`, `drive_usage`, `drive_find_duplicates`) read from a cache up to 5 minutes old (with the opt-in persistent index, up to 24 h old and marked `stale: true`; `drive_sharing_audit`, `drive_sync_plan` and `drive_find_duplicates` never serve the saved index, they only reuse saved folder listings read less than 5 minutes ago); changes made by other clients or processes are not seen until it expires or you pass `refresh: true`. The first walk of a large drive can take minutes (measured about 21 s per 1,200 files at the default concurrency (12)); `drive_search`, `drive_tree` and `drive_usage` return a `partial: true` result after 25 s and finish the walk in the background.
539
549
  - `drive_auth_status` has no native CLI equivalent — it probes by resolving `/my-files` and reports authenticated based on whether that succeeds.
540
550
  - Paths are always Drive-absolute: `/my-files/folder/file.pdf`. Relative paths are not supported.
@@ -548,13 +558,63 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
548
558
 
549
559
  Left out of `core` (use `full`): permanent deletion (`drive_delete`, `drive_empty_trash`), `drive_auth_logout`, public links, invitations and invites, album management, `photos_upload` and the sync-file tools. A call to a hidden tool returns an error asking for `PROTON_DRIVE_TOOL_TIER=full`; no CLI command runs.
550
560
 
561
+ ### Human approval (on by default)
562
+
563
+ Since 1.11.0 a destructive or outward-facing operation runs only after a person says yes to that exact operation. The server asks, not the assistant. The assistant's own `confirmed: true` is no longer an authorisation.
564
+
565
+ **What needs approval** (default mode, `human`): `drive_auth_logout`, `drive_delete`, `drive_empty_trash`, `drive_share_invite`, `drive_share_revoke`, `drive_share_set_url`, `drive_share_remove_url`, `drive_share_remove_all`, `drive_share_leave`, `drive_invitation_accept`, `drive_invitation_reject`, `photos_delete_album`, `photos_remove_from_album`, applying `drive_bulk_move` or `drive_bulk_trash`, `drive_upload` with a `replace` strategy, `drive_download` / `photos_download` with a `remove` strategy, and `drive_write_file` over an existing file. Also gated: `drive_copy`, `drive_move`, `drive_mkdir`, `drive_rename`, `drive_upload`, `drive_write_file`, `drive_trash` and `drive_restore` when a path they read from or write to is under `/shared-with-me`, because that puts your data into, or changes, a folder someone else controls.
566
+
567
+ **What does not** (reversible changes inside your own `/my-files`): a single `drive_trash`, `drive_restore`, `drive_move` / `drive_rename` / `drive_copy` / `drive_mkdir` inside `/my-files`, an upload that does not replace anything, album create / update / add, `photos_upload`, and `drive_write_file` to a new file. A loop of single `drive_trash` calls is therefore not stopped in the default mode; use `strict` (below) if that matters to you.
568
+
569
+ **Two ways you approve**
570
+
571
+ 1. **A dialog in your client** (MCP elicitation). Shown for every gated call, whatever `confirmed` says. It counts as a yes only if you accept it with the approve box ticked; an explicit decline means no, and that is final. Only one dialog is open at a time: a gated call made while a dialog waits is turned away, not queued. If the dialog is closed without an answer (cancel), fails or times out after 120 s, nobody said no, so the call is refused with `approval_required` and a code (route 2 below) instead of a dead end; it still needs you at a terminal. After 5 declined or failed prompts within a minute the server stops asking for a while and refuses. If the dialog is closed or fails, an older terminal approval for the same operation is discarded, so the assistant cannot use it to answer that question. After an accepted or declined dialog, leftover records for the same operation are removed on a best-effort basis (a failed cleanup only warns).
572
+ 2. **A command in a terminal**, when the client cannot show the dialog. The call is refused with `approval_required` and a code such as `K7Q2-M9XD`. Run `proton-drive-cli approve K7Q2-M9XD` yourself in a terminal (without a global install: `npx -y -p proton-drive-mcp proton-drive-cli approve K7Q2-M9XD`): it shows the server's own record of the operation, and you type `yes`. Then ask the assistant to repeat the same call with the same arguments. The approval works once, for that exact operation, and lasts 5 minutes; a pending request expires after 10 minutes, and at most 20 are kept. `proton-drive-cli approvals` lists them and `proton-drive-cli deny <code>` discards one. `approve` refuses to run without an interactive terminal. The code only identifies the request; it is not a password and does not need to stay secret. Records live in a private folder (`0700`, files `0600`) next to the index folder, or in `PROTON_DRIVE_APPROVAL_DIR`; downloads cannot write into it, and the server refuses to use it inside `PROTON_DRIVE_SYNC_PATH` (it warns on stderr at startup, and the assistant is told the server is misconfigured). **The command must see the same folder as the server:** the same `PROTON_DRIVE_APPROVAL_DIR`, or the same `XDG_CACHE_HOME` / `HOME` when you did not set it. A Claude Desktop extension or a service started with a different environment writes its records somewhere your terminal does not look, and `approve` then reports an unknown code; set `PROTON_DRIVE_APPROVAL_DIR` to one absolute path in both places.
573
+
574
+ **What you will see.** Every line is written by the server from validated values, not by the assistant. For example:
575
+
576
+ ```
577
+ drive_share_invite: invite a person to a file or folder (affects other people or is visible outside your Drive)
578
+ path: /my-files/Taxes/2025
579
+ email: someone@example.org
580
+ role: editor
581
+ message: none
582
+ ```
583
+
584
+ Passwords and message texts are never shown, only whether a password is set and how many characters a message has. Read the paths and the effect before you approve. How each client displays a long message is not verified.
585
+
586
+ **Modes** (`PROTON_DRIVE_APPROVAL`, read once at startup):
587
+
588
+ | Value | Behaviour |
589
+ |---|---|
590
+ | unset or `human` | The gated set above needs a human yes. |
591
+ | `strict` | Every tool that changes Drive or the account needs a human yes, including single trash, restore, moves and uploads, and `drive_write_file` to a new file. |
592
+ | `model` | The 1.10.1 behaviour: `confirmed: true` from the assistant is enough. Only for people who knowingly want that, for example scheduled jobs with nobody present. A warning is written to stderr at startup. |
593
+ | anything else | Treated as `strict`, with a warning. |
594
+
595
+ `PROTON_DRIVE_MODE=readonly` and `PROTON_DRIVE_REMOTE_ROOTS` are checked first: you are never asked about a call that would be refused anyway. In unattended runs (no one can answer a dialog) gated calls are refused; set `model` only if you accept the risk, ideally together with `PROTON_DRIVE_REMOTE_ROOTS` and the audit log.
596
+
597
+ **What this does not cover.** The gate trusts your client's dialog and your own computer. It cannot stop a client that answers the dialog itself, an auto-answer you configure (for example a Claude Code `Elicitation` hook), anything that can write your files, or what you approve without reading. **If your client gives the assistant a shell** (Claude Code's Bash tool, a terminal MCP server and similar), the assistant can run the official `proton-drive` CLI directly, and nothing in this server can prevent that. Deny it in the client. For Claude Code, an example for `.claude/settings.json` (check the rule syntax and the result with `/permissions` for your version; this is a pattern match, not a complete barrier):
598
+
599
+ ```json
600
+ {
601
+ "permissions": {
602
+ "deny": ["Bash(proton-drive *)", "Bash(*/proton-drive *)", "Bash(*proton-drive-cli approve*)", "Bash(*proton-drive-cli*approve*)"]
603
+ }
604
+ }
605
+ ```
606
+
607
+ The two `approve` rules matter too: `proton-drive-cli approve` asks for an interactive terminal, but an assistant with a shell could run it under a fake terminal (for example through a pseudo-terminal wrapper) and type `yes` itself. Denying the command in the client is what keeps the terminal route a human step.
608
+
609
+ Also not covered: copying files into a folder under `/my-files` that is already shared or has a public link (use `PROTON_DRIVE_REMOTE_ROOTS`), and the terminal route on Windows, which is untested (the approvals folder assumes POSIX file renames). Details: [THREAT_MODEL.md](THREAT_MODEL.md).
610
+
551
611
  ### Guard layer (opt-in)
552
612
 
553
613
  Four environment variables limit what a model (or a prompt-injected one) can do with your Drive. All are read once at startup and are off by default. They apply to the MCP server only: the companion CLI (`proton-drive-cli`) is a tool you run yourself and is not restricted by them.
554
614
 
555
- - **`PROTON_DRIVE_MODE=readonly`** hides every tool that changes Drive or the account from `tools/list` and refuses it at call time (no CLI command runs). Hidden: `drive_upload`, `drive_mkdir`, `drive_rename`, `drive_move`, `drive_copy`, `drive_trash`, `drive_restore`, `drive_delete`, `drive_empty_trash`, `drive_bulk_move`, `drive_bulk_trash`, `drive_write_file`, `drive_auth_logout`, every `drive_share_*` that changes sharing (`invite`, `revoke`, `set_url`, `remove_url`, `remove_all`, `leave`), `drive_invitation_accept`/`reject`, and `photos_create_album`, `photos_update_album`, `photos_delete_album`, `photos_add_to_album`, `photos_remove_from_album`, `photos_upload`. Reads, analytics and downloads to local disk stay. An invalid value is treated as `readonly`. Prompts that name a hidden tool are not offered.
615
+ - **`PROTON_DRIVE_MODE=readonly`** hides every tool that changes Drive or the account from `tools/list` and refuses it at call time (no CLI command runs). Hidden: `drive_upload`, `drive_mkdir`, `drive_rename`, `drive_move`, `drive_copy`, `drive_trash`, `drive_restore`, `drive_delete`, `drive_empty_trash`, `drive_bulk_move`, `drive_bulk_trash`, `drive_write_file`, `drive_auth_logout`, every `drive_share_*` that changes sharing (`invite`, `revoke`, `set_url`, `remove_url`, `remove_all`, `leave`), `drive_invitation_accept`/`reject`, and `photos_create_album`, `photos_update_album`, `photos_delete_album`, `photos_add_to_album`, `photos_remove_from_album`, `photos_upload`. Reads, analytics and downloads to local disk stay, except that the `remove` conflict strategies of `drive_download` and `photos_download` (they delete existing local files) are refused. An invalid value is treated as `readonly`. Prompts that name a hidden tool are not offered.
556
616
  - **`PROTON_DRIVE_REMOTE_ROOTS`** (list separated by `:` on macOS/Linux, `;` on Windows, e.g. `/my-files/Projects/X`) confines every Drive path argument to those folders. Paths are matched by whole segment and case-sensitively (`/my-files/AB` is not inside `/my-files/A`); `..` and empty (`//`) segments are refused. Paths include sources, destinations, bulk lists, walk roots (`drive_tree`, `drive_search`, `drive_usage`, `drive_find_duplicates`, `drive_sharing_audit`, `drive_share_expiry_report`, `drive_recent_changes`, `drive_refresh_index`, `drive_sync_plan`, and the optional `path` of `drive_content_index` and `drive_search_content`, whose results outside the roots are dropped; their default `/my-files` is refused, so pass a `path`) and the sync-file tools. The root folder itself cannot be renamed, moved, trashed or left (`drive_share_leave`). `drive_usage` leaves out the account-wide trash summary. An entry that is not a clean absolute path is dropped with a warning; if none is left everything is refused. **These tools cannot be limited to a folder and are refused while roots are set:** `drive_auth_logout`, `drive_delete`, `drive_restore`, `drive_empty_trash`, `drive_list_trash` (trash is account-wide and addressed by name or UID), `drive_audit_log`, `drive_list_invitations`, `drive_invitation_accept`, `drive_invitation_reject`, and all ten `photos_*` tools. `drive_audit_log` is refused too, because its entries name paths outside the roots (read the file directly). `drive_auth_status` and `drive_version` touch no Drive content and keep working.
557
- - **`PROTON_DRIVE_AUDIT_LOG=/absolute/path/audit.jsonl`** appends one JSON line per tool call, refused calls included: `ts`, `seq`, `tool`, redacted `args`, `outcome` (`ok`, `error` or `refused`), a short `code` (`roots`, `readonly`, `tier`, `confirm`, `audit`, `snapshot`, `invalid`, `cli_error`, ...), `durationMs`, and `prev`/`hash`, a SHA-256 chain over the previous hash and the record. The file is created `0600` (its folder `0700` if missing). Passwords and message bodies are never written; for `drive_write_file` only the byte length of the content is, and arguments a tool does not declare are recorded as present, never by value. If the log cannot be written, tools that change Drive are refused (reads continue, with a warning on stderr). `drive_audit_log` returns the newest entries (default 50, full tier only, not available while roots are set) and `verification`: `{ok: true, entries, head}` or the first broken `seq`. The chain detects edited, inserted, reordered and mid-file removed lines, not removal of the newest lines: keep `head` somewhere else if you need that. Several servers can share one file (appends are serialized with a `<log>.lock` file; if it cannot be taken within a few seconds the write counts as failed). The server refuses to start when the log lies inside `PROTON_DRIVE_SYNC_PATH`. **An entry is written after the call finishes, so a crash or kill in the middle of an operation can leave a change that was never recorded.** The hash chain is only as trustworthy as the account that can write the file.
617
+ - **`PROTON_DRIVE_AUDIT_LOG=/absolute/path/audit.jsonl`** appends one JSON line per tool call, refused calls included: `ts`, `seq`, `tool`, redacted `args`, `outcome` (`ok`, `error` or `refused`), a short `code` (`roots`, `readonly`, `tier`, `confirm`, `approval_required`, `approval_declined`, `approval_unavailable`, `approval_changed`, `audit`, `snapshot`, `invalid`, `cli_error`, ...), for approved calls an `approval` field (`channel`: `elicitation`, `cli` or `model`, a short operation hash, and the code for `cli`), `durationMs`, and `prev`/`hash`, a SHA-256 chain over the previous hash and the record. The file is created `0600` (its folder `0700` if missing). Passwords and message bodies are never written; for `drive_write_file` only the byte length of the content is, and arguments a tool does not declare are recorded as present, never by value. If the log cannot be written, tools that change Drive are refused (reads continue, with a warning on stderr). `drive_audit_log` returns the newest entries (default 50, full tier only, not available while roots are set) and `verification`: `{ok: true, entries, head}` or the first broken `seq`. The chain detects edited, inserted, reordered and mid-file removed lines, not removal of the newest lines: keep `head` somewhere else if you need that. Several servers can share one file (appends are serialized with a `<log>.lock` file; if it cannot be taken within a few seconds the write counts as failed). The server refuses to start when the log lies inside `PROTON_DRIVE_SYNC_PATH`. **An entry is written after the call finishes, so a crash or kill in the middle of an operation can leave a change that was never recorded.** The hash chain is only as trustworthy as the account that can write the file.
558
618
  - **`PROTON_DRIVE_SNAPSHOT_BEFORE_OVERWRITE=1`** keeps the previous version before an overwrite (the result carries `snapshot`), as `<same folder>/.versions/<name>.<UTC timestamp>`. `drive_write_file` overwrites the local sync copy, so it copies the existing **local** file inside the sync folder (the sync client uploads the copy; unsynced local edits and files never uploaded are preserved). `drive_upload` with `fileConflictStrategy: replace` copies the existing **remote** file. If the copy fails, or the remote state cannot be determined (for example the CLI is missing), the overwrite is refused. Replacing a folder is not versioned and is refused too: `drive_upload` of a folder with a `replace` strategy, or onto a remote folder, while snapshots are on. A file that does not exist yet has nothing to preserve. Snapshots are never pruned.
559
619
 
560
620
  ### Reading file contents
@@ -682,6 +742,8 @@ Every tool group was live-tested on 2026-09-28 against a real Proton account, **
682
742
  | `PROTON_DRIVE_MODE` | Optional | `full` (default) or `readonly`: hide and refuse every tool that changes Drive or the account. An unknown value is treated as `readonly`, with a warning. See [Guard layer](#guard-layer-opt-in). |
683
743
  | `PROTON_DRIVE_REMOTE_ROOTS` | Optional | Drive folders (separated by `:`, or `;` on Windows) that every remote path argument must stay inside, e.g. `/my-files/Projects/X`. Tools that cannot be limited to a folder are refused while it is set. See [Guard layer](#guard-layer-opt-in). |
684
744
  | `PROTON_DRIVE_AUDIT_LOG` | Optional | Absolute path of an append-only, hash-chained JSONL audit log (`0600`). If it cannot be written, tools that change Drive are refused. Read it with `drive_audit_log`. See [Guard layer](#guard-layer-opt-in). |
745
+ | `PROTON_DRIVE_APPROVAL` | Optional | `human` (default), `strict` or `model`: who may approve destructive and outward-facing operations. `strict` gates every tool that changes Drive; `model` restores the 1.10.1 behaviour where the assistant's `confirmed: true` is enough (warning at startup). An unknown value is treated as `strict`, with a warning. See [Human approval](#human-approval-on-by-default). |
746
+ | `PROTON_DRIVE_APPROVAL_DIR` | Optional | Folder for terminal approvals (default: `approvals` next to the index folder, `~/Library/Caches/proton-drive-mcp/approvals` on macOS, `$XDG_CACHE_HOME` or `~/.cache` elsewhere). Created `0700`; the server refuses to use it inside `PROTON_DRIVE_SYNC_PATH`, and downloads cannot write into it. |
685
747
  | `PROTON_DRIVE_SNAPSHOT_BEFORE_OVERWRITE` | Optional | `1` to copy the existing file to `.versions/<name>.<timestamp>` in its folder before `drive_write_file` (local sync copy) or `drive_upload` (`replace`, remote copy) overwrites it; the overwrite is refused if the copy fails. Replacing a folder is refused. Off by default. See [Guard layer](#guard-layer-opt-in). |
686
748
 
687
749
  ---
package/dist/cli.js CHANGED
@@ -18,10 +18,14 @@ import { indexStatus, deleteIndex } from "./services/walkIndex.js";
18
18
  import { deleteChangeSnapshots } from "./services/changes.js";
19
19
  import { clearContentIndex } from "./services/contentIndex.js";
20
20
  import { resolve } from "node:path";
21
+ import { realpathSync } from "node:fs";
22
+ import { fileURLToPath } from "node:url";
23
+ import { createInterface } from "node:readline";
24
+ import { createApprovalStore, resolveApprovalDir } from "./utils/approvalStore.js";
21
25
  import { driveSearch, driveTree } from "./services/find.js";
22
26
  import { readDriveContent } from "./services/content.js";
23
27
  import { driveUsage, driveFindDuplicates, driveSharingAudit } from "./services/analytics.js";
24
- import { validateRemotePath, validateRemotePathList, validateLocalPath, validateEmail, validateMessage, validateName, validateFlagValue } from "./utils/validation.js";
28
+ import { validateRemotePath, validateRemotePathList, validateLocalPath, validateDownloadTarget, validateEmail, validateMessage, validateName, validateFlagValue } from "./utils/validation.js";
25
29
  const drive = new DriveService();
26
30
  const args = process.argv.slice(2);
27
31
  const jsonMode = args.includes("--json");
@@ -90,6 +94,11 @@ Commands:
90
94
  index status Persistent walk index (PROTON_DRIVE_INDEX=1): enabled?, path, size, age, entries
91
95
  index clear Delete the saved index file (plaintext names/paths of your drive), the change snapshots and the encrypted content index
92
96
 
97
+ approvals List pending/approved out-of-band approvals (code, tool, status, expires in, first summary line)
98
+ approve <code> Show the server's stored summary of a refused operation and approve it after you type 'yes'
99
+ (needs an interactive terminal)
100
+ deny <code> Discard a pending or approved approval
101
+
93
102
  doctor [--config <path>] Read-only diagnostics: Node, proton-drive CLI, auth, sync path, Claude Desktop config
94
103
  (exit 1 if any check fails)
95
104
  init [--config <path>] [--write] First-run helper (also: npx -y proton-drive-mcp init): runs the doctor checks, prints the Claude
@@ -166,6 +175,74 @@ function numFlags(...names) {
166
175
  function print(data) {
167
176
  console.log(jsonMode ? JSON.stringify(data) : JSON.stringify(data, null, 2));
168
177
  }
178
+ /** Interactive approval: returns the process exit code. Approves only after a typed `yes` on a real terminal. */
179
+ export async function approveInteractive(store, codeIn, io) {
180
+ if (!codeIn) {
181
+ io.stderr.write("Usage: approve <code>\n");
182
+ return 1;
183
+ }
184
+ if (!io.isTTY) {
185
+ io.stderr.write("Refusing to approve: this command needs an interactive terminal (stdin and stdout must be a TTY). Run it yourself in a terminal; nothing was approved.\n");
186
+ return 1;
187
+ }
188
+ let rec;
189
+ try {
190
+ rec = store.get(codeIn);
191
+ }
192
+ catch (e) {
193
+ io.stderr.write(`${e instanceof Error ? e.message : String(e)}\n`);
194
+ return 1;
195
+ }
196
+ if (!rec) {
197
+ io.stderr.write(`No approval ${codeIn.trim().toUpperCase()}: unknown, expired, denied or already used.\n`);
198
+ return 1;
199
+ }
200
+ if (rec.status !== "pending") {
201
+ io.stderr.write(`Approval ${rec.code} is already approved; the next identical call can use it.\n`);
202
+ return 1;
203
+ }
204
+ io.stdout.write(`\nApproval ${rec.code} for ${rec.tool}\n\n${rec.summary}\n\n`);
205
+ io.stdout.write("Type 'yes' to approve this operation (anything else aborts): ");
206
+ const rl = createInterface({ input: io.stdin });
207
+ const answer = await new Promise((res) => {
208
+ rl.once("line", (l) => res(l));
209
+ rl.once("close", () => res(""));
210
+ });
211
+ rl.close();
212
+ if (answer.trim() !== "yes") {
213
+ io.stdout.write("\nAborted. Nothing was approved.\n");
214
+ return 1;
215
+ }
216
+ try {
217
+ const done = store.approve(rec.code);
218
+ io.stdout.write(`\nApproved ${done.code}. It is valid for ${Math.max(1, Math.round((done.expiresAt - Date.now()) / 60000))} minutes; ask the assistant to call again with the same arguments.\n`);
219
+ return 0;
220
+ }
221
+ catch (e) {
222
+ io.stderr.write(`${e instanceof Error ? e.message : String(e)}\n`);
223
+ return 1;
224
+ }
225
+ }
226
+ function listApprovals(store) {
227
+ const now = Date.now();
228
+ const rows = store.list().map((r) => ({
229
+ code: r.code,
230
+ tool: r.tool,
231
+ status: r.status,
232
+ expiresInSeconds: Math.max(0, Math.round((r.expiresAt - now) / 1000)),
233
+ summary: r.summary.split("\n")[0] ?? "",
234
+ }));
235
+ if (jsonMode) {
236
+ console.log(JSON.stringify(rows));
237
+ return;
238
+ }
239
+ if (rows.length === 0) {
240
+ console.log("No pending approvals.");
241
+ return;
242
+ }
243
+ for (const r of rows)
244
+ console.log(`${r.code} ${r.status.padEnd(8)} ${r.tool} expires in ${Math.floor(r.expiresInSeconds / 60)}m${String(r.expiresInSeconds % 60).padStart(2, "0")}s ${r.summary}`);
245
+ }
169
246
  function setupClaudeDesktop() {
170
247
  const configPath = resolve(getFlag("--config") ?? defaultConfigPath());
171
248
  const rawSync = getFlag("--sync-path");
@@ -233,6 +310,31 @@ async function run() {
233
310
  }
234
311
  return;
235
312
  }
313
+ // Local files only: no account, no CLI binary needed.
314
+ if (cmd === "approvals" || cmd === "approve" || cmd === "deny") {
315
+ const store = createApprovalStore({ dir: resolveApprovalDir() });
316
+ if (cmd === "approvals")
317
+ listApprovals(store);
318
+ else if (cmd === "approve") {
319
+ process.exitCode = await approveInteractive(store, sub, {
320
+ stdin: process.stdin, stdout: process.stdout, stderr: process.stderr,
321
+ isTTY: Boolean(process.stdin.isTTY && process.stdout.isTTY),
322
+ });
323
+ }
324
+ else {
325
+ if (!sub) {
326
+ console.error("Usage: deny <code>");
327
+ process.exit(1);
328
+ }
329
+ if (store.deny(sub))
330
+ console.log(`Denied ${sub.trim().toUpperCase()}.`);
331
+ else {
332
+ console.error(`No approval ${sub.trim().toUpperCase()}: unknown or already used.`);
333
+ process.exit(1);
334
+ }
335
+ }
336
+ return;
337
+ }
236
338
  const cliCheck = await checkCliAvailable();
237
339
  if (!cliCheck.available) {
238
340
  const msg = cliCheck.reason === "not_executable"
@@ -290,7 +392,7 @@ async function run() {
290
392
  }
291
393
  let local;
292
394
  try {
293
- local = validateLocalPath(rawLocal, { scan: true });
395
+ local = validateLocalPath(rawLocal, { scan: true, upload: true });
294
396
  }
295
397
  catch (e) {
296
398
  console.error(e instanceof Error ? e.message : String(e));
@@ -325,7 +427,7 @@ async function run() {
325
427
  }
326
428
  let local;
327
429
  try {
328
- local = validateLocalPath(rawLocal2);
430
+ local = validateDownloadTarget(rawLocal2, [remote]);
329
431
  }
330
432
  catch (e) {
331
433
  console.error(e instanceof Error ? e.message : String(e));
@@ -728,7 +830,7 @@ async function run() {
728
830
  const photoPaths = positionals.slice(0, -1).map((p) => requirePath(p, "photo download <photo>... <local-folder>"));
729
831
  let localFolderValidated;
730
832
  try {
731
- localFolderValidated = validateLocalPath(localFolder);
833
+ localFolderValidated = validateDownloadTarget(localFolder, photoPaths);
732
834
  }
733
835
  catch (e) {
734
836
  console.error(e instanceof Error ? e.message : String(e));
@@ -754,7 +856,7 @@ async function run() {
754
856
  const localPaths = [];
755
857
  for (const p of positionals) {
756
858
  try {
757
- localPaths.push(validateLocalPath(p, { scan: true }));
859
+ localPaths.push(validateLocalPath(p, { scan: true, upload: true }));
758
860
  }
759
861
  catch (e) {
760
862
  console.error(e instanceof Error ? e.message : String(e));
@@ -780,23 +882,35 @@ async function run() {
780
882
  process.exit(1);
781
883
  }
782
884
  }
783
- run().catch((err) => {
784
- if (err instanceof DriveCliNotFoundError || err instanceof DriveNotAuthenticatedError) {
785
- console.error(err.message);
786
- }
787
- else if (err instanceof DriveCliError) {
788
- console.error(`CLI error: ${err.message}`);
789
- if (err.stderr)
790
- console.error(err.stderr);
791
- }
792
- else if (err instanceof DriveParseError) {
793
- console.error(`Parse error: ${err.message}`);
794
- }
795
- else if (err instanceof Error) {
796
- console.error(err.message);
885
+ /** True when started as a bin (cli.js directly, or index.js delegating `init`); false when a test imports the exports. */
886
+ function isEntryPoint() {
887
+ try {
888
+ const entry = realpathSync(process.argv[1]);
889
+ const self = realpathSync(fileURLToPath(import.meta.url));
890
+ return entry === self || entry === realpathSync(fileURLToPath(new URL("./index.js", import.meta.url)));
797
891
  }
798
- else {
799
- console.error("Error:", String(err));
892
+ catch {
893
+ return false;
800
894
  }
801
- process.exit(1);
802
- });
895
+ }
896
+ if (isEntryPoint())
897
+ run().catch((err) => {
898
+ if (err instanceof DriveCliNotFoundError || err instanceof DriveNotAuthenticatedError) {
899
+ console.error(err.message);
900
+ }
901
+ else if (err instanceof DriveCliError) {
902
+ console.error(`CLI error: ${err.message}`);
903
+ if (err.stderr)
904
+ console.error(err.stderr);
905
+ }
906
+ else if (err instanceof DriveParseError) {
907
+ console.error(`Parse error: ${err.message}`);
908
+ }
909
+ else if (err instanceof Error) {
910
+ console.error(err.message);
911
+ }
912
+ else {
913
+ console.error("Error:", String(err));
914
+ }
915
+ process.exit(1);
916
+ });