proton-drive-mcp 1.5.3 → 1.6.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,24 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.6.0 — 2026-11-01
4
+
5
+ ### Added
6
+ - **Guard layer** (all opt-in, off by default; they apply to the MCP server only, so the companion `proton-drive-cli` bypasses them):
7
+ - `PROTON_DRIVE_MODE=readonly` hides and refuses every tool that changes Drive or the account (an invalid value fails closed to readonly). Every tool is classified as reading or mutating, and a test fails if a new tool is not.
8
+ - `PROTON_DRIVE_REMOTE_ROOTS` confines every Drive path argument to the listed folders; tools that cannot be limited to a folder (trash, invitations, photos, sign-out) are refused while it is set.
9
+ - `PROTON_DRIVE_AUDIT_LOG` appends a hash-chained JSON line per tool call, refused calls included, with passwords and file text redacted (only the byte length of written content is kept); appends from several server processes are serialized with a lock file, and the server refuses to start when the log lies inside `PROTON_DRIVE_SYNC_PATH`; if the log cannot be written, tools that change Drive are refused. New tool **`drive_audit_log`** returns the newest entries and checks the chain.
10
+ - `PROTON_DRIVE_SNAPSHOT_BEFORE_OVERWRITE=1` keeps the previous version as `.versions/<name>.<timestamp>` before an overwrite: `drive_write_file` copies the existing local sync file (inside the sync folder), `drive_upload` (`replace`) copies the remote file. The overwrite is refused if the copy fails, if the remote state cannot be determined (e.g. CLI missing), or when a folder would be replaced.
11
+ - **`drive_recent_changes`**: files added or modified since a date (`7d`, `12h`, `2w` or an ISO date). With `snapshot: "diff" | "save"` and `PROTON_DRIVE_INDEX=1` it compares against a saved per-path snapshot and reports added, removed, modified and moved files. An incomplete walk never overwrites a snapshot. `proton-drive-cli index clear` also removes the snapshot file.
12
+ - **`drive_share_expiry_report`**: public links with `expiresAt`, `daysLeft` and the flags `expired`, `expiringSoon`, `noExpiry`, `hasPassword`. Built on the sharing audit, so it keeps its limit of 100 shared items and reports `capped`.
13
+ - **`drive_read_many`**: reads the text of up to 10 files in one call, two at a time, with per-file and total character caps. One failing file does not fail the batch.
14
+
15
+ ### Changed
16
+ - `drive_share_set_url` now refuses, before changing anything, to replace a link whose password and/or expiration the call omits (set-url replaces all link settings), naming what would be lost. Pass them again, or pass the new `resetSettings: true` to drop them on purpose. It also refuses when the existing settings cannot be read. Previously this only produced a warning after the fact.
17
+
18
+ ### Notes
19
+ - Known limits: audit entries are written after the change; the audit-log lock can fork the chain only if a crashed holder and contention coincide; a contended append blocks the server for up to ~4 s; the local `.versions` copy has no size cap. The `drive_share_set_url` link check was confirmed against the live CLI (`urlAccess.customPassword`, `expirationTime`).
20
+ - The MCP server now lists 51 tools (47 in 1.5.3). The three new tools are MCP-only; the companion CLI still mirrors 45.
21
+
3
22
  ## 1.5.3 — 2026-10-31
4
23
 
5
24
  ### Security
package/README.md CHANGED
@@ -58,7 +58,7 @@ What to expect: search matches names, sizes and dates, not the text of every fil
58
58
 
59
59
  - **Claude manages your Proton Drive** — list, upload, download, move, share, trash, restore
60
60
  - **Proton Photos album management** — list albums, create/delete albums, add and remove photos
61
- - **Companion CLI** — 45 of the 47 operations, scriptable and pipeable, works in cron and shell scripts (the two sync-folder tools, `drive_read_file` and `drive_write_file`, are MCP-only)
61
+ - **Companion CLI** — 45 of the 51 operations, scriptable and pipeable, works in cron and shell scripts (the two sync-folder tools, `drive_read_file` and `drive_write_file`, `drive_audit_log` and the newer `drive_read_many`, `drive_share_expiry_report` and `drive_recent_changes` are MCP-only)
62
62
  - **Full Proton Drive CLI command coverage** — all 32 scriptable commands of CLI 0.8.0 have a matching tool (checked against the CLI's own help; `auth login` is the one command excluded, since it's an interactive browser flow). Not every optional flag is exposed: `sharing invite --include-node-name` is deliberately off (it would put the file name in the invitation email in clear text) and the `inherited` invite role is not offered; commands that accept several paths run one path per call except bulk move and bulk trash
