> ## 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-CN/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-CN/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.