docs: tighten token permission guidance to least-privilege scopes

README.md

@@ -63,13 +63,17 @@ A single dashboard shows the state of every tracked file:
 
 | | Provider | Required info | Token scope |
 |:---:|---|---|---|
-| <img src="https://img.shields.io/badge/GitHub-181717?style=flat-square&logo=github&logoColor=white" alt="GitHub"> | **GitHub** | Personal access token, owner, repo name | `repo` |
-| <img src="https://img.shields.io/badge/GitLab-FC6D26?style=flat-square&logo=gitlab&logoColor=white" alt="GitLab"> | **GitLab** | Personal access token, project ID, base URL | `api` |
-| <img src="https://img.shields.io/badge/Gitea-609926?style=flat-square&logo=gitea&logoColor=white" alt="Gitea"> | **Gitea** | Personal access token, base URL, owner, repo name | (all) |
+| <img src="https://img.shields.io/badge/GitHub-181717?style=flat-square&logo=github&logoColor=white" alt="GitHub"> | **GitHub** | Personal access token, owner, repo name | `Contents: Read and write` (fine-grained); `repo` (classic) |
+| <img src="https://img.shields.io/badge/GitLab-FC6D26?style=flat-square&logo=gitlab&logoColor=white" alt="GitLab"> | **GitLab** | Personal access token, project ID, base URL | `read_repository`, `write_repository` |
+| <img src="https://img.shields.io/badge/Gitea-609926?style=flat-square&logo=gitea&logoColor=white" alt="Gitea"> | **Gitea** | Personal access token, base URL, owner, repo name | `write:repository` (1.19+); account-wide on older versions |
 