63
63
  - **Zero credential exposure** — auth is handled entirely by the official Proton Drive CLI; this MCP never touches your password or session token
64
64
  - **Shell injection safe** — all CLI calls use `execFile` with discrete argument arrays, never string interpolation
@@ -277,7 +277,7 @@ proton-drive-cli index clear
277
277
  - 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`).
278
278
  - Walks skip `.git` and `node_modules` by default.
279
279
  - 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. Off by default, see [Persistent index](#persistent-index-opt-in).
280
- - Read-only tools (`drive_search`, `drive_tree`, `drive_usage`, `drive_find_duplicates`, `drive_sharing_audit`, `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`.
280
+ - 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`.
281
281
  - Duplicate detection uses the sha1 the uploader claimed, which is unverified. `verify: true` downloads the candidates and hashes them.
282
282
  - 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.
283
283
  - Sizes are sums of file sizes, not your account quota.
@@ -292,7 +292,8 @@ By default every new server process (each Claude Desktop session) walks the driv
292
292
  - **What is stored:** the node list of up to 8 recent complete walks under `/my-files` (partial or failed walks are never saved, so a `drive_tree` that stops at its depth limit is not stored), plus a fingerprint of your account's Drive root. No file contents, no credentials, no tokens.
293
293
  - **Where:** `PROTON_DRIVE_INDEX_DIR` if set; otherwise `~/Library/Caches/proton-drive-mcp` (macOS) or `$XDG_CACHE_HOME/proton-drive-mcp` / `~/.cache/proton-drive-mcp` (Linux). One file, `walk-index.json`, mode `0600` in a `0700` directory, written atomically. Use a dedicated directory: a pre-existing directory with group/other access (or owned by someone else) is refused with one warning and never chmodded; a missing one is created `0700`. A symlinked directory or file is refused. A saved file with loose permissions, another owner, a future timestamp, or above 200 MB is ignored. Not written above 200 MB.
294
294
  - **Account check:** before any saved data is served, one `list /my-files` (~2 s) confirms it belongs to the account that is logged in now; if the check fails (network, rate limit) nothing is served from disk for that call and the file is kept; a proven account mismatch deletes it. Either way the drive is walked fresh.
