> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth Access Tokens 集合

`oauthAccessTokens` 儲存 web 接受的 bearer 權杖。在 Ayakaleaf Pro 中，這些是使用者在帳戶設定頁面建立、用於 git-bridge 與 MCP 端點的個人存取權杖（Git 驗證權杖）。一份文件對應一個權杖。Schema 位於 `services/web/app/src/models/OauthAccessToken.mjs`；web 模組 `oauth2-server` 寫入該集合，大多透過原生驅動程式。

#### 欄位

| 欄位 | 型別 | 含義 | 來源 |
| - | - | - | - |
| `_id` | ObjectId | 權杖文件 id。設定頁面依此 id 刪除權杖。 | `OauthAccessToken.mjs:6` |
| `accessToken` | String | 權杖的 SHA-256 十六進位摘要。明文權杖為 `olp_` 加 36 個隨機字母與數字，僅在建立時顯示一次，從不儲存。 | `OauthAccessToken.mjs:8`, `services/web/modules/oauth2-server/app/src/OAuthPersonalAccessTokenManager.mjs:54,72`, `services/web/modules/oauth2-server/app/src/SecretsHelper.mjs:6-11` |
| `accessTokenPartial` | String | 明文權杖的前 8 個字元，顯示在權杖清單中。 | `OauthAccessToken.mjs:9`, `OAuthPersonalAccessTokenManager.mjs:73` |
| `type` | String | 在設定頁面建立的每個權杖都為 `personal_access_token`。清單、計數與刪除查詢都依它篩選。 | `OauthAccessToken.mjs:10`, `OAuthPersonalAccessTokenManager.mjs:75` |
| `accessTokenExpiresAt` | Date | 建立後一年。此後兩種權杖驗證都會拒絕該權杖，TTL 索引會在一天後將其刪除。 | `OauthAccessToken.mjs:11`, `OAuthPersonalAccessTokenManager.mjs:65-68,77` |
| `oauthApplication_id` | ObjectId | [OAuth Applications](https://ayakaleaf-pro.mintlify.site/zh-TW/dev/data-model/oauth-applications-collection.md) 中 `Overleaf Git Bridge` 用戶端的 `_id`。 | `OauthAccessToken.mjs:12`, `OAuthPersonalAccessTokenManager.mjs:55-56,74` |
| `scope` | String | 以空格分隔的 scope。個人存取權杖獲得 `git_bridge`，即 git-bridge 與 MCP 路由所要求的 scope。 | `OauthAccessToken.mjs:15`, `OAuthPersonalAccessTokenManager.mjs:76` |
| `user_id` | String (ObjectId in the schema) | 權杖擁有者。`createToken` 透過原生驅動程式按原樣以字串儲存工作階段中的使用者 id；管理面板也以字串查詢它（`services/web/modules/admin-tools/app/src/AdminUserListManager.mjs:391-392`）。 | `OauthAccessToken.mjs:16`, `services/web/modules/oauth2-server/app/src/OAuthPersonalAccessTokenController.mjs:29-41`, `OAuthPersonalAccessTokenManager.mjs:78,83-85` |
| `createdAt` | Date | 建立時間。權杖清單依它排序，最新的在前。 | `OauthAccessToken.mjs:17`, `OAuthPersonalAccessTokenManager.mjs:21-22,64,79` |
| `lastUsedAt` | Date | 權杖最近一次通過驗證的時間。兩種權杖驗證都會設定它。 | `OauthAccessToken.mjs:19`, `services/web/modules/oauth2-server/app/src/OAuth2Model.mjs:58-61`, `OAuthPersonalAccessTokenManager.mjs:136-140` |
| `refreshToken`, `refreshTokenExpiresAt` | String, Date | 只有 `saveToken` 會寫入它們（重新整理權杖經過雜湊），而沒有任何程式碼呼叫 `saveToken`，見 [OAuth Applications](https://ayakaleaf-pro.mintlify.site/zh-TW/dev/data-model/oauth-applications-collection.md)。 | `OauthAccessToken.mjs:13-14`, `OAuth2Model.mjs:249-252` |
| `expiresAt` | Date | 僅存在於 schema 中：本儲存庫沒有程式碼寫入它。有一個 TTL 索引涵蓋它。 | `OauthAccessToken.mjs:18` |
| `lastNotifiedAt.warning`, `lastNotifiedAt.expired`, `notificationsSuppressedAt` | Date | 僅存在於 schema 中：本儲存庫沒有程式碼讀取或寫入它們。 | `OauthAccessToken.mjs:20-27` |

#### 寫入方

| 程式碼 | 作用 |
| - | - |
| `OAuthPersonalAccessTokenManager.mjs:53-88` (`createToken`) | 插入個人存取權杖。路由 `POST /oauth/personal-access-tokens`（`services/web/modules/oauth2-server/app/src/OAuthPersonalAccessTokenRouter.mjs:22-27`）要求使用者具備 `gitBridge` 功能，且每位使用者最多 10 個權杖（`OAuthPersonalAccessTokenController.mjs:7,34-38`）。 |
| `OAuthPersonalAccessTokenManager.mjs:90-105` (`removeToken`) | 刪除使用者的一個權杖。路由 `DELETE /oauth/personal-access-tokens/:token_id`（`OAuthPersonalAccessTokenRouter.mjs:29-32`）。 |
| `OAuthPersonalAccessTokenManager.mjs:136-140`, `OAuth2Model.mjs:58-61` | 驗證成功後設定 `lastUsedAt`。 |

#### 讀取方

| 程式碼 | 作用 |
| - | - |
| `OAuthPersonalAccessTokenManager.mjs:107-144` (`verifyToken`) | 為 `GET /oauth/token/info`（`OAuthPersonalAccessTokenRouter.mjs:11-15`）依雜湊驗證權杖，git-bridge 在 git clone 與 push 時呼叫它（`services/git-bridge/src/main/java/uk/ac/ic/wlgitbridge/server/Oauth2Filter.java:285`）。拒絕已過期的權杖以及被停權或已刪除使用者的權杖。 |
| `OAuth2Model.mjs:31-82` (`getAccessToken`) | 為 `AuthenticationController.requireOauth('git_bridge')`（`services/web/app/src/Features/Authentication/AuthenticationController.mjs:409-450`）驗證 bearer 權杖：用於 git-bridge 的 API 路由（`services/web/modules/git-bridge/app/src/GitBridgeRouter.mjs:33-59`）與 MCP 端點（`services/web/modules/mcp-server/app/src/McpRouter.mjs:16-22`）。拒絕已過期的權杖以及被停權或已刪除使用者的權杖。 |
| `OAuthPersonalAccessTokenManager.mjs:13-50` (`listTokens`, `getUserTokenNums`) | 為設定頁面列出使用者的權杖（`GET /oauth/personal-access-tokens`），並計算數量以檢查上限。 |
| `AdminUserListManager.mjs:388-400` (module `admin-tools`) | 在管理面板中顯示使用者權杖的前綴。 |

#### 索引

| 名稱 | 鍵 | 選項 | 遷移 |
| - | - | - | - |
| `refreshToken_1` | `{ refreshToken: 1 }` | 唯一，部分索引：`refreshToken` 存在 | `20230405190240_oauth_refresh_tokens_index.mjs` |
| `expiresAt_1` | `{ expiresAt: 1 }` | TTL，`expireAfterSeconds: 0`，部分索引：`expiresAt` 存在 | `20230406125632_oauth_tokens_ttl.mjs` |
| `user_id_1_type_1` | `{ user_id: 1, type: 1 }` | | `20250321160345_add_type_to_pat_user_id_index.mjs`（取代 `20250115110745_oauth_user_id_index_no_partial.mjs` 中的 `user_id_1`，後者又取代了 `20230426095212_personal_oauth_tokens_user_index.mjs` 中的 `pat_user_id_1`） |
| `accessTokenExpiresAt_1` | `{ accessTokenExpiresAt: 1 }` | TTL，`expireAfterSeconds: 86400`，部分索引：`accessTokenExpiresAt` 存在 | `20260511104500_expire_oauthAccessTokens.mjs` |

遷移位於 `tools/migrations/`。唯一索引 `accessToken_1` 僅來自標記為 `saas` 與 `server-pro` 的遷移，因此 Community Edition 中 `accessToken` 上沒有索引。

#### 備註

* 刪除使用者不會刪除其權杖。`UserDeleter` 會觸發 `cleanupPersonalAccessTokens` 掛鉤（`services/web/app/src/Features/User/UserDeleter.mjs:230-234`），但沒有模組監聽它。由於使用者已不存在，兩種權杖驗證都會拒絕這些權杖，TTL 索引會在 `accessTokenExpiresAt` 之後一天將其移除。
* 停權使用者只會結束其工作階段。權杖仍會保留，只要 `users.suspended` 為 `true`，兩種權杖驗證都會拒絕它們（`OAuth2Model.mjs:51-54`, `OAuthPersonalAccessTokenManager.mjs:129-134`）。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.