-- **GitHub token:** Settings → Developer settings → Personal access tokens → `repo` scope.
-- **GitLab token:** User settings → Access tokens → `api` scope. Base URL defaults to `https://gitlab.com`; change it for self-hosted instances.
-- **Gitea token:** User settings → Applications → Access tokens. Point the base URL at your instance (e.g. `https://gitea.example.com`).
+> **Security tip:** scope every token as narrowly as possible — one repo, the minimum permissions, and a short expiration — and store it only in this plugin's settings. Never paste it into a note that gets synced. Rotate it immediately if it's ever exposed, and revoke tokens you're no longer using.
+
+- **GitHub token:** create a [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) (Settings → Developer settings → Personal access tokens → Fine-grained tokens) rather than a classic one. Set **Repository access** to *Only select repositories* and pick just the repo you're syncing, set an **Expiration** (90 days or less), and grant only **Contents: Read and write**. If you must use a classic token, limit the `repo` scope to that one use and set an expiration.
+- **GitLab token:** prefer a [project access token](https://docs.gitlab.com/user/project/settings/project_access_tokens/) (Project → Settings → Access tokens) over a personal one — it's scoped to a single project and can be revoked without affecting your account. The plugin only calls the repository tree/blobs/commits/branches endpoints, so grant just `read_repository` and `write_repository` (**not** `api`, which also grants issues, merge requests, CI, and account-wide access). Role **Developer** is the minimum that can push to a non-protected branch. Set an expiration date, and base URL defaults to `https://gitlab.com`; change it for self-hosted instances.
+- **Gitea token:** User settings → Applications → Access tokens. The plugin only touches repository content, branches, and git data, so on Gitea 1.19+ (which supports per-scope tokens) select just **`write:repository`** — that implies read access too — instead of "Select all". Older Gitea versions (down to the 1.12 minimum) don't support scoped tokens, so the token is account-wide by default; in that case, use a dedicated bot/service account with access to only the target repo rather than your personal account's token. Set an expiration if your instance offers one, and point the base URL at your instance (e.g. `https://gitea.example.com`).
+
+All three providers let you revoke a token instantly from its settings page — do that first if a token may have leaked, then issue a new one.
 
 Other settings: **language** (system default, English, Traditional Chinese, or Simplified Chinese); **auto-refresh Sync Status on startup**; **branch** to sync against (default `main`); **root path** prefix inside the repo; **vault folder** to scope which notes are tracked; and **symbolic link handling** (*real* — recreate the link, GitHub only; *follow* — sync the target's content; *skip*). See [Symbolic link handling](docs/symlink-handling.md) for details.
 

USAGE_zh-cn.md

@@ -34,9 +34,14 @@ Git File Sync 不会同步整个 vault；您可以只选择要分享、发布或
 
 1. **选择服务**：在 `设置` > `Git File Sync` 中选择 GitLab、GitHub 或 Gitea。
 2. **填写凭据**：
-   - **GitHub**：需要个人访问令牌 (PAT)、用户名或组织名、仓库名。令牌需要 `repo` 权限。
-   - **GitLab**：需要个人访问令牌 (PAT)、项目 ID、服务器网址（默认为 `https://gitlab.com`；自建实例请改为对应网址）。令牌需要 `api` 权限。
-   - **Gitea**：需要个人访问令牌 (PAT)、服务器网址（例如 `https://gitea.example.com`）、用户名或组织名、仓库名。可在 `用户设置` > `应用程序` > `访问令牌` 中创建令牌。
+
+   > **安全提示：** 请把每个令牌的权限范围缩到最小：只允许需要同步的仓库、只授予必要权限，并设置较短的有效期。令牌只应保存在本插件的设置中，不要粘贴到会被同步的笔记里。如果令牌可能泄露，请立即撤销并重新创建；不再使用的令牌也应直接撤销。
+
+   - **GitHub**：建议创建 [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new)，而不是 classic token。在 **Repository access** 中选择 *Only select repositories*，只指定要同步的仓库；设置 **Expiration**（建议不超过 90 天），并只授予 **Contents: Read and write**。如果必须使用 classic token，则使用 `repo` scope，并为该用途设置到期时间。
+   - **GitLab**：建议优先使用 [project access token](https://docs.gitlab.com/user/project/settings/project_access_tokens/)（`Project` > `Settings` > `Access tokens`），而不是个人访问令牌，使权限限制在单个项目内，也可以独立撤销。插件只会调用 repository tree、blob、commit 和 branch 相关 API，因此只需要 `read_repository` 和 `write_repository`，**不需要** `api`。如需推送到非 protected branch，最低角色为 **Developer**。请设置到期时间；服务器网址默认为 `https://gitlab.com`，自建环境请改为您的实例网址。
+   - **Gitea**：在 `用户设置` > `应用程序` > `访问令牌` 中创建令牌。插件只会操作仓库内容、分支和 Git data；Gitea 1.19+ 支持 scoped token，请只选择 **`write:repository`**（已包含读取权限），不要选择全部权限。较旧版本（最低支持到 1.12）没有 scoped token，令牌默认是账号级别；这种情况下建议使用只拥有目标仓库权限的专用 bot / service account，而不是个人账号。若实例支持到期时间也请设置，并将服务器网址指向您的 Gitea 实例（例如 `https://gitea.example.com`）。
+
+   三种服务都可以从各自的设置页面立即撤销令牌。如果令牌可能泄露，请先撤销，再签发新的令牌。
 3. **仓库路径**：如需把笔记存放在仓库中的特定目录（例如 `notes/`），请设置 `Root Path`。
 4. **语言和自动刷新**：可以选择跟随系统、English、繁體中文或简体中文。“Obsidian 启动时自动刷新同步状态”默认开启，也可在设置中关闭。
 
@@ -104,5 +109,5 @@ Git File Sync 不会同步整个 vault；您可以只选择要分享、发布或
 
 ## 🔒 隐私与安全
 
-- 个人访问令牌只保存在本地 vault 的插件数据目录中，只会发送给您配置的 Git 服务。
+- 个人访问令牌只保存在本地 vault 的插件数据目录中，只会发送到您配置的 Git 服务。
 - 插件不收集使用数据或分析信息。

USAGE_zh.md

@@ -36,9 +36,14 @@
 
 1. **選擇服務**：在 `設定` > `Git File Sync` 中選擇 GitLab、GitHub 或 Gitea。
 2. **填寫憑證**：
-   - **GitHub**：需要 個人存取權杖 (PAT)、帳號名稱、儲存庫名稱。權杖需具備 `repo` 權限。
-   - **GitLab**：需要 個人存取權杖 (PAT)、專案 ID、伺服器網址（預設為 `https://gitlab.com`，自架請改為您的網址）。權杖需具備 `api` 權限。
-   - **Gitea**：需要 個人存取權杖 (PAT)、伺服器網址（例如 `https://gitea.example.com`）、帳號名稱、儲存庫名稱。權杖在 `使用者設定` > `應用程式` > `存取權杖` 中建立。
+
+   > **安全性提示：** 請將每個權杖的範圍縮到最小：只允許需要同步的儲存庫、只授予必要權限，並設定較短的有效期限。權杖只應儲存在此外掛的設定中，不要貼到會被同步的筆記。如果權杖可能外洩，請立即撤銷並重新建立；不再使用的權杖也應直接撤銷。
+
+   - **GitHub**：建議建立 [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new)，而不是 classic token。在 **Repository access** 選擇 *Only select repositories*，只指定要同步的儲存庫；設定 **Expiration**（建議 90 天以內），並只授予 **Contents: Read and write**。若必須使用 classic token，則使用 `repo` scope，並為此用途設定到期日。
+   - **GitLab**：建議優先使用 [project access token](https://docs.gitlab.com/user/project/settings/project_access_tokens/)（`Project` > `Settings` > `Access tokens`），而不是個人存取權杖，讓權限限制在單一專案，也能獨立撤銷。外掛只會呼叫 repository tree、blob、commit 與 branch 相關 API，因此只需要 `read_repository` 與 `write_repository`，**不需要** `api`。若要推送到非 protected branch，最低角色需為 **Developer**。請設定到期日；伺服器網址預設為 `https://gitlab.com`，自架環境請改成您的實例網址。
+   - **Gitea**：在 `使用者設定` > `應用程式` > `存取權杖` 建立權杖。外掛只會操作儲存庫內容、分支與 Git data；Gitea 1.19+ 支援 scoped token，請只選 **`write:repository`**（已包含讀取權限），不要選擇全部權限。較舊版本（最低支援至 1.12）沒有 scoped token，權杖預設為帳號層級；這種情況建議使用只具備目標儲存庫權限的專用 bot / service account，而不是個人帳號。若實例支援到期日也請設定，並將伺服器網址指向您的 Gitea 實例（例如 `https://gitea.example.com`）。
+
+   三種服務都可以從各自的設定頁立即撤銷權杖。如果權杖可能外洩，請先撤銷，再簽發新的權杖。
 3. **儲存庫路徑**：如果您想將筆記存放在儲存庫的特定資料夾（例如 `notes/`），請在 `Root Path` 中設定。
 4. **語言與自動重新整理**：可選擇跟隨系統、English、繁體中文或简体中文；「Obsidian 啟動時自動重新整理同步狀態」預設開啟，亦可在設定中關閉。
 
@@ -108,5 +113,5 @@
 
 ## 🔒 隱私與安全
 
-- 您的存取權杖 (Token) 僅會儲存在您本機的 Obsidian 資料夾內，不會傳送至任何第三方伺服器。
-- 本插件不會收集任何個人數據或使用紀錄。
+- 您的存取權杖 (Token) 僅會儲存在本機 vault 的外掛資料目錄中，只會傳送到您設定的 Git 服務。
+- 本外掛不會收集任何個人資料或使用紀錄。