295
- - **Freshness:** data up to `PROTON_DRIVE_INDEX_MAX_AGE_H` hours old (default 24; `0` = never use saved data) is returned immediately with `stale: true` (and `refreshing: true` while one background walk replaces it); a repeated call then returns the fresh walk. A failed or incomplete background walk is not retried for 5 minutes within the same server process (`PROTON_DRIVE_INDEX_REFRESH_COOLDOWN_MS`); a new process tries once again. The saved data is account-checked first (see above). `drive_sync_plan`, `drive_find_duplicates` and the sharing audit never use saved data. `refresh: true` always does a blocking fresh walk. Writes made through this server drop the affected entries from memory and disk.
295
+ - **Freshness:** data up to `PROTON_DRIVE_INDEX_MAX_AGE_H` hours old (default 24; `0` = never use saved data) is returned immediately with `stale: true` (and `refreshing: true` while one background walk replaces it); a repeated call then returns the fresh walk. A failed or incomplete background walk is not retried for 5 minutes within the same server process (`PROTON_DRIVE_INDEX_REFRESH_COOLDOWN_MS`); a new process tries once again. The saved data is account-checked first (see above). `drive_sync_plan`, `drive_find_duplicates`, the sharing audit and `drive_recent_changes` never use saved data. `refresh: true` always does a blocking fresh walk. Writes made through this server drop the affected entries from memory and disk.
296
+ - **Change snapshots:** `drive_recent_changes` with `snapshot` stores a second plaintext file, `changes-snapshot.json`, in the same directory under the same rules (see [Recent changes](#recent-changes)); it is only written when you ask for `snapshot: "save"`, and `index clear` removes it as well.
296
297
  - **Read-only directory:** an index in a directory (or file) you cannot write to is ignored, because it could not be kept current after the server's own writes.
297
298
  - **Limits:** `drive_tree` with a depth limit is not answered from the saved full walk (it walks live); changes made by other clients or processes are not seen until the data is refreshed.
298
299
  - **Check or remove it:** `proton-drive-cli index status` and `proton-drive-cli index clear` (or just delete the file). In the MCPB bundle, the **Persistent search index** setting is the opt-in.
@@ -340,7 +341,7 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
340
341
  `drive_auth_status` · `drive_auth_logout` · `drive_version`
341
342
 
342
343
  ### Filesystem
343
- `drive_list` · `drive_info` · `drive_read_content` · `drive_tree` · `drive_search` · `drive_mkdir` · `drive_upload` · `drive_download` · `drive_rename` · `drive_move` · `drive_delete`
344
+ `drive_list` · `drive_info` · `drive_read_content` · `drive_read_many` · `drive_tree` · `drive_search` · `drive_mkdir` · `drive_upload` · `drive_download` · `drive_rename` · `drive_move` · `drive_delete`
344
345
 
345
346
  ### Sharing
346
347
  `drive_share_status` · `drive_share_invite` · `drive_share_revoke` · `drive_share_remove_all` · `drive_share_set_url` · `drive_share_remove_url`
@@ -361,7 +362,10 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
361
362
  `drive_list_invitations` · `drive_invitation_accept` · `drive_invitation_reject` · `drive_share_leave`
362
363
 
363
364
  ### Analytics
364
- `drive_usage` · `drive_find_duplicates` · `drive_sharing_audit`
365
+ `drive_usage` · `drive_find_duplicates` · `drive_sharing_audit` · `drive_share_expiry_report` · `drive_recent_changes`
366
+
367
+ ### Audit (see [Guard layer](#guard-layer-opt-in))
368
+ `drive_audit_log`
365
369
 
366
370
  ### Photos
367
371
  `photos_list_albums` · `photos_create_album` · `photos_update_album` · `photos_delete_album` · `photos_list_album_photos` · `photos_add_to_album` · `photos_remove_from_album` · `photos_list_timeline` · `photos_download` · `photos_upload`
@@ -378,6 +382,7 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
378
382
  | `drive_list` | List files and folders at a path (paginated, default 200; `/` lists the roots) | `path`, `limit?`, `offset?` |
379
383
  | `drive_info` | Get metadata for one file/folder, including revision details (noise trimmed) | `path`, `verbose?` (raw CLI node) |
380
384
  | `drive_read_content` | Read the text of a file stored in Drive (no sync folder needed): text/code, `.docx`, text-layer `.pdf`. Paged; content is untrusted data. See [Reading file contents](#reading-file-contents) | `path`, `maxChars?` (default 20000, max 100000), `offset?` |
385
+ | `drive_read_many` | Read the text of up to 10 Drive files in one call, two at a time; per-file and total character caps; one failing file does not fail the rest. Content is untrusted data. See [Reading file contents](#reading-file-contents) | `paths` (max 10), `maxCharsPerFile?` (default 4000, max 20000), `maxTotalChars?` (default 40000, max 100000) |
381
386
  | `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?` |
382
387
  | `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?` |
383
388
  | `drive_mkdir` | Create a new empty folder | `path` |
@@ -392,10 +397,13 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
392
397
  | `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?` |
393
398
  | `drive_find_duplicates` | Likely duplicate groups (claimed sha1 / same size; `verify` downloads and sha256s candidates), wasted bytes, suggested keeper — never deletes | `path?`, `minSize?`, `verify?`, `maxVerifyBytes?`, `maxVerifyTotalBytes?` (default 500 MB, max 2 GB), `limit?`, `refresh?` |
394
399
  | `drive_sharing_audit` | Public links (no URL), invitees, pending invitations and risk flags for shared items (max 100) | `path?`, `refresh?` |
400
+ | `drive_share_expiry_report` | Public links under a path with `expiresAt`, `daysLeft` and flags `expired`, `expiringSoon`, `noExpiry`, `hasPassword`, soonest first. Uses the sharing audit walk (max 100 shared items; `capped` says when more exist). Lists only links set directly on items below `path`: a link on the folder passed as `path` itself is not listed, so pass its parent. Changes nothing | `path?`, `withinDays?` (default 14), `refresh?` |
401
+ | `drive_recent_changes` | Files added or modified since a date (`since`: ISO date or `7d`/`12h`/`2w`, default 7d), from one complete walk. With `snapshot: "diff"` or `"save"` (needs `PROTON_DRIVE_INDEX=1`): added, removed, modified and moved files against the previous snapshot of that path. See [Recent changes](#recent-changes) | `path?`, `since?`, `limit?` (default 50, max 500), `snapshot?`, `refresh?` |
402
+ | `drive_audit_log` | Newest audit-log entries plus a hash-chain check (needs `PROTON_DRIVE_AUDIT_LOG`; works in readonly mode) | `limit?` (default 50) |
395
403
  | `drive_share_invite` | Invite a user (sends an email) ⚠️ | `path`, `email`, `role` (viewer/editor/admin), `message?`, `confirmed: true` |
396
404
  | `drive_share_revoke` | Revoke one person's access (fails if not a member) ⚠️ | `path`, `email`, `confirmed: true` |
397
405
  | `drive_share_remove_all` | Remove every member + pending invitation at once ⚠️ | `path`, `confirmed: true` |
398
- | `drive_share_set_url` | Create/replace a public share link ⚠️ (re-running without `password`/`expiration` removes them; expiry max ~90 days) | `path`, `role?` (viewer/editor), `password?`, `expiration?`, `confirmed: true` |
406
+ | `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` |
399
407
  | `drive_share_remove_url` | Remove the public share link ⚠️ | `path`, `confirmed: true` |
400
408
  | `drive_trash` | Move to trash | `path` |
401
409
  | `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?` |
@@ -453,12 +461,21 @@ The server offers four MCP prompts (also declared in the MCPB manifest): `organi
453
461
 
454
462
  ### Token cost
455
463
 
456
- `tools/list` is sent to the model in every session. Measured payload (JSON bytes): `full` 40.1 KB (47 tools), `core` 17.9 KB (19 tools). Set `PROTON_DRIVE_TOOL_TIER=core` to load only:
464
+ `tools/list` is sent to the model in every session. Measured payload (JSON bytes): `full` 44.4 KB (51 tools), `core` 17.9 KB (19 tools). Set `PROTON_DRIVE_TOOL_TIER=core` to load only:
457
465
 
458
466
  `drive_auth_status`, `drive_version`, `drive_list`, `drive_info`, `drive_read_content`, `drive_list_trash`, `drive_search`, `drive_tree`, `drive_mkdir`, `drive_upload`, `drive_download`, `drive_rename`, `drive_move`, `drive_copy`, `drive_trash`, `drive_restore`, `drive_share_status`, `photos_list_timeline`, `photos_download`.
459
467
 
460
468
  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.
461
469
 
470
+ ### Guard layer (opt-in)
471
+
472
+ 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.
473
+
474
+ - **`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.
475
+ - **`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_sync_plan`; 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.
476
+ - **`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.
477
+ - **`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.
478
+
462
479
  ### Reading file contents
463
480
 
464
481
  `drive_read_content` returns the text of a file stored in Drive, without a sync folder: it downloads the file into a private temp directory (mode 0700, always removed afterwards), extracts the text and returns it in pages (`offset` / `maxChars`, default 20000, max 100000 characters; the reply carries `nextOffset` while more remains). Expect 2-4 s per read.
@@ -469,6 +486,15 @@ Left out of `core` (use `full`): permanent deletion (`drive_delete`, `drive_empt
469
486
  - **Untrusted content:** file text comes from your drive and may contain instructions aimed at the model (prompt injection). The tool returns it as data, nothing is executed, and its description tells the model to treat it as data, never as instructions.
470
487
  - **Optional packages:** `.docx` needs `fflate` and `.pdf` needs `unpdf`; both are optional dependencies of this package, installed by default (and included in the MCPB bundle). If they were omitted (`npm install --omit=optional`), PDF/DOCX reading returns a clear error naming the package to install (`npm install fflate unpdf`); text formats work without them. The test suite skips the PDF/DOCX groups with a reason when the packages are missing (never on CI, where they fail instead).
471
488
 
489
+ `drive_read_many` takes up to 10 paths and applies the same rules to each file (formats, size cap, isolated parsing, untrusted content). Files are read two at a time, because the CLI fails with "database is locked" under heavier parallelism. Each result is `{path, ok, text?, truncated?, nextOffset?, error?}`, so one unreadable file does not fail the others. Text is capped per file (`maxCharsPerFile`, default 4000, max 20000) and over the whole call (`maxTotalChars`, default 40000); once the total is used up, remaining files report `skipped`. Continue a truncated file with `drive_read_content` and `offset = nextOffset`. With `PROTON_DRIVE_REMOTE_ROOTS` set, every path must be inside a root or the whole call is refused.
490
+
491
+ ### Recent changes
492
+
493
+ `drive_recent_changes` answers "what changed in this folder?" in two ways.
494
+
495
+ - **Since a date** (default): files whose original modification time or upload time is at or after `since` (an ISO date, or a relative age such as `7d`, `12h`, `2w`; default `7d`), newest first, from one complete walk that never reads the saved index. It cannot tell "added" from "modified" and sees only what the walk data shows: a file changed in place with an old claimed modification time and no re-upload is missed.
496
+ - **Against a snapshot** (`snapshot: "diff"` or `"save"`): only with `PROTON_DRIVE_INDEX=1`, because it keeps a plaintext list of file paths, sizes, modification times and claimed sha1 hashes (the same privacy trade-off as the [persistent index](#persistent-index-opt-in)); otherwise the call returns an error saying so. The list is stored per walked path in `changes-snapshot.json` next to `walk-index.json` (same private `0700` directory, `0600` file, atomic write, tied to the account fingerprint, not written above 50 MB, up to 8 paths kept; `proton-drive-cli index clear` removes it too). `diff` compares the current drive with the previous snapshot of that path and reports `added`, `removed`, `modified` and `moved` (a removed and an added file with the same size and the same non-empty claimed sha1; files without a sha1 show up as removed plus added). `save` does the same comparison and then stores the current state as the new baseline. If the walk was incomplete, nothing is saved (a partial list would later look like mass deletions) and `removed`/`moved` are left out of the answer.
497
+
472
498
  ## Known limitations
473
499
 
474
500
  These come from the upstream `proton-drive` CLI (v0.8.0), not from this server:
@@ -524,7 +550,11 @@ Every tool group was live-tested on 2026-09-28 against a real Proton account, **
524
550
  | `PROTON_DRIVE_INDEX_MAX_AGE_H` | Optional | Oldest saved index data that may be served, in hours (default 24; 0 = never serve saved data). Served data is marked `stale: true` and refreshed in the background (`drive_sync_plan`, `drive_find_duplicates` and the sharing audit never use it). |
525
551
  | `PROTON_DRIVE_READ_MAX_BYTES` | Optional | Largest file `drive_read_content` will download, in bytes (default 10485760 = 10 MB; values above 52428800 = 50 MB are clamped). Larger files are refused before any download. |
526
552
  | `PROTON_DRIVE_READ_TIMEOUT_MS` | Optional | Hard time limit for parsing one `.pdf`/`.docx` in `drive_read_content`, in milliseconds (default 20000; clamped to 1-120000). On expiry the parsing worker is terminated and the call returns an error. |
527
- | `PROTON_DRIVE_TOOL_TIER` | Optional | `full` (default, all 47 tools) or `core` (19 everyday tools; see [Token cost](#token-cost)). Tools outside the active tier are hidden from `tools/list` and refused at call time. Read once at startup; an unknown value falls back to `full` with a warning on stderr. |
553
+ | `PROTON_DRIVE_TOOL_TIER` | Optional | `full` (default, all 51 tools) or `core` (19 everyday tools; see [Token cost](#token-cost)). Tools outside the active tier are hidden from `tools/list` and refused at call time. Read once at startup; an unknown value falls back to `full` with a warning on stderr. |
554
+ | `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). |
555
+ | `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). |
556
+ | `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). |
557
+ | `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). |
528
558
 
529
559
  ---
530
560
 
package/dist/cli.js CHANGED
@@ -14,6 +14,7 @@ import { buildEntry, defaultConfigPath, isDirectory, resolveDriveCli, writeEntry
14
14
  import { syncPlan, planBulkMove, planBulkTrash, loadListing, foldersToList } from "./services/plan.js";
15
15
  import { invalidatePath } from "./services/walk.js";
16
16
  import { indexStatus, deleteIndex } from "./services/walkIndex.js";
17
+ import { deleteChangeSnapshots } from "./services/changes.js";
17
18
  import { resolve } from "node:path";
18
19
  import { driveSearch, driveTree } from "./services/find.js";
19
20
  import { readDriveContent } from "./services/content.js";
@@ -212,7 +213,7 @@ async function run() {
212
213
  if (sub === "status")
213
214
  print(indexStatus());
214
215
  else if (sub === "clear")
215
- print(deleteIndex());
216
+ print({ ...deleteIndex(), changeSnapshotsDeleted: deleteChangeSnapshots() });
216
217
  else {
217
218
  console.error("Usage: index status|clear");
218
219
  process.exit(